Beacon Android SDK
Connect Wallets with dApps on Tezos
Beacon is an implementation of the wallet interaction standard tzip-10 which describes the connection of a dApp with a wallet.
About
The Beacon Android SDK
provides Android developers with tools useful for setting up communication between native wallets supporting Tezos and dApps that implement beacon-sdk
.
Installation
To add Beacon Android SDK
into your project:
- Make sure the JitPack repository is included in your root
build.gradle
file:
Groovy
allprojects {
repositories {
...
maven { url 'https://jitpack.io' }
}
}
Kotlin
allprojects {
repositories {
...
maven("https://jitpack.io")
}
}
- Add the dependencies:
Groovy
dependencies {
def beacon_version = "x.y.z"
// REQUIRED, core
implementation "com.github.airgap-it.beacon-android-sdk:core:$beacon_version"
// optional, client-dapp
implementation "com.github.airgap-it.beacon-android-sdk:client-dapp:$beacon_version"
// optional, client-wallet
implementation "com.github.airgap-it.beacon-android-sdk:client-wallet:$beacon_version"
// optional, client-wallet-compat
implementation "com.github.airgap-it.beacon-android-sdk:client-wallet-compat:$beacon_version"
// optional, blockchain-substrate
implementation "com.github.airgap-it.beacon-android-sdk:blockchain-substrate:$beacon_version"
// optional, blockchain-tezos
implementation "com.github.airgap-it.beacon-android-sdk:blockchain-tezos:$beacon_version"
// optional, transport-p2p-matrix
implementation "com.github.airgap-it.beacon-android-sdk:transport-p2p-matrix:$beacon_version"
---
// alternatively, all modules
implementation "com.github.airgap-it:beacon-android-sdk:$beacon_version"
}
Kotlin
dependencies {
val beaconVersion = "x.y.z"
// REQUIRED, core
implementation("com.github.airgap-it.beacon-android-sdk:core:$beaconVersion")
// optional, client-dapp
implementation("com.github.airgap-it.beacon-android-sdk:client-dapp:$beaconVersion")
// optional, client-wallet
implementation("com.github.airgap-it.beacon-android-sdk:client-wallet:$beaconVersion")
// optional, client-wallet-compat
implementation("com.github.airgap-it.beacon-android-sdk:client-wallet-compat:$beaconVersion")
// optional, blockchain-substrate
implementation("com.github.airgap-it.beacon-android-sdk:blockchain-substrate:$beaconVersion")
// optional, blockchain-tezos
implementation("com.github.airgap-it.beacon-android-sdk:blockchain-tezos:$beaconVersion")
// optional, transport-p2p-matrix
implementation("com.github.airgap-it.beacon-android-sdk:transport-p2p-matrix:$beaconVersion")
---
// alternatively, all modules
implementation("com.github.airgap-it:beacon-android-sdk:$beaconVersion")
}
Proguard and R8
Beacon Android SDK
internally uses various libraries that may require custom ProGuard rules. If you're using ProGuard or R8, please follow the guides listed below to make sure your app works correctly after obfuscation:
Troubleshooting
See the list of known issues and how to fix them if you run into problems after adding the dependencies.
-
Native library (com/sun/jna/xxxxx/libjnidispatch.so) not found in resource path
Add the
"net.java.dev.jna:jna:x.y.z@aar"
dependency and exclude thenet.java.dev.jna
group from the Beacon dependencies.Groovy
def withoutJna = { exclude group: "net.java.dev.jna" } implementation "com.github.airgap-it.beacon-android-sdk:core:$beacon_version", withoutJna implementation "com.github.airgap-it.beacon-android-sdk:client-wallet:$beacon_version", withoutJna ... def jna_version = "5.9.0" implementation "net.java.dev.jna:jna:$jna_version@aar"
Kotlin
fun ModuleDependency.excludeJna(): ModuleDependency = apply { exclude(group = "net.java.dev.jna") } implementation("com.github.airgap-it.beacon-android-sdk:core:$beaconVersion") { withoutJna() } implementation("com.github.airgap-it.beacon-android-sdk:client-wallet:$beaconVersion") { withoutJna() } ... val jnaVersion = "5.9.0" implementation("net.java.dev.jna:jna:$jnaVersion@aar")
Documentation
The documentation can be found here.
Project Overview
The project consists of the following modules:
Core
Core modules are the basis for other modules. They are required for the SDK to work as expected.
Module | Description | Dependencies | Required by |
---|---|---|---|
:core |
Base for other modules | :client-wallet :client-wallet-compat :blockchain-substrate :blockchain-tezos :transport-p2p-matrix |
Client
Client modules ship with Beacon implementations for different parts of the network.
Module | Description | Dependencies | Required by |
---|---|---|---|
:client-dapp |
Beacon implementation for dApps | :core |
|
:client-wallet |
Beacon implementation for wallets | :core |
:client-wallet-compat |
:client-wallet-compat |
Provides a supplementary interface for :client-wallet for use without Coroutines |
:core :client-wallet |
Blockchain
Blockchain modules provide support for different blockchains.
Module | Description | Dependencies | Required by |
---|---|---|---|
:blockchain-substrate |
Substrate specific components | :core |
|
:blockchain-tezos |
Tezos specific components | :core |
Transport
Transport modules provide various interfaces used to establish connection between Beacon clients.
Module | Description | Dependencies | Required by |
---|---|---|---|
:transport-p2p-matrix |
Beacon P2P implementation which uses Matrix for the communication | :core |
Demo
Demo modules provide examples of how to use the library.
Module | Description |
---|---|
:demo |
Example application |
Examples
The snippets below show how to quickly setup a wallet listening for incoming Beacon messages in Kotlin with coroutines.
For more examples or examples of how to use the SDK without coroutines or in Java, please see our demo
app (WIP).
Create a Beacon wallet client and listen for incoming requests
import it.airgap.beaconsdk.blockchain.substrate.substrate
import it.airgap.beaconsdk.blockchain.tezos.tezos
import it.airgap.beaconsdk.client.wallet.BeaconWalletClient
import it.airgap.beaconsdk.transport.p2p.matrix.p2pMatrix
class MainActivity : AppCompatActivity() {
lateinit var client: BeaconWalletClient
// ...
suspend fun listenForBeaconMessages() {
// create a wallet Beacon client that can listen for Substrate and Tezos messages via Matrix network
client = BeaconWalletClient("My App") {
support(substrate(), tezos())
use(p2pMatrix())
}
myCoroutineScope.launch {
// subscribe to a message Flow
client.connect().collect { /* process messages */ }
}
}
}
Migration
See the below guides to learn how to migrate your existing code to new Beacon Android SDK
versions.
From <v3.0.0
As of v3.0.0
, not only has Beacon Android SDK
been further split into new modules, it has also become more generic in terms of supported blockchains and transports.
This means that in some parts the values that had been previously set by default now must be configured manually or that various structures have changed their location or definition.
To make sure your existing Beacon integration will be set up the same way as it used to be before v3.0.0
do the following:
- Remove the old dependency and add
core
,client-wallet
,blockchain-tezos
andtransport-p2p-matrix
modules.
def beaconVersion = "3.0.0"
/* <v3.0.0: implementation "com.github.airgap-it:beacon-android-sdk:$beaconVersion" */
implementation "com.github.airgap-it.beacon-android-sdk:core:$beaconVersion"
implementation "com.github.airgap-it.beacon-android-sdk:client-wallet:$beaconVersion"
implementation "com.github.airgap-it.beacon-android-sdk:blockchain-tezos:$beaconVersion"
implementation "com.github.airgap-it.beacon-android-sdk:transport-p2p-matrix:$beaconVersion"
- Replace the old
BeaconClient
with the newBeaconWalletClient
(client-wallet
) and configure it withTezos
blockchain (blockchain-tezos
) andP2pMatrix
transport (transport-p2p-matrix
).
import it.airgap.beaconsdk.blockchain.tezos.tezos
import it.airgap.beaconsdk.client.wallet.BeaconWalletClient
import it.airgap.beaconsdk.core.data.P2P
import it.airgap.beaconsdk.transport.p2p.matrix.p2pMatrix
/* <v3.0.0: val client = BeaconClient("MyApp") */
val client = BeaconWalletClient("MyApp") {
support(tezos())
use(P2P(p2pMatrix()))
}
- Adjust the message handling code.
/* <v3.0.0:
* when (beaconRequest) {
* is PermissionBeaconRequest -> { ... }
* is OperationBeaconRequest -> { ... }
* is SignPayloadBeaconRequest -> { ... }
* is BroadcastBeaconRequest -> { ... }
* }
*/
import it.airgap.beaconsdk.blockchain.tezos.message.request.PermissionTezosRequest
import it.airgap.beaconsdk.blockchain.tezos.message.request.BroadcastTezosRequest
import it.airgap.beaconsdk.blockchain.tezos.message.request.OperationTezosRequest
import it.airgap.beaconsdk.blockchain.tezos.message.request.SignPayloadTezosRequest
when (beaconRequest) {
is PermissionTezosRequest -> { /* ... */ }
is OperationTezosRequest -> { /* ... */ }
is SignPayloadTezosRequest -> { /* ... */ }
is BroadcastTezosRequest -> { /* ... */ }
else -> { /* ... */ }
}
/* <v3.0.0:
* val response = OperationBeaconResponse.from(
* operationRequest, //: OperationBeaconRequest
* transactionHash,
* )
*/
import it.airgap.beaconsdk.blockchain.tezos.message.response.OperationTezosResponse
val response = OperationTezosResponse.from(
blockchainBeaconRequest, //: OperationTezosRequest
transactionHash,
)
/* <v3.0.0:
* val errorResponse = ErrorBeaconResponse.from(
* broadcastRequest, //: BroadcastBeaconRequest
* BeaconError.BroadcastError,
* )
*/
import it.airgap.beaconsdk.blockchain.tezos.data.TezosError
val errorResponse = ErrorBeaconResponse.from(
broadcastRequest, //: BroadcastTezosRequest
TezosError.BroadcastError,
)
Development
The project is built with Gradle.
Product Flavors
There are the following product flavors configured:
prod
- the production ready versionmock
- provides mock implementations, used only for unit tests
Build
Android Studio
Before building the project in Android Studio make sure the active build variant uses the prod
flavor.
Command Line
Build all modules:
$ ./gradlew assembleProd
Build a single module:
$ ./gradlew :${module}:assembleProd
Run Tests
Android Studio
Before running the tests in Android Studio make sure the active build variant uses the mock
flavor.
Command Line
$ ./gradlew testMock{Release|Debug}UnitTest
Related Projects
AirGap Projects
Beacon SDK - an SDK for web developers
Beacon iOS SDK - an SDK for iOS developers
Community Projects
Beacon Flutter SDK - an SDK for Flutter developers