Wallet Account v1 Service

Skip The Details?

• 👉 Jump to Package Types
• 👉 Jump to Service Methods

Overview

The AccountService manages blockchain wallet accounts across multiple ledger networks (Stellar, Solana, Bitcoin, Ethereum etc.). This service provides comprehensive account lifecycle management, from creation through closure, along with balance queries and metadata management.

Accounts serve as the primary containers for holding and managing digital assets on the Mesh platform. Each account is:

• Ledger-specific: Tied to a single blockchain network
• Hierarchically owned: Part of your group's organizational structure
• Uniquely numbered: Identified by a 7-digit Account Number
• Multi-asset capable: Can hold multiple instrument balances within its ledger

Common Workflows

Account Lifecycle Management

1. Create Account - Register account in system (off-chain)
2. Open Account - Initialize on blockchain (on-chain)
3. Use Account - Receive deposits, execute trades
4. Query Balances - Monitor holdings with live data
5. Close Account - Deactivate when no longer needed

Key Concepts

Account Numbers

Each account receives a unique 7-digit Account Number starting with '1' (e.g., 1234567). This Account Number provides:

• Easy account identification
• Simplified inter-account transfers
• Human-friendly references

Ledger Support

Accounts can be created on four blockchain networks:

Ledger	Use Case	Address Format	Status
Stellar	Fast settlements, stablecoins	Ed25519 public key	Live
Solana	High-throughput trading	Ed25519 public key	Coming Soon
Bitcoin	Store of value	secp256k1 address	Coming Soon
Ethereum	DeFi integration	secp256k1 address	Coming Soon

Live Ledger Data

The populate_ledger_data parameter in read requests (Get, List, Search) controls whether to fetch current blockchain state:

• false: Returns stored account metadata only (faster)
• true: Returns live balances and state from blockchain (slower)

Use live data for:

• Balance verification before trades
• Account state confirmation
• Audit and reporting

Use cached data for:

• Account listing and browsing
• Display name lookups
• Bulk operations

Authentication & Authorization

The AccountService uses role-based access control:

Write Operations

Require ROLE_WALLET_ADMIN or ROLE_WALLET_ACCOUNT_ADMIN:

• CreateAccount
• UpdateAccount
• OpenAccount
• CloseAccount

Read Operations

Require any wallet role (ADMIN or VIEWER variants):

• GetAccount
• GetAccountByNumber
• ListAccounts
• SearchAccounts

All operations are scoped to your group's hierarchy - you can only access accounts owned by your group or its descendants. You can only operate on accounts in your executing group.

Best Practices

1. Account Creation: Always specify a descriptive display_name for easy identification
2. Ledger Selection: Choose the appropriate ledger based on your trading needs
3. Balance Queries: Use populate_ledger_data=false for listing, true for trading decisions
4. Error Handling: Check account state before operations - closed accounts cannot transact
5. Monitoring: Track the ledger_transaction reference when opening/closing accounts