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"
  
  
  // REQUIRED
  def jna_version = "x.y.z"
  
  implementation "net.java.dev.jna:jna:$jna_version@aar"
}

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())) 
}

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 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

Name		Name	Last commit message	Last commit date
Latest commit History 160 Commits
.github/ISSUE_TEMPLATE		.github/ISSUE_TEMPLATE
.gitlab/issue_templates		.gitlab/issue_templates
blockchain-substrate		blockchain-substrate
blockchain-tezos		blockchain-tezos
buildSrc		buildSrc
client-dapp		client-dapp
client-wallet-compat		client-wallet-compat
client-wallet		client-wallet
core		core
demo		demo
gradle/wrapper		gradle/wrapper
transport-p2p-matrix		transport-p2p-matrix
.gitignore		.gitignore
.gitlab-ci.yml		.gitlab-ci.yml
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
build.gradle		build.gradle
gradle.properties		gradle.properties
gradlew		gradlew
gradlew.bat		gradlew.bat
jitpack.yml		jitpack.yml
settings.gradle		settings.gradle

License

airgap-it/beacon-android-sdk

Folders and files

Latest commit

History

Repository files navigation

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

About

Topics

Resources

License

Stars

Watchers

Forks

Releases 5

Packages 0

Contributors 3

Languages

Packages