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 the net.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 and transport-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 new BeaconWalletClient (client-wallet) and configure it with Tezos blockchain (blockchain-tezos) and P2pMatrix 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())) }


3. Adjust the message handling code.
```kotlin
/* <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 version
mock - 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

airgap-it / beacon-android-sdk

readme

Beacon Android SDK

About

Installation

Groovy

Kotlin

Groovy

Kotlin

Proguard and R8

Troubleshooting

Groovy

Kotlin

Documentation

Project Overview

Core

Client

Blockchain

Transport

Demo

Examples

Create a Beacon wallet client and listen for incoming requests

Migration

From <v3.0.0

Development

Product Flavors

Build

Android Studio

Command Line

Run Tests

Android Studio

Command Line

Related Projects

AirGap Projects

Community Projects