> ## 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 and withdrawals move through Ground's on-chain contract stack.

This page describes the end-to-end path funds take when entering and leaving a Portfolio Wallet, and lists every deployed contract address by chain.

## Deposit flow

When a user deposits a supported stablecoin into their Portfolio Wallet, funds move through the following sequence. USDC and USDT follow separate strategy lanes.

```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
    participant MR as MasterRouter
    participant AR as AdapterRegistry
    participant YS as Yield Source Contract(s)

    User->>PW: Transfer selected stablecoin
    API->>API: Detect deposit via on-chain monitoring
    API->>PW: Sign + submit deposit tx
    PW->>MR: Execute deposit intent
    MR->>AR: Resolve adapter for yield source
    AR-->>MR: Return active adapter address
    MR->>YS: Forward stablecoin + call deposit
    YS-->>MR: Return receipt tokens
    API->>API: Record position, update balances
```

1. The user transfers USDC or USDT from an external wallet to the Portfolio Wallet deposit address on a supported chain.
2. Ground's servers detect the incoming transfer via on-chain monitoring.
3. Ground signs and submits a deposit transaction from the Portfolio Wallet.
4. The Portfolio Wallet calls the **MasterRouter** contract.
5. The MasterRouter resolves the correct yield source through the **AdapterRegistry**.
6. The stablecoin is deposited into a compatible **underlying yield source** whose `depositToken` matches the strategy lane.
7. Receipt tokens are held by the Portfolio Wallet; Ground updates the wallet's on-chain position and reported balances.

## Withdrawal flow

Withdrawals reverse the deposit path, unwinding positions back to the requested stablecoin before sending to the destination:

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    participant Dest as Destination Wallet
    participant PW as Portfolio Wallet
    participant API as Ground API
    participant MR as MasterRouter
    participant AR as AdapterRegistry
    participant YS as Yield Source Contract(s)

    API->>API: Plan withdrawal (select positions to unwind)
    API->>PW: Sign + submit redeem tx
    PW->>MR: Execute redeem intent
    MR->>AR: Resolve adapter for yield source
    AR-->>MR: Return active adapter address
    MR->>YS: Redeem receipt tokens for stablecoin
    YS-->>MR: Return selected stablecoin
    API->>PW: Submit payout transfer
    PW->>Dest: Selected stablecoin arrives
    Note over API,YS: Each payout leg settles and pays out independently
