Wallet Architecture

SAI Wallet is implemented as a non-custodial multichain wallet: keys and signatures remain on the user side, while infrastructure components perform route building, execution monitoring, and normalization of operation statuses.

In short:

• the application signs all transactions locally, without transferring keys
• one domain model for different networks and tokens
• workflow manages multi-step operations and their statuses

The architecture is oriented toward (1) unifying interaction with various networks and tokens and (2) executing multi-step operations with status monitoring and recording of execution results.

At the architecture level, the system is divided into a domain model and infrastructure modules. The domain model describes “what is done” (assets, portfolio, strategy, operation, fee), while infrastructure describes “how it is executed” in a specific network or through a specific protocol.

Layers and Responsibility Boundaries

Client Application

The client is responsible for:

• key management and transaction signing;
• displaying aggregated portfolio (balances, positions, accruals);
• building operations (workflow) and showing the user the composition of steps and estimated costs;
• sending transactions and displaying execution statuses.

Domain Model

The domain model is a set of entities and rules not tied to a specific network:

• AssetRef: asset identifier (ticker/contract/network);
• ChainRef: network identifier and family (e.g., EVM / non-EVM);
• Portfolio: aggregated representation of balances and positions;
• Workflow: operation as a sequence of steps (local and cross-chain);
• FeeBreakdown: cost breakdown by components (see Economics).

Smart Contract Layer

Smart contracts ensure uniform execution of key operations and record observable state:

• cross-chain operation controller (accounting for operation identifiers, statuses, idempotency);
• routing/execution contracts for exchange and staking (Swap/Stake);
• adapters to external protocols (unified interfaces);
• accounting for shares/positions in strategies and events for monitoring.

Cross-Chain Message Exchange

Cross-chain message exchange is performed via an infrastructure module. It ensures delivery of payload between networks and receipt of execution confirmations. At the domain model level, this looks like a “cross-chain transition step” with a fixed operation identifier and predictable error model.

External Protocols and Connectors

Integrations with DEX, yield protocols, pools, and bridges are isolated in connectors/adapters. This limits “leakage” of specific protocol details into the user scenario: at the SAI Wallet level, unified operations swap/deposit/withdraw are used.

Optional Off-Chain Services

Some functions may be performed off-chain (while maintaining the non-custodial model):

• collection and normalization of balance and position data (indexers);
• building quota and route by current fees/availability (quoter/router);
• observability and status diagnostics (see FAQ).

Chain Abstraction Layer and Network Adapters

Network differences (address formats, gas mechanics, transaction confirmation, token standards) are not exposed to the domain model. For this, a Chain Abstraction Layer (CAL) and a family of network adapters are used:

• EVM adapter: transactions, gas model, ERC-20 interfaces, events;
• non-EVM adapter: address specifics, fees, and contract calls for a specific network.

Adapters provide a unified set of operations: transaction building, fee estimation, sending, waiting for confirmation, and status normalization.

Operation Controller and Workflow Model

An operation in SAI Wallet is considered as a workflow of steps. Steps can be:

• local (in one network);
• cross-chain (initiation in the source network and completion in the destination network).

For cross-chain workflows, an operation controller is used that:

• assigns an operation identifier and records its state;
• validates initiator and parameters;
• ensures handling of message re-delivery without duplicating actions;
• stores events and statuses for monitoring.

Staking Architecture

The technical implementation of staking in SAI Wallet is built around a unified contract contour (StakeRouter + strategy adapters) and mechanics for updating positions through workflow statuses, transactions, and events. This allows hiding details of specific yield protocols and ensuring unified UX.

Details: Staking Architecture.

Swap Module and Exchange Mechanism Separation

In the UI, exchange is presented as a single screen, but the execution mechanism depends on asset types and route (see Swap):

• for some scenarios (e.g., exchange/transfer of stablecoins between networks), a cross-chain workflow with controlled cost breakdown is used;
• for other tokens, an external exchange module (provider/aggregator) is used, connected as an infrastructure integration.

At the architecture level, both cases are described the same way: “exchange” is a workflow with quota and status monitoring, but steps are executed by different executors.

Observability and Portfolio State Updates

The user portfolio is formed from:

• on-chain events and operation statuses;
• balances in networks and position states in strategy contracts;
• aggregated metrics (sum, share, accruals), normalized into the domain model.

Contract events are used as the source of truth for updating the aggregated portfolio representation and position statuses.

Trust Boundaries

The trust model separates components:

• the user controls keys and signatures;
• infrastructure builds and maintains workflows but cannot sign operations;
• external protocols are considered independent systems, interaction with which is isolated through adapters and risk/constraint parameters at the SAI Wallet level.

The described components define responsibility distribution but do not fix the order of step execution. The section Cross-chain Workflow presents the pipeline (state machine) for operation execution: from route building to result confirmation by network data.