Develop

.github/workflows/build-release-tags.yml

@@ -296,6 +296,39 @@ jobs:
       - name: Add Android toolchain
         if: ${{ matrix.target == 'Android' }}
         run: |
+          # Setup Android SDK
+          ANDROID_SDK_ROOT="$HOME/android-sdk"
+
+          # Download command-line tools if not present
+          if [ ! -d "$ANDROID_SDK_ROOT/cmdline-tools/latest" ]; then
+            echo "Downloading Android command-line tools..."
+            mkdir -p "$ANDROID_SDK_ROOT/cmdline-tools"
+            wget https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip -O cmdline-tools.zip
+            unzip -q cmdline-tools.zip -d "$ANDROID_SDK_ROOT/cmdline-tools"
+            mv "$ANDROID_SDK_ROOT/cmdline-tools/cmdline-tools" "$ANDROID_SDK_ROOT/cmdline-tools/latest"
+            rm cmdline-tools.zip
+          else
+            echo "Android command-line tools already exist"
+          fi
+
+          # Always accept licenses and install/update required SDK components
+          echo "Installing/updating Android SDK components..."
+          yes | "$ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager" --licenses || true
+          "$ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager" "platform-tools" "platforms;android-34" "build-tools;34.0.0"
+
+          # Set environment variables
+          echo "ANDROID_HOME=$ANDROID_SDK_ROOT" >> $GITHUB_ENV
+          echo "ANDROID_SDK_ROOT=$ANDROID_SDK_ROOT" >> $GITHUB_ENV
+          echo "$ANDROID_SDK_ROOT/platform-tools" >> $GITHUB_PATH
+          echo "$ANDROID_SDK_ROOT/cmdline-tools/latest/bin" >> $GITHUB_PATH
+
+          # Verify SDK installation
+          echo "=== Android SDK Setup ==="
+          echo "ANDROID_HOME: $ANDROID_SDK_ROOT"
+          echo "SDK contents:"
+          ls -la "$ANDROID_SDK_ROOT"
+
+          # Download and setup Android NDK
           NDK_VERSION="r27b"
           NDK_DIR="$HOME/android-ndk-$NDK_VERSION"
 
@@ -308,6 +341,8 @@ jobs:
             echo "Android NDK already exists at $NDK_DIR, skipping download"
           fi
 
+          echo "ANDROID_HOME=$ANDROID_SDK_ROOT"
+          echo "ANDROID_SDK_ROOT=$ANDROID_SDK_ROOT"
           echo "ANDROID_NDK_HOME=$NDK_DIR" >> $GITHUB_ENV
 
           rustup target add aarch64-linux-android

.github/workflows/cmake.yml

@@ -449,6 +449,39 @@ jobs:
       - name: Add Android toolchain
         if: ${{ matrix.target == 'Android' }}
         run: |
+          # Setup Android SDK
+          ANDROID_SDK_ROOT="$HOME/android-sdk"
+
+          # Download command-line tools if not present
+          if [ ! -d "$ANDROID_SDK_ROOT/cmdline-tools/latest" ]; then
+            echo "Downloading Android command-line tools..."
+            mkdir -p "$ANDROID_SDK_ROOT/cmdline-tools"
+            wget https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip -O cmdline-tools.zip
+            unzip -q cmdline-tools.zip -d "$ANDROID_SDK_ROOT/cmdline-tools"
+            mv "$ANDROID_SDK_ROOT/cmdline-tools/cmdline-tools" "$ANDROID_SDK_ROOT/cmdline-tools/latest"
+            rm cmdline-tools.zip
+          else
+            echo "Android command-line tools already exist"
+          fi
+
+          # Always accept licenses and install/update required SDK components
+          echo "Installing/updating Android SDK components..."
+          yes | "$ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager" --licenses || true
+          "$ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager" "platform-tools" "platforms;android-34" "build-tools;34.0.0"
+
+          # Set environment variables
+          echo "ANDROID_HOME=$ANDROID_SDK_ROOT" >> $GITHUB_ENV
+          echo "ANDROID_SDK_ROOT=$ANDROID_SDK_ROOT" >> $GITHUB_ENV
+          echo "$ANDROID_SDK_ROOT/platform-tools" >> $GITHUB_PATH
+          echo "$ANDROID_SDK_ROOT/cmdline-tools/latest/bin" >> $GITHUB_PATH
+
+          # Verify SDK installation
+          echo "=== Android SDK Setup ==="
+          echo "ANDROID_HOME: $ANDROID_SDK_ROOT"
+          echo "SDK contents:"
+          ls -la "$ANDROID_SDK_ROOT"
+
+          # Download and setup Android NDK
           NDK_VERSION="r27b"
           NDK_DIR="$HOME/android-ndk-$NDK_VERSION"
 
@@ -459,6 +492,8 @@ jobs:
             rm ndk.zip
           fi
 