```

1. The API plans the withdrawal by selecting which yield source positions to unwind (each becomes a **payout leg**).
2. For each payout leg, Ground signs and submits a redeem transaction from the Portfolio Wallet.
3. The Portfolio Wallet calls the **MasterRouter**.
4. The MasterRouter resolves the correct yield source via the **AdapterRegistry**.
5. Receipt tokens are redeemed from the **underlying yield source** and the source's deposit token is returned.
6. As each payout leg settles, the requested stablecoin is transferred from the Portfolio Wallet to the user's destination address immediately. Payout legs do not wait for each other.

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.

<Info>
  Some yield sources, including `syrup-usdc` and JTRSY, have asynchronous redemption. JTRSY USDC redemptions are instant through Basin when liquidity is available. 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>

## Deployed contract addresses

Each supported chain has the core routing infrastructure (MasterRouter, AdapterRegistry, WalletBindingRegistry), a CCTP adapter for bridging, and yield source adapters.

### Production (mainnet)

#### Core contracts

| Chain    | MasterRouter                                 | AdapterRegistry                              | WalletBindingRegistry                        |
| -------- | -------------------------------------------- | -------------------------------------------- | -------------------------------------------- |
| Ethereum | `0xD743D5b09eceA67880c4bc326a18A874bafE246E` | `0x6Da1180A84C0E38a0d292f1e51853ce4C75fc150` | `0x36E76eE20168300a1005e3d607499f6f0C62318b` |
| Arbitrum | `0xD743D5b09eceA67880c4bc326a18A874bafE246E` | `0x6Da1180A84C0E38a0d292f1e51853ce4C75fc150` | `0x9FfaaF612A748681508852591c54AFC84A7a84E8` |
| Base     | `0xD743D5b09eceA67880c4bc326a18A874bafE246E` | `0x6Da1180A84C0E38a0d292f1e51853ce4C75fc150` | `0xc8bC5a9F6F2e5C0a78B1dDC4088A8dCE9B5316c8` |
| Polygon  | `0xD743D5b09eceA67880c4bc326a18A874bafE246E` | `0x6Da1180A84C0E38a0d292f1e51853ce4C75fc150` | `0xc8bC5a9F6F2e5C0a78B1dDC4088A8dCE9B5316c8` |

#### Yield source adapters (Ethereum only)

| Adapter                  | Address                                      | Underlying Protocol                                          |
| ------------------------ | -------------------------------------------- | ------------------------------------------------------------ |
| Syrup USDC               | `0x746253ea7ecd9c356C4E42A977238779fa1F85BA` | Maple Finance                                                |
| U.S. Treasury Bill Vault | `0x5a68cfE0DCCcfA4991e5a92d2c382b15B41C4119` | Ground vault backed by Superstate USTB                       |
| JTRSY USDC Vault         | `0x668c8B417314cC231bB18D948F3835e79c85Fe43` | Ground vault backed by Centrifuge JTRSY                      |
| JTRSY USDT Vault         | `0x6E48246dC3eFC8A5F7d342F90AC7833791C782c7` | Ground vault backed by Centrifuge JTRSY                      |
| Morpho Gauntlet USDC     | `0xb36Ee685D1AdE0af03995E0e9E6D7D050736E4bE` | Morpho (Vault: `0xdd0f28e19C1780eb6396170735D45153D261490d`) |
| Morpho Steakhouse USDC   | `0xe196b91BfF3F0EC4279e8494Ab9b9727B62FFDEb` | Morpho (Vault: `0xBEEF01735c132Ada46AA9aA4c54623cAA92A64CB`) |
| Morpho August USDC V2    | `0x6268d5c875acAB235d411563A4A03163aDa08F90` | Morpho (Vault: `0x7ceB0f01Cb7187a2EBED5661eCC4d5701d8F2350`) |

#### Bridge adapters

| Chain    | CCTP Adapter                                 |
| -------- | -------------------------------------------- |
| Ethereum | `0x49bD4C78cf3B4dDcF9c3857269BFa08C69f5E044` |
| Arbitrum | `0x49bD4C78cf3B4dDcF9c3857269BFa08C69f5E044` |
| Base     | `0x49bD4C78cf3B4dDcF9c3857269BFa08C69f5E044` |
| Polygon  | `0x49bD4C78cf3B4dDcF9c3857269BFa08C69f5E044` |

### Sandbox (Ethereum Sepolia)

| Contract                      | Address                                      |
| ----------------------------- | -------------------------------------------- |
| MasterRouter                  | `0xBB6cD0a42cb96eb7bA9234a0B5738545D53958d3` |
| AdapterRegistry               | `0x4d18Ee079fc36573d62B52B02eB9c6D8F0fc38E2` |
| WalletBindingRegistry         | `0xDd48ddD16B3E6906F8d64dB51c03a39EFE0C3EA4` |
| CCTP Adapter                  | `0x826abf3b74c59B6Aec8a0d4aF07fe5fC81A0Fe0F` |
| Syrup USDC Adapter            | `0x9DF3Ef7DbE65eBF07064c912fFC52c2AB169EbbF` |
| Morpho August USDC V2 Adapter | `0xFa86eF30a830A27e2d00b4D8eC9cd853690222B7` |
| JTRSY USDC Vault              | `0xfF5155c2389f8552795C0fA12fa3005260F417ec` |
| JTRSY USDT Vault              | `0xCAa3b4C38Ee8EA43aAa3a44b50dACB4B3032C1CA` |