Wallet Transfer v1 Service

Skip The Details?

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

Overview

The TransferService manages asset transfers between accounts on the same ledger network. This service handles the full lifecycle of a transfer, from creation through on-chain execution, including fee calculation and state tracking.

Transfers are the primary mechanism for moving assets between accounts on the Mesh platform. Each transfer is:

• Ledger-bound: Both the source and destination accounts must be on the same ledger network
• Fee-aware: Transfer fees and VAT are automatically calculated
• State-tracked: Transfers progress through defined states (in progress, successful, failed)
• Hierarchically scoped: Owned by a group within your organizational hierarchy
• Monitorable: Real-time streaming updates as transfer state changes

Common Workflows

Basic Transfer

1. Calculate Transfer Fee - Preview the fee, VAT amount, and VAT rate for the intended transfer amount
2. Create Transfer - Initiate a transfer specifying source address, destination address, and amount
3. Monitor Transfer - Subscribe to real-time state updates via streaming
4. Verify Completion - Confirm the transfer reached TRANSFER_STATE_SUCCESSFUL

Transfer Auditing

1. List Transfers - Retrieve all transfers within your group hierarchy
2. Search by Address - Find all transfers involving a specific ledger address
3. Get Transfer - Retrieve details of a specific transfer by resource name

Key Concepts

Transfer States

Transfers progress through the following states:

State	Description
TRANSFER_STATE_IN_PROGRESS	Transfer has been submitted and is being processed on-chain
TRANSFER_STATE_SUCCESSFUL	Transfer completed successfully on the ledger
TRANSFER_STATE_FAILED	Transfer failed during on-chain execution

Ledger Addresses

The from and to fields use ledger-native addresses. Both addresses must be on the same ledger network. The address format determines which ledger the transfer executes on:

Ledger	Address Format
Stellar	Ed25519 public key
Solana	Ed25519 public key

Transfer Description

Transfers support an optional description field to record the reason for the transfer. When include_in_ledger is set to true, the description will be included in the on-chain ledger transaction, making it visible on the blockchain.

Transfer Fees

Each transfer includes a TransferFee containing:

• amount - The calculated fee charged for the transfer
• vat_rate - The VAT rate applied to the fee calculation

Fees are calculated automatically by the system during transfer creation. You can preview the fee breakdown before creating a transfer using the CalculateTransferFee method, which returns the fee amount, VAT amount, and VAT rate for a given transfer amount.

Transfer Numbers

Each transfer receives a unique, monotonically increasing number that serves as a human-readable identifier. This number is system-generated and immutable.

Authentication & Authorization

The TransferService uses role-based access control:

Write Operations

Require ROLE_WALLET_ADMIN or ROLE_WALLET_TRANSFER_ADMIN:

• CreateTransfer

Read Operations

Require any wallet role (ADMIN or VIEWER variants):

• GetTransfer
• ListTransfers
• SearchTransfersByAddress
• MonitorTransfer
• CalculateTransferFee

All operations are scoped to your group's hierarchy - you can only access transfers owned by your group or its descendants.