core

Imported from avenbreaks/core (AGENTS.md). Install upstream with npx skills add avenbreaks/core. Copyright stays with the author.

AGENTS.md

Guidance for AI assistants (Claude Code, Gemini, Codex, etc.) collaborating on this repository.

Purpose & Audience

This document orients coding agents to the repo structure, development workflow, coding standards, and core architectural patterns used across Gem Wallet Core.

Project Overview

Gem Wallet Core is a Rust-based cryptocurrency wallet backend engine supporting 35+ blockchain networks. It is a Cargo workspace with 40+ crates covering transaction processing, asset management, DeFi integrations, and cross-platform mobile support.

Repository Layout

Applications (apps/)

• API Server (apps/api/): REST API with WebSocket price streaming
• Daemon (apps/daemon/): Background services for asset updates, push notifications, transaction indexing
• Parser (apps/parser/): Multi-chain transaction parsing with message queue integration
• Setup (apps/setup/): Database initialization

Cross-Platform Library (gemstone/)

Shared Rust library compiled to iOS Swift Package and Android AAR using UniFFI bindings. Contains blockchain RPC clients, swap integrations, payment URI decoding, and message signing.

• Key module: gemstone::gem_swapper — swapper module for on-device swap integrations

Blockchain Support

Individual gem_* crates for each blockchain with unified RPC client patterns:

• Bitcoin family: Bitcoin, Bitcoin Cash, Litecoin, Dogecoin
• Ethereum & L2s: Ethereum, Polygon, Arbitrum, Optimism, Base, zkSync, Linea
• Alternative L1s: Solana, Sui, TON, Aptos, NEAR, Stellar, Algorand
• Cosmos ecosystem: Cosmos Hub, Osmosis, Celestia, Injective, Sei, Noble

Core Services (selected crates)

• primitives/: Central types and models shared across the system
• storage/: Database models, migrations, and data access layer using Diesel ORM
• name_resolver/: ENS, SNS, and other naming service integrations
• gem_evm/: EVM blockchain support with unified RPC client patterns
• gem_jsonrpc/: Internal JSON-RPC client library (replaces external alloy dependencies)
• gem_client/: Client trait abstraction used across services; implementations: ReqwestClient (backend) and AlienProvider (mobile)
• serde_serializers/: Custom Serde serializers/deserializers used across crates
• security_provider/: Security provider abstractions and utilities
• gem_hypercore/: Perpetuals (perps) support via Hyperliquid integration
• fiat/: Integration with fiat providers (MoonPay, Transak, Mercuryo, Banxa)
• nft/: NFT marketplace integrations (OpenSea, Magic Eden, NFTScan)
• pricer/: Asset pricing from CoinGecko and DEX sources
• localizer/: i18n support for 20+ languages using Fluent

Technology Stack

• Framework: Rust workspace with Rocket web framework
• Database: PostgreSQL (primary), Redis (caching)
• Message Queue: RabbitMQ with Lapin
• RPC: Custom gem_jsonrpc client library for blockchain interactions
• Mobile: UniFFI for iOS/Android bindings
• Serialization: Serde with custom serializers
• Async: Tokio runtime
• Testing: Built-in Rust testing with integration tests

Development Workflow

All commands use the just task runner. Run from the workspace root unless specified.

Build

• just build: Build the workspace
• just build-gemstone: Build cross-platform library
• just gemstone build-ios: Build iOS Swift Package (run in gemstone/)
• just gemstone build-android: Build Android AAR (run in gemstone/)

Test

• just test-workspace: Run all workspace tests
• just test-all: Run all tests including integration
• just test <CRATE>: Test a specific crate
• just gemstone test-ios: Run iOS integration tests (run in gemstone/)
• cargo test --test integration_test --package <CRATE> --features <FEATURE>: Run integration tests manually

Code Quality

• just format: Format all code
• just lint: Run clippy with warnings as errors
• just fix: Auto-fix clippy issues
• just unused: Find unused dependencies with cargo-machete

Database

• just migrate: Run Diesel migrations
• just setup-services: Start Docker services (PostgreSQL, Redis, Meilisearch, RabbitMQ)

Mobile

• just gemstone install-ios-targets: Install iOS Rust targets (run in gemstone/)
• just gemstone install-android-targets: Install Android Rust targets and cargo-ndk (run in gemstone/)
• Note: Mobile builds require UniFFI bindings generation and platform-specific compilation

Utilities

• just localize: Update localization files
• just generate-ts-primitives: Generate TypeScript types from Rust
• just outdated: Check for outdated dependencies

Coding Standards

Follow the existing code style patterns unless explicitly asked to change.

