> ## Documentation Index
> Fetch the complete documentation index at: https://docs.groundtech.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Onchain Architecture

> How deposits, direct protocol positions, and Ground RWA Vault positions move through Ground's contract stack.

This page describes how stablecoins enter a Portfolio Wallet and then move through either a direct protocol position or a Ground RWA Vault position. USDC and USDT follow separate strategy lanes.

## Funding a Portfolio Wallet

Funding and allocation are separate stages. An external transfer first becomes cash in the Portfolio Wallet. A later Ground-managed rebalance deploys that cash according to the wallet's strategy.

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    participant User as External Wallet
    participant PW as Portfolio Wallet
    participant API as Ground API

    User->>PW: Transfer selected stablecoin
    API->>API: Detect and confirm transfer
    API->>API: Post wallet cash balance
    API->>PW: Start eligible strategy allocation
```

The stablecoin remains in its original token lane. Ground does not convert between USDC and USDT during deposits, rebalances, or withdrawals. USDC may bridge within its supported CCTP domain; USDT remains on Ethereum in production.

## Signing Portfolio Wallet actions

Ground uses Turnkey to sign Portfolio Wallet transactions according to the wallet's configured policies. Ground then broadcasts the signed transaction, which calls the MasterRouter from the Portfolio Wallet address.

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    participant API as Ground API
    participant TK as Turnkey
    participant PW as Portfolio Wallet
    participant MR as MasterRouter

    API->>TK: Request Portfolio Wallet transaction signature
    TK-->>API: Return approved signed transaction
    API->>PW: Broadcast signed wallet transaction
    PW->>MR: Execute authorized action
```

Some actions require customer approval before Turnkey releases the signature. See [Transaction Approvals](/docs/portfolio-wallets/transaction-approvals) for the approval API and verification flow.

## Direct protocol positions

DeFi sources such as Morpho use a direct protocol path. The Portfolio Wallet calls the MasterRouter, the router resolves an approved adapter through the AdapterRegistry, and the adapter interacts with the underlying protocol. The resulting protocol position token or vault share is held by the Portfolio Wallet.

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    participant PW as Portfolio Wallet
    participant MR as MasterRouter
    participant AR as AdapterRegistry
    participant Adapter as Protocol Adapter
    participant Protocol as Underlying Protocol

    PW->>MR: Execute yield-source action
    MR->>AR: Resolve approved adapter
    AR-->>MR: Return active adapter
    MR->>Adapter: Forward action and stablecoin
    Adapter->>Protocol: Deposit into protocol
    Protocol-->>PW: Issue protocol position
```

An exit follows the corresponding protocol's redeem path. Some direct protocols settle in one transaction; others require additional waiting or settlement steps before stablecoin is available for payout.

## Ground RWA Vault positions

Ground RWA Vault sources use dedicated vault contracts. The Portfolio Wallet interacts onchain with the MasterRouter and the applicable Ground vault, then holds a wallet-specific, non-transferable Ground receipt rather than an underlying provider instrument directly.

Depending on the product and available liquidity, a Ground RWA Vault deposit may settle immediately or use the following asynchronous deposit lifecycle:

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    participant PW as Portfolio Wallet
    participant MR as MasterRouter
    participant GV as Ground RWA Vault
    participant Provider as RWA Provider
    participant Processor as Vault Processor

    PW->>MR: Submit vault deposit request
    MR->>GV: Create wallet request
    GV->>Provider: Start provider settlement
    Provider-->>GV: Make underlying value claimable
    Processor->>GV: Process available settlement
    PW->>MR: Claim processed deposit
    MR->>GV: Claim deposit for wallet
    GV-->>PW: Issue non-transferable Ground receipt
```

Ground RWA Vault exits use the corresponding redemption lifecycle: the wallet requests redemption, provider settlement and vault processing complete, the wallet claims stablecoin, and Ground sends the payout to the withdrawal destination. Some vaults can settle through available onchain liquidity; otherwise the asynchronous path applies. Each withdrawal payout leg settles and pays out independently.

<Info>
  Processing policies in the [Yield Sources](/docs/portfolio-wallets/yield-sources) catalog describe operational estimates. Actual completion depends on external fulfillment and vault processing. Because payout legs may settle at different times, each requires separate approval when signing keys are configured in the [developer portal](https://portal.groundtech.co). See [Transaction Approvals](/docs/portfolio-wallets/transaction-approvals) for details.
</Info>

## Contract addresses

See [Contract Addresses](/docs/resources/addresses) for the canonical production and sandbox router, registry, adapter, Ground vault, bridge, and Solana program deployments.