{"id":18938747,"url":"https://github.com/airgap-it/beacon-android-sdk","last_synced_at":"2025-04-15T19:30:32.564Z","repository":{"id":59218856,"uuid":"303679512","full_name":"airgap-it/beacon-android-sdk","owner":"airgap-it","description":"The beacon sdk allows Android developers of dApps and wallets on Tezos to implement the wallet interaction standard tzip-10.","archived":false,"fork":false,"pushed_at":"2025-03-24T15:04:15.000Z","size":1742,"stargazers_count":11,"open_issues_count":4,"forks_count":8,"subscribers_count":7,"default_branch":"develop","last_synced_at":"2025-03-24T16:23:34.493Z","etag":null,"topics":["beacon","beacon-sdk","dapps","tezos","wallet"],"latest_commit_sha":null,"homepage":"https://walletbeacon.io","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/airgap-it.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-10-13T11:23:41.000Z","updated_at":"2025-03-24T15:04:18.000Z","dependencies_parsed_at":"2025-03-24T16:22:43.863Z","dependency_job_id":"d7270861-de8b-4d7a-9636-e2d1e00eb708","html_url":"https://github.com/airgap-it/beacon-android-sdk","commit_stats":null,"previous_names":[],"tags_count":39,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/airgap-it%2Fbeacon-android-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/airgap-it%2Fbeacon-android-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/airgap-it%2Fbeacon-android-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/airgap-it%2Fbeacon-android-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/airgap-it","download_url":"https://codeload.github.com/airgap-it/beacon-android-sdk/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249138536,"owners_count":21218904,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["beacon","beacon-sdk","dapps","tezos","wallet"],"created_at":"2024-11-08T12:15:20.928Z","updated_at":"2025-04-15T19:30:32.548Z","avatar_url":"https://github.com/airgap-it.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Beacon Android SDK\n\n[![stable](https://img.shields.io/github/v/tag/airgap-it/beacon-android-sdk?label=stable\u0026sort=semver)](https://github.com/airgap-it/beacon-android-sdk/releases)\n[![latest](https://img.shields.io/github/v/tag/airgap-it/beacon-android-sdk?color=orange\u0026include_prereleases\u0026label=latest)](https://github.com/airgap-it/beacon-android-sdk/releases)\n[![release](https://img.shields.io/jitpack/v/github/airgap-it/beacon-android-sdk)](https://jitpack.io/#airgap-it/beacon-android-sdk)\n[![documentation](https://img.shields.io/badge/documentation-online-brightgreen.svg)](https://docs.walletbeacon.io/wallet/getting-started/android/installation)\n[![license](https://img.shields.io/github/license/airgap-it/beacon-android-sdk)](https://github.com/airgap-it/beacon-android-sdk/blob/master/LICENSE)\n\n\u003e Connect Wallets with dApps on Tezos\n\n[Beacon](https://walletbeacon.io) is an implementation of the wallet interaction standard [tzip-10](https://gitlab.com/tzip/tzip/blob/master/proposals/tzip-10/tzip-10.md) which describes the connection of a dApp with a wallet.\n\n## About\n\nThe `Beacon Android SDK` provides Android developers with tools useful for setting up communication between native wallets supporting Tezos and dApps that implement [`beacon-sdk`](https://github.com/airgap-it/beacon-sdk).\n\n## Installation\n\nTo add `Beacon Android SDK` into your project:\n\n  1. Make sure the [JitPack](https://jitpack.io/) repository is included in your root `build.gradle` file:\n\n  #### Groovy\n  ```groovy\n  allprojects {\n    repositories {\n      ...\n      maven { url 'https://jitpack.io' }\n    }\n  }\n  ```\n\n  #### Kotlin\n  ```kotlin\n  allprojects {\n    repositories {\n      ...\n      maven(\"https://jitpack.io\")\n    }\n  }\n  ```\n\n  2. Add the dependencies:\n\n  #### Groovy\n  ```groovy\n  dependencies {\n    def beacon_version = \"x.y.z\"\n\n    // REQUIRED, core\n    implementation \"com.github.airgap-it.beacon-android-sdk:core:$beacon_version\"\n\n    // optional, client-dapp\n    implementation \"com.github.airgap-it.beacon-android-sdk:client-dapp:$beacon_version\"\n  \n    // optional, client-wallet\n    implementation \"com.github.airgap-it.beacon-android-sdk:client-wallet:$beacon_version\"\n    // optional, client-wallet-compat\n    implementation \"com.github.airgap-it.beacon-android-sdk:client-wallet-compat:$beacon_version\"\n  \n    // optional, blockchain-substrate\n    implementation \"com.github.airgap-it.beacon-android-sdk:blockchain-substrate:$beacon_version\"\n    // optional, blockchain-tezos\n    implementation \"com.github.airgap-it.beacon-android-sdk:blockchain-tezos:$beacon_version\"\n  \n    // optional, transport-p2p-matrix\n    implementation \"com.github.airgap-it.beacon-android-sdk:transport-p2p-matrix:$beacon_version\"\n  \n    ---\n\n    // alternatively, all modules\n    implementation \"com.github.airgap-it:beacon-android-sdk:$beacon_version\"\n    \n    \n    // REQUIRED\n    def jna_version = \"x.y.z\"\n    \n    implementation \"net.java.dev.jna:jna:$jna_version@aar\"\n  }\n  ```\n\n  #### Kotlin\n  ```kotlin\n  dependencies {\n    val beaconVersion = \"x.y.z\"\n  \n    // REQUIRED, core\n    implementation(\"com.github.airgap-it.beacon-android-sdk:core:$beaconVersion\")\n\n    // optional, client-dapp\n    implementation(\"com.github.airgap-it.beacon-android-sdk:client-dapp:$beaconVersion\")\n  \n    // optional, client-wallet\n    implementation(\"com.github.airgap-it.beacon-android-sdk:client-wallet:$beaconVersion\")\n    // optional, client-wallet-compat\n    implementation(\"com.github.airgap-it.beacon-android-sdk:client-wallet-compat:$beaconVersion\")\n  \n    // optional, blockchain-substrate\n    implementation(\"com.github.airgap-it.beacon-android-sdk:blockchain-substrate:$beaconVersion\")\n    // optional, blockchain-tezos\n    implementation(\"com.github.airgap-it.beacon-android-sdk:blockchain-tezos:$beaconVersion\")\n  \n    // optional, transport-p2p-matrix\n    implementation(\"com.github.airgap-it.beacon-android-sdk:transport-p2p-matrix:$beaconVersion\")\n  \n    ---\n  \n    // alternatively, all modules\n    implementation(\"com.github.airgap-it:beacon-android-sdk:$beaconVersion\")\n  }\n  ```\n### Proguard and R8\n\n`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:\n\n- [ProGuard rules for Kotlin Serialization](https://github.com/Kotlin/kotlinx.serialization#android)\n- [ProGuard rules for LazySodium](https://github.com/terl/lazysodium-java/wiki/installation#proguard)\n\n### Troubleshooting\n\nSee the list of known issues and how to fix them if you run into problems after adding the dependencies.\n\n- `Native library (com/sun/jna/xxxxx/libjnidispatch.so) not found in resource path`\n\n    Add the `\"net.java.dev.jna:jna:x.y.z@aar\"` dependency **and exclude the `net.java.dev.jna` group from the Beacon dependencies**.\n  \n    #### Groovy\n    ```groovy\n    def withoutJna = { exclude group: \"net.java.dev.jna\" }\n    \n    implementation \"com.github.airgap-it.beacon-android-sdk:core:$beacon_version\", withoutJna\n    implementation \"com.github.airgap-it.beacon-android-sdk:client-wallet:$beacon_version\", withoutJna \n    ...\n  \n    def jna_version = \"5.9.0\"\n    \n    implementation \"net.java.dev.jna:jna:$jna_version@aar\"\n    ```\n  \n    #### Kotlin\n    ```kotlin\n    fun ModuleDependency.excludeJna(): ModuleDependency = apply {\n        exclude(group = \"net.java.dev.jna\")\n    }\n    \n    implementation(\"com.github.airgap-it.beacon-android-sdk:core:$beaconVersion\") { withoutJna() }\n    implementation(\"com.github.airgap-it.beacon-android-sdk:client-wallet:$beaconVersion\") { withoutJna() }\n    ...\n    \n    val jnaVersion = \"5.9.0\"\n  \n    implementation(\"net.java.dev.jna:jna:$jnaVersion@aar\")\n    ```\n\n## Documentation\n\nThe documentation can be found [here](https://docs.walletbeacon.io/).\n\n## Project Overview\n\nThe project consists of the following modules:\n\n### Core\n\nCore modules are the basis for other modules. They are required for the SDK to work as expected.\n\n| Module  | Description            | Dependencies | Required by                                                                                                                                          |\n| ------- | ---------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `:core` | Base for other modules | ✖️           | `:client-wallet` \u003cbr /\u003e `:client-wallet-compat` \u003cbr /\u003e\u003cbr /\u003e `:blockchain-substrate` \u003cbr /\u003e `:blockchain-tezos` \u003cbr /\u003e\u003cbr /\u003e `:transport-p2p-matrix` |\n\n### Client\n\nClient modules ship with Beacon implementations for different parts of the network.\n\n| Module                  | Description                                                                                                                                | Dependencies                    | Required by             |\n| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- | ----------------------- |\n| `:client-dapp`          | Beacon implementation for dApps                                                                                                            | `:core`                         | ✖️                      |\n| `:client-wallet`        | Beacon implementation for wallets                                                                                                          | `:core`                         | `:client-wallet-compat` |\n| `:client-wallet-compat` | Provides a supplementary interface for `:client-wallet` for use without [Coroutines](https://kotlinlang.org/docs/coroutines-overview.html) | `:core` \u003cbr /\u003e `:client-wallet` | ✖️                      |\n\n### Blockchain\n\nBlockchain modules provide support for different blockchains.\n\n| Module                  | Description                   | Dependencies | Required by |\n| ----------------------- | ----------------------------- | ------------ | ----------- |\n| `:blockchain-substrate` | Substrate specific components | `:core`      | ✖️          |\n| `:blockchain-tezos`     | Tezos specific components     | `:core`      | ✖️          |\n\n### Transport\n\nTransport modules provide various interfaces used to establish connection between Beacon clients.\n\n| Module                  | Description                                                                              | Dependencies | Required by |\n| ----------------------- | ---------------------------------------------------------------------------------------- | ------------ | ----------- |\n| `:transport-p2p-matrix` | Beacon P2P implementation which uses [Matrix](https://matrix.org/) for the communication | `:core`      | ✖️          |\n\n### Demo\n\nDemo modules provide examples of how to use the library. \n\n| Module  | Description         |\n| ------- | ------------------- |\n| `:demo` | Example application |\n\n## Examples\n\nThe snippets below show how to quickly setup a wallet listening for incoming Beacon messages in Kotlin with coroutines. \n\nFor more examples or examples of how to use the SDK without coroutines or in Java, please see our `demo` app (WIP).\n\n### Create a Beacon wallet client and listen for incoming requests\n\n```kotlin\nimport it.airgap.beaconsdk.blockchain.substrate.substrate\nimport it.airgap.beaconsdk.blockchain.tezos.tezos\nimport it.airgap.beaconsdk.client.wallet.BeaconWalletClient\nimport it.airgap.beaconsdk.transport.p2p.matrix.p2pMatrix\n\nclass MainActivity : AppCompatActivity() {\n  lateinit var client: BeaconWalletClient\n\n  // ...\n\n  suspend fun listenForBeaconMessages() {\n    // create a wallet Beacon client that can listen for Substrate and Tezos messages via Matrix network \n    client = BeaconWalletClient(\"My App\") {\n        support(substrate(), tezos())    \n        use(p2pMatrix())\n    }\n\n    myCoroutineScope.launch {\n      // subscribe to a message Flow\n      client.connect().collect { /* process messages */ }\n    }\n  }\n}\n```\n\n## Migration\n\nSee the below guides to learn how to migrate your existing code to new `Beacon Android SDK` versions.\n\n### From \u003cv3.0.0\n\nAs 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.\nThis 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.\nTo 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:\n\n1. Remove the old dependency and add `core`, `client-wallet`, `blockchain-tezos` and `transport-p2p-matrix` modules.\n\n```groovy\ndef beaconVersion = \"3.0.0\"\n\n/* \u003cv3.0.0: implementation \"com.github.airgap-it:beacon-android-sdk:$beaconVersion\" */\n\nimplementation \"com.github.airgap-it.beacon-android-sdk:core:$beaconVersion\"\n\nimplementation \"com.github.airgap-it.beacon-android-sdk:client-wallet:$beaconVersion\"\nimplementation \"com.github.airgap-it.beacon-android-sdk:blockchain-tezos:$beaconVersion\"\nimplementation \"com.github.airgap-it.beacon-android-sdk:transport-p2p-matrix:$beaconVersion\"\n```\n\n2. Replace the old `BeaconClient` with the new `BeaconWalletClient` (`client-wallet`) and configure it with `Tezos` blockchain (`blockchain-tezos`) and `P2pMatrix` transport (`transport-p2p-matrix`).\n```kotlin\nimport it.airgap.beaconsdk.blockchain.tezos.tezos\nimport it.airgap.beaconsdk.client.wallet.BeaconWalletClient\nimport it.airgap.beaconsdk.core.data.P2P\nimport it.airgap.beaconsdk.transport.p2p.matrix.p2pMatrix\n\n/* \u003cv3.0.0: val client = BeaconClient(\"MyApp\") */\nval client = BeaconWalletClient(\"MyApp\") {\n    support(tezos())    \n    use(P2P(p2pMatrix())) \n}\n```\n\n3. Adjust the message handling code.\n```kotlin\n/* \u003cv3.0.0:\n * when (beaconRequest) {\n *    is PermissionBeaconRequest -\u003e { ... }\n *    is OperationBeaconRequest -\u003e { ... }\n *    is SignPayloadBeaconRequest -\u003e { ... }\n *    is BroadcastBeaconRequest -\u003e { ... } \n * }\n */\n\nimport it.airgap.beaconsdk.blockchain.tezos.message.request.PermissionTezosRequest\nimport it.airgap.beaconsdk.blockchain.tezos.message.request.BroadcastTezosRequest\nimport it.airgap.beaconsdk.blockchain.tezos.message.request.OperationTezosRequest\nimport it.airgap.beaconsdk.blockchain.tezos.message.request.SignPayloadTezosRequest\n\nwhen (beaconRequest) {\n    is PermissionTezosRequest -\u003e { /* ... */ }\n    is OperationTezosRequest -\u003e { /* ... */ }\n    is SignPayloadTezosRequest -\u003e { /* ... */ }\n    is BroadcastTezosRequest -\u003e { /* ... */ }\n    else -\u003e { /* ... */ }\n}\n```\n\n```kotlin\n/* \u003cv3.0.0:\n * val response = OperationBeaconResponse.from(\n *    operationRequest, //: OperationBeaconRequest \n *    transactionHash,\n * ) \n */\nimport it.airgap.beaconsdk.blockchain.tezos.message.response.OperationTezosResponse\n        \nval response = OperationTezosResponse.from(\n    blockchainBeaconRequest, //: OperationTezosRequest \n    transactionHash,\n)\n```\n```kotlin\n/* \u003cv3.0.0:\n * val errorResponse = ErrorBeaconResponse.from(\n *    broadcastRequest, //: BroadcastBeaconRequest \n *    BeaconError.BroadcastError,\n * ) \n */\n\nimport it.airgap.beaconsdk.blockchain.tezos.data.TezosError\n\nval errorResponse = ErrorBeaconResponse.from(\n    broadcastRequest, //: BroadcastTezosRequest\n    TezosError.BroadcastError,\n)\n```\n\n## Development\n\nThe project is built with [Gradle](https://gradle.org/).\n\n\n### Product Flavors\nThere are the following product flavors configured:\n\n- `prod` - the production ready version\n- `mock` - provides mock implementations, used only for unit tests\n\n### Build\n\n#### Android Studio\n\nBefore building the project in Android Studio make sure the active build variant uses the `prod` flavor.\n\n#### Command Line\n\nBuild all modules:\n```\n$ ./gradlew assembleProd\n```\n\nBuild a single module:\n```\n$ ./gradlew :${module}:assembleProd\n```\n\n### Run Tests\n\n#### Android Studio\n\nBefore running the tests in Android Studio make sure the active build variant uses the `mock` flavor.\n\n#### Command Line\n\n```\n$ ./gradlew testMock{Release|Debug}UnitTest\n```\n\n---\n## Related Projects\n\n### AirGap Projects\n\n[Beacon SDK](https://github.com/airgap-it/beacon-sdk) - an SDK for web developers\n\n[Beacon iOS SDK](https://github.com/airgap-it/beacon-ios-sdk) - an SDK for iOS developers\n\n### Community Projects\n\n[Beacon Flutter SDK](https://github.com/TalaoDAO/beacon) - an SDK for Flutter developers\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fairgap-it%2Fbeacon-android-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fairgap-it%2Fbeacon-android-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fairgap-it%2Fbeacon-android-sdk/lists"}