Code Formatting

• Line length: 160 characters maximum (configured in rustfmt.toml)
• Indentation: 4 spaces (Rust standard)
• Imports: Automatically reordered with rustfmt
• ALWAYS run just format before committing
• Formatter enforces consistent style across all crates/workspace

Commit Messages

• Write descriptive messages following conventional commit format

Naming

• Files/modules: snake_case (e.g., asset_id.rs, chain_address.rs)
• Crates: Prefixed naming (gem_* for blockchains, security_* for security)
• Functions/variables: snake_case
• Structs/enums: PascalCase
• Constants: SCREAMING_SNAKE_CASE

Imports

1. Standard library imports first
2. External crate imports
3. Local crate imports
4. Module re-exports with pub use

IMPORTANT: Always import models and types at the top of the file. Never use inline imports inside functions (e.g., use crate::models::SomeType inside a function). Declare all imports in the file header.

Error Handling

• Use thiserror for custom error types
• Implement From traits for error conversion
• Use consistent Result<T, Error> return types
• Propagate errors with the ? operator

Database Patterns

• Separate database models from domain primitives
• Use as_primitive() methods for conversion
• Diesel ORM with PostgreSQL backend
• Support transactions and upserts

Async Patterns

• Tokio runtime throughout
• Async client structs returning Result<T, Error>
• Use Arc<tokio::sync::Mutex<T>> for shared async state

Architecture & Patterns

Key Development Patterns

• One crate per blockchain using unified RPC client patterns
• UniFFI bindings require careful Rust API design for mobile compatibility
• Use BigDecimal for financial precision
• Use async/await with Tokio across services
• Database models use Diesel ORM with automatic migrations
• Consider cross-platform performance constraints for mobile

Repository Pattern

Services access repositories through direct methods on DatabaseClient. This pattern:

• Separates data access and business logic
• Assigns each repository a specific domain (assets, devices, etc.)
• Implements all repository traits directly on DatabaseClient
• Returns primitive types from repository methods, not database models
• Simplifies the API via direct method calls

Example:

pub struct AssetsClient {
    database: Box<DatabaseClient>,
}

impl AssetsClient {
    pub fn new(database_url: &str) -> Self {
        let database = Box::new(DatabaseClient::new(database_url));
        Self { database }
    }
    
    pub fn get_asset(&mut self, id: &str) -> Result<Asset, Box<dyn Error + Send + Sync>> {
        self.database.assets().get_asset(id)
    }
    
    pub fn get_assets_by_device_id(&mut self, device_id: &str) -> Result<Vec<Asset>, Box<dyn Error + Send + Sync>> {
        let subscriptions = self.database.subscriptions().get_subscriptions_by_device_id(device_id)?;
        // ... process subscriptions
        self.database.assets().get_assets(asset_ids)
    }
}

Direct repository access methods available on DatabaseClient include:

• assets() - Asset operations
• devices() - Device operations
• subscriptions() - Subscription operations
• prices() - Price operations
• transactions() - Transaction operations
• And more...

RPC Client Patterns

• Use gem_jsonrpc::JsonRpcClient for blockchain RPC interactions
• Prefer alloy_primitives::hex::encode_prefixed() for hex encoding with 0x prefix
• Use alloy_primitives::Address::to_string() instead of manual formatting
• RPC calls expect hex strings directly; avoid double encoding
• Use JsonRpcClient::batch_call() for batch operations
• Propagate errors via JsonRpcError

Blockchain Provider Patterns

• Each blockchain crate has a provider/ directory with trait implementations
• Provider methods should fetch raw data via RPC, then call mapper functions for conversion
• Place mapper functions in separate *_mapper.rs files for clean separation
• Example: get_balance_coin() calls self.get_balance() then balances_mapper::map_coin_balance()
• This pattern ensures consistent data transformation and testability across all blockchain implementations

Testing

Conventions

• Place integration tests in tests/ directories
• Use #[tokio::test] for async tests
• Prefix test names descriptively with test_
• Use Result<(), Box<dyn std::error::Error + Send + Sync>> for test error handling
• Configure integration tests with test = false and appropriate required-features for manual execution
• Prefer real networks for RPC client tests (e.g., Ethereum mainnet)
• Test data management: For long JSON test data (>20 lines), store in testdata/ and load with include_str!(); per-crate layout is typically src/, tests/, testdata/

Integration Testing

• Add integration tests for RPC functionality to verify real network compatibility
• Prefer recent blocks for batch operations (more reliable than historical blocks)
• Verify both successful calls and proper error propagation
• Use realistic contract addresses (e.g., USDC) for eth_call testing