Sargon

Rust	Kotlin	Swift	Average

Sargon is library for sharing code between Radix iOS/Android wallets.

Important

This library is intended for internal use only in the official iOS and Android wallets. Interfaces will be changing regularly, and we do not recommend other developers integrate the library or align with these standards.

Etymology

Named after Sargon of Akkad the first ruler of the Akkadian Empire, the first empire of Mesopotamia. Babylon was a city in southern Mesopotamia, and of course the name of the Radix milestone with which the Radix wallets was launched.

Development

Setup

We recommend installing the Radix Transaction Manifest Extension for VS Code if you use that IDE

Snippets

For VS Code IDE users, we recommend installing the Rust snippet vendored with this repo:

./scripts/install_snippets.sh

Swift

xcode-select --install

Or install Xcode from App Store

After installing, you should run the following command to verify the SDK path is set to the Xcode app under Applications.

$ xcrun --show-sdk-path
/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk

If it doesn't point to the expected path (and instead points to something like /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk), make sure you have the PATH exported on your profile (e.g. .zshrc):

export PATH="/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"

Kotlin

brew install kotlin

pre-commit

Recommended to use pre-commit tool

brew install pre-commit

This repo contains a .pre-commit-config.yaml which uses the amazing typos tool, you MUST INSTALL the config, do it by:

pre-commit install

direnv

Install direnv to automatically load env variables when you change directory to Sargon dir. This repo contains an .envrc which exports RUST_LOG=info so that logs are shown when running unit tests. When you run cargo test those logs will show up. Prefer using nextest below if you dont wanna see logs, and want prettier test result output.

nextest

Nextest is a nice test runner for Rust!

cargo install cargo-nextest

Code coverage

Recommended to use tarpaulin tool for code coverage:

cargo install cargo-tarpaulin

And then run:

cargo tarpaulin --out Html

Run Tests

cargo nextest run

Build local

iOS

Prerequisites

Rust targets for iOS

rustup target add aarch64-apple-ios aarch64-apple-ios-sim

Rust targets (macOS)

rustup target add aarch64-apple-darwin

Build

Find script here

./scripts/ios/build-ios.sh

Test Swift

Find script here

Code coverage

Details

./scripts/ios/test.sh

Summary

./scripts/ios/test.sh --summary

Test only

./scripts/ios/test.sh --testonly

Export code coverage

If you change lcov format in export_code.cov.sh please use an updated file name.

./scripts/ios/test.sh --codecov swift_code_cov.lcov

Alternatively if you wanna skip code cove

Android

Prerequisites

MacOs

• Install jenv

  brew install jenv

  Dont forget to add to eval to zsh

  export PATH="$HOME/.jenv/bin:$PATH"
  eval "$(jenv init -)"

• Install Java (openjdk@17)

  brew install openjdk@17

  Add openjdk version to jenv

  jenv add /opt/homebrew/Cellar/openjdk@17/17.0.10/libexec/openjdk.jdk/Contents/Home/

• cargo-ndk

  cargo install cargo-ndk

• Download the Command Line tools here and unzip

  mkdir -p ~/Library/Android/sdk/cmdline-tools
  mv <download/path>/cmdline-tools ~/Library/Android/sdk/cmdline-tools/latest

  ## In your profile (like .zshrc)
  export ANDROID_HOME=$HOME/Library/Android/sdk
  export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin
  export PATH=$PATH:$ANDROID_HOME/platform-tools
  # Make sure to also include the SDK ROOT in order to build the mac os desktop binaries
  export SDKROOT="`xcrun --show-sdk-path`

  ## Source your profile 
  source ~/.zshrc

  ## Assert that it works with
  sdkmanager --version

• Download the latest ndk

  ## Print the list of available ANDKs
  sdkmanager --list | grep ndk

  ## Install the latest ndk like ndk;27.1.12297006 
  sdkmanager --install "ndk;<version.of.ndk>"

  ## Export ndk 
  ## In your profile (like .bashrc, or .zshrc etc)
  export ANDROID_NDK_HOME=$ANDROID_HOME/ndk

Linux

• (Optional) Install build essentials

  apt-get install build-essential
  apt-get install cmake

• Install Java (openjdk-17)

  apt-get install openjdk-17-jre

• cargo-ndk

  cargo install cargo-ndk