+          echo "ANDROID_HOME=$ANDROID_SDK_ROOT" >> $GITHUB_ENV
+          echo "ANDROID_SDK_ROOT=$ANDROID_SDK_ROOT" >> $GITHUB_ENV
           echo "ANDROID_NDK_HOME=$NDK_DIR" >> $GITHUB_ENV
 
           rustup target add aarch64-linux-android

.gitignore

@@ -73,4 +73,67 @@ CRDT.Datastore.TEST/
 #Data files for deepseek test
 example/BpeTokenizer/data/**/*.mnn
 example/BpeTokenizer/data/**/*.mnn.weight
-example/BpeTokenizer/data/**/*.json
+example/BpeTokenizer/data/**/*.json
+
+# Local environment / secrets — never commit
+.env
+.env.*
+!.env.example
+examples/.env
+examples/.env.*
+!examples/.env.example
+
+# Build outputs
+build/
+
+# macOS
+.DS_Store
+
+# Test log files
+/tmp/eth_watch_*.log
+examples/*.log
+
+# User-specific stuff
+.idea/**/workspace.xml
+.idea/**/tasks.xml
+.idea/**/usage.statistics.xml
+.idea/**/dictionaries
+.idea/**/shelf
+
+# github copilot
+.idea/**/copilot*
+# AWS User-specific
+.idea/**/aws.xml
+
+# Generated files
+.idea/**/contentModel.xml
+
+# Sensitive or high-churn files
+.idea/**/dataSources/
+.idea/**/dataSources.ids
+.idea/**/dataSources.local.xml
+.idea/**/sqlDataSources.xml
+.idea/**/dynamic.xml
+.idea/**/uiDesigner.xml
+.idea/**/dbnavigator.xml
+
+# CMake
+cmake-build-*/
+
+# File-based project format
+*.iws
+
+# IntelliJ
+out/
+
+# Android studio 3.1+ serialized cache file
+.idea/caches/build_file_checksums.ser
+
+### CLion+iml Patch ###
+# Reason: https://github.com/joeblau/gitignore.io/issues/186#issuecomment-249601023
+
+*.iml
+modules.xml
+.idea/misc.xml
+*.ipr
+

.gitmodules

@@ -14,3 +14,6 @@
 [submodule "docs"]
 	path = docs
 	url = ../sg-docs
+[submodule "evmrelay"]
+	path = evmrelay
+	url = ../evmrelay

AgentDocs/CLAUDE.md

@@ -61,10 +61,15 @@ Your default mode is “tiny, surgical insertion into existing code”.
 - Always run the linter before committing.
 - Always run the formatter before committing.
 - Always run the build before committing.
-- Always run in interactive mode with the user on a step by step basis
+- Always run in interactive mode with the user on a step-by-step basis
 - Always look in AgentDocs for other instructions.
     - The files can include SPRINT_PLAN.md, Architecture.md, CHECKPOINT.md, AGENT_MISTAKES.md
-
+- Always look in AgentDocs for other instructions.
+    - The files can include SPRINT_PLAN.md, Architecture.md, CHECKPOINT.md, AGENT_MISTAKES.md
+- Always make sure to only use C++17 features and below.
+    - For instance boost::coroutines only work in C++20, do NOT use it.
+    - Make sure not to use other C++ versions' features above C++17
+
 ## Build Commands
 
 > **See `README.md` → "Building the Project" for the full authoritative build instructions.**

build/Android/CMakeLists.txt

@@ -49,8 +49,14 @@ set(PROTOC_EXECUTABLE "${_THIRDPARTY_BUILD_DIR}/protobuf_host/bin/protoc${CMAKE_
 
 set(TESTING OFF)
 
-find_library(log-lib log)
-find_library(android-lib android)
+add_library(android::log INTERFACE IMPORTED GLOBAL)
+set_target_properties(android::log PROPERTIES IMPORTED_LIBNAME "log")
+
+add_library(android::android INTERFACE IMPORTED GLOBAL)
+set_target_properties(android::android PROPERTIES IMPORTED_LIBNAME "android")
 
 # Include common build parameters
 include(../CommonBuildParameters.cmake)
+
+# Add Android AAR build for secure storage
+add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/securestorage ${CMAKE_BINARY_DIR}/android_aar)

build/Android/securestorage/.gitignore

@@ -0,0 +1,18 @@
+# Gradle build outputs
+.gradle/
+build/
+library/build/
+
+# Gradle wrapper (download on demand)
+.gradle-wrapper.jar
+gradlew
+gradlew.bat
+gradle/
+
+# Local configuration
+local.properties
+
+# IDE files
+.idea/
+*.iml
+.DS_Store

build/Android/securestorage/CMakeLists.txt