• Download the Command Line tools here and unzip

  mkdir -p ~/Library/Android/sdk/cmdline-tools
  mv <download/path>/cmdline-tools ~/Library/Android/sdk/cmdline-tools/latest

  ## In your profile (like .zshrc)
  export ANDROID_HOME=$HOME/Library/Android/sdk
  export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin
  export PATH=$PATH:$ANDROID_HOME/platform-tools

  ## Source your profile 
  source ~/.bashrc

  ## Assert that it works with
  sdkmanager --version

• Download the latest ndk

  ## Print the list of available ANDKs
  sdkmanager --list | grep ndk

  ## Install the latest ndk like ndk;27.1.12297006 
  sdkmanager --install "ndk;<version.of.ndk>"

  ## Export ndk 
  ## In your profile (like .bashrc, or .zshrc etc)
  export ANDROID_NDK_HOME=$ANDROID_HOME/ndk

Install Rust targets (Android)

rustup target add aarch64-linux-android armv7-linux-androideabi

Install Rust targets (Desktop Binaries)

MacOs

rustup target add aarch64-apple-darwin

Linux

rustup target add x86_64-unknown-linux-gnu

Build

cd jvm
# (Debug)
./gradlew sargon-android:assembleDebug
# (Release)
./gradlew sargon-android:assembleRelease

Unit Tests (Running locally)

./gradlew sargon-android:testDebugUnitTest

Instrumentation Tests (Running on a device)

# Make sure you have a device or emulator is connected to ADB
./gradlew sargon-android:connectedDebugAndroidTest

Release

iOS

Locally

Prerequisites

Important

You will need the prerequisites of Build local above.

Install gh

brew install gh

Github PAT

Create a Github Personal Access Token (PAT) labeled "Classic" and give it these permissions: write:packages admin:org -> read:org

Manually release

For the first time, you must:

gh auth login

Do this:

? What account do you want to log into? GitHub.com
? What is your preferred protocol for Git operations on this host? SSH
? Upload your SSH public key to your GitHub account? Skip
? How would you like to authenticate GitHub CLI? Paste an authentication token
Tip: you can generate a Personal Access Token here https://github.com/settings/tokens
The minimum required scopes are 'repo', 'read:org'.
? Paste your authentication token: ****************************************

If successful you should see:

- gh config set -h github.com git_protocol ssh
✓ Configured git protocol
✓ Logged in as <YOUR_GH_USERNAME>

Find script here

./scripts/ios/release.sh

CD

See .github/workflows/release.yml

Android

Locally

In order to build sargon for local development we will leverage the local maven repository. Instead of publishing the package in a maven server, we can publish it locally.

In order to publish both android and desktop binaries with a simple command run

cd jvm/
./gradlew sargon-android:buildForLocalDev  // This builds both sargon-android and sargon-desktop-bins

This will produce the following message when successfully finished

> Task :sargon-android:buildForLocalDev
✅ Library is published in maven local with version:
1.1.19-c74d9cbf-SNAPSHOT

Note that such local maven builds are in debug mode and have a -SNAPSHOT suffix.

Copy the version name to your project but make sure that mavenLocal() is included in your project's settings.gradle

dependencyResolutionManagement {
    ...
    repositories {
        mavenLocal()
        ...
    }
}

Tip

The libraries that are published in local maven will reside in:

$HOME/.m2/repository/com/radixdlt/sargon

CD

Two modules are published in Github's maven.

• sargon-android

  (See .github/workflows/release-android.yml)

  Contains the generated UniFFi Kotlin code and the runtime sargon binaries, in different architectures. It also contains the JNA dependency.

  Import with:

  implementation("com.radixdlt.sargon:sargon-android:<version>")
  

• sargon-desktop-bins

  (See .github/workflows/release-desktop-bins.yml)

  Contains only the runtime sargon binaries, built for desktop. Used when running Unit tests.

  Import with:

  testRuntimeOnly("com.radixdlt.sargon:sargon-desktop-bins:<version>")
  

Important

Currently only supporting aarch64-apple-darwin (apple silicon) and x86_64-unknown-linux-gnu. So when running Unit tests for your client app, make sure to run them on an apple silicon or linux machine. We can add more architectures in the future, if requested.

Example apps

iOS

See iOS example app in examples/iOS

Android

See Android example app in examples/android

Import the /jvm directory in Android Studio and run the android configuration.