@@ -0,0 +1,33 @@
+# Android AAR build for KeyStoreHelper
+cmake_minimum_required(VERSION 3.22)
+
+# Check if Gradle wrapper exists, if not, set it up
+set(GRADLEW_PATH "${CMAKE_CURRENT_SOURCE_DIR}/gradlew")
+if(NOT EXISTS "${GRADLEW_PATH}")
+    message(STATUS "Gradle wrapper not found, running setup script...")
+    execute_process(
+        COMMAND bash ${CMAKE_CURRENT_SOURCE_DIR}/setup-gradle-wrapper.sh
+        WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+        RESULT_VARIABLE SETUP_RESULT
+    )
+    if(NOT SETUP_RESULT EQUAL 0)
+        message(FATAL_ERROR "Failed to set up Gradle wrapper. Please check your internet connection.")
+    endif()
+    message(STATUS "Gradle wrapper setup complete")
+endif()
+
+# Custom target to build the AAR using Gradle
+add_custom_target(build_android_aar ALL
+    COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/gradlew :library:assembleRelease
+    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+    COMMENT "Building securestorage AAR with Gradle"
+    BYPRODUCTS ${CMAKE_CURRENT_SOURCE_DIR}/library/build/outputs/aar/library-release.aar
+)
+
+# Install the AAR to the installation directory
+install(FILES
+    ${CMAKE_CURRENT_SOURCE_DIR}/library/build/outputs/aar/library-release.aar
+    DESTINATION lib/android
+    RENAME securestorage-release.aar
+    OPTIONAL
+)

build/Android/securestorage/README.md

@@ -0,0 +1,78 @@
+# Android Secure Storage AAR
+
+This directory contains the Android Gradle project for building the SuperGenius secure storage AAR.
+
+## Overview
+
+The AAR contains:
+- `ai.gnus.sdk.KeyStoreHelper` - Java class providing secure key storage using Android KeyStore
+
+**Source Location**: The Java source is maintained in `src/local_secure_storage/impl/KeyStoreHelper.java` and referenced by the Gradle build. This ensures a single source of truth alongside the C++ implementation.
+
+## Building
+
+### Via CMake (Recommended)
+When building the Android version of SuperGenius, the AAR will be built automatically during `make`:
+
+```bash
+cd build/OSX
+mkdir -p Android && cd Android
+cmake ../.. \
+  -DCMAKE_ANDROID_NDK=/path/to/ndk \
+  -DANDROID_ABI=arm64-v8a \
+  -DCMAKE_BUILD_TYPE=Release
+make
+make install
+```
+
+The Gradle wrapper will be set up automatically if needed during the CMake configure step.
+The AAR will be built during `make` and installed to `${CMAKE_INSTALL_PREFIX}/lib/android/securestorage-release.aar` during `make install`.
+
+### Via Gradle Directly
+You can also build the AAR directly using Gradle:
+
+```bash
+cd build/Android/securestorage
+./gradlew :library:assembleRelease
+```
+
+Output: `build/Android/securestorage/library/build/outputs/aar/library-release.aar`
+
+## Usage in Unity/GeniusSDK
+
+1. Include the AAR in your Unity project's `Assets/Plugins/Android/` directory
+2. Include your SDK `.so` file in `Assets/Plugins/Android/libs/[ABI]/`
+3. Initialize KeyStoreHelper before using native secure storage:
+
+```java
+import ai.gnus.sdk.KeyStoreHelper;
+
+public class YourUnityActivity extends UnityPlayerActivity {
+    @Override
+    protected void onCreate(Bundle savedInstanceState) {
+        super.onCreate(savedInstanceState);
+        // This must be called AFTER the native SDK .so is loaded
+        // It caches the class reference using the app's ClassLoader
+        KeyStoreHelper.initialize(this);
+    }
+}
+```
+
+**Important**: The AAR's `nativeInit` method is implemented in your SDK's `.so` file. Make sure Unity loads the native library before calling `KeyStoreHelper.initialize()`.
+
+## JNI Contract
+
+The C++ code in `src/local_secure_storage/impl/Android.cpp`:
+- Implements: `Java_ai_gnus_sdk_KeyStoreHelper_nativeInit` - Caches class reference using app ClassLoader
+- Calls these static Java methods:
+  - `ai.gnus.sdk.KeyStoreHelper.load()Ljava/lang/String;`
+  - `ai.gnus.sdk.KeyStoreHelper.save(Ljava/lang/String;)Z`
+  - `ai.gnus.sdk.KeyStoreHelper.delete(Ljava/lang/String;)Z`
+
+**ClassLoader Fix**: The native code now uses the app's ClassLoader (via the Context passed to `initialize()`) instead of the system ClassLoader, which fixes crashes when secure storage is accessed from worker threads.
+
+## Requirements
+
+- Android SDK 33
+- Min SDK 28 (Android 9.0)
+- Gradle 8.1+

build/Android/securestorage/build.gradle

@@ -0,0 +1,21 @@
+// Top-level build file
+buildscript {
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.1.0'
+    }
+}
+
+allprojects {
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+
+task clean(type: Delete) {
+    delete rootProject.buildDir
+}

build/Android/securestorage/gradle.properties

@@ -0,0 +1,4 @@
+# Project-wide Gradle settings.
+org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8
+android.useAndroidX=true
+android.enableJetifier=false