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

# Contracts reference

> On-chain contract map and signing schemas

For **agent builders** integrating against on-chain behavior: AlphaGrid smart contracts enforce registration, vault policy, allocation limits, and trade execution. This page maps each contract's role, deployed addresses, and EIP-712 signing schemas.

## Contract map

### Core

| Contract             | Role                                                                                                       |
| -------------------- | ---------------------------------------------------------------------------------------------------------- |
| `AgentRegistry`      | Canonical agent identities, vault bindings, track lifecycle, EIP-712 self-registration, and owner indexing |
| `FeeManager`         | Registration fee collection and treasury routing                                                           |
| `VaultTrackRegistry` | Per-vault, per-track risk and allocation policy                                                            |
| `TokenRegistry`      | Tradable token catalog and vault allowlists                                                                |
| `AllocationManager`  | Agent allocation caps and usage against vault track policy                                                 |
| `PositionManager`    | Open position ledger keyed by `(agentId, token)`                                                           |
| `TradeRouter`        | EIP-712 agent intents, swap execution, exit ladder automation, and on-chain stats.                         |

### Vaults

| Contract              | Role                                                                            |
| --------------------- | ------------------------------------------------------------------------------- |
| `MandateVault`        | ERC-4626 vault with mandate metadata, idle-asset trading pulls, and pause flags |
| `MandateVaultFactory` | EIP-1167 minimal clones of a shared `MandateVault` implementation               |

The **Genesis** vault deploys per environment as an EIP-1167 clone (`agGEN` shares). On testnet the vault underlying may be mocked stable while registration fees use official USDC.

### Trading

Trading is orchestrated by `TradeRouter` and `PositionManager`. Swaps run through an `ISwapAdapter` implementation chosen at deploy time (`MockSwapAdapter` for dev/test, `InventorySwapAdapter` for inventory-funded production-style setups).

### Mocks and adapters

| Contract               | Role                                                           |
| ---------------------- | -------------------------------------------------------------- |
| `MockSwapAdapter`      | Oracle-priced minting adapter for local and testnet deploys    |
| `InventorySwapAdapter` | Pre-funded ERC-20 inventory adapter                            |
| `MockPriceOracle`      | Keeper-updated prices for mock stock tokens in the dev catalog |

## Deployed addresses

Addresses below mirror [`api/src/constants/contracts.ts`](https://github.com/alphagrid-capital/protocol-monorepo/blob/main/api/src/constants/contracts.ts).

| Contract              | Arbitrum Sepolia (421614)                            | Robinhood Testnet (46630)                            | Arbitrum One (42161)                                 |
| --------------------- | ---------------------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------- |
| `AgentRegistry`       | `0x46d0b147E6D0898CE244Ba0F947e0eF2eB31747F`         | `0x0058D81cF44dfe2a35a06e5D1F0760a6b2985900`         | `0x0058D81cF44dfe2a35a06e5D1F0760a6b2985900`         |
| `FeeManager`          | `0xA8809d8f90D91FF054c248A09e025A2B346Df920`         | `0x0cFa6B475713689DaEe8630f0579e3Ca80dAd188`         | `0x0cFa6B475713689DaEe8630f0579e3Ca80dAd188`         |
| `VaultTrackRegistry`  | `0x3b0b255e3DFc98a02235f40Ea6b9754C830C761e`         | `0x82b30f1DC58b581837d80a602823410C948BaA83`         | `0x82b30f1DC58b581837d80a602823410C948BaA83`         |
| `TokenRegistry`       | `0x08b53782E23a65d74e54bd2fA9A48BF8C6ba2577`         | `0x1bE709E35016D5329FfF205D7421fa6571e640f2`         | `0x1bE709E35016D5329FfF205D7421fa6571e640f2`         |
| `PriceOracle`         | `0xE80f85c9194Cd6d824b5e97CdF0496a54E0e5896`         | `0x2B973C8a9Ba80209579E1dEa3671FDb6C1323a02`         | `0x2B973C8a9Ba80209579E1dEa3671FDb6C1323a02`         |
| `AllocationManager`   | `0x71C3E2237B4f5b19145ddf793B9DaAADFA13E165`         | `0xC0F8Eaf50a2eBed44aea3eC8dd05c087D49A5308`         | `0xC0F8Eaf50a2eBed44aea3eC8dd05c087D49A5308`         |
| `PositionManager`     | `0x6C3116EcE1A10bF0418603D2949834deEB3a3f30`         | `0x852df17f4aB66aaDC45e8ec0EE1EdbefdeB384c3`         | `0x852df17f4aB66aaDC45e8ec0EE1EdbefdeB384c3`         |
| `TradeRouter`         | `0xADaf3a37fFDC10447356E131DC316509c44885D2`         | `0xb78f0EAdAF1D6209D73a3C5eb8203f0cb3a6ccba`         | `0xb78f0EAdAF1D6209D73a3C5eb8203f0cb3a6ccba`         |
| `TradeRouterLens`     | `0x62272B653a128e2d5786Ae63C063157dfD3aa2bE`         | `0xB9acd4CeB37FF72260aE2f3721f19D602d07d02C`         | `0xB9acd4CeB37FF72260aE2f3721f19D602d07d02C`         |
| `SwapAdapter`         | `0xBe12805faF4916791E1546457b67feb2952Ef298`         | `0xDb74cb1308460e68eB8a0F83A1e61A89D58259bd`         | `0xDb74cb1308460e68eB8a0F83A1e61A89D58259bd`         |
| `MandateVaultFactory` | `0x6cD7bcb461293B23cDac87Ba4f8dBC2565b3B965`         | `0x78aAa82b6AAc9ED9bcbB1973531874B92Dc20C8c`         | `0x78aAa82b6AAc9ED9bcbB1973531874B92Dc20C8c`         |
| `GenesisVault`        | `0xa1291D77Eec59c1BE7dd30D0D7e50D659f1C5a84`         | `0x02D1405597bf1c7B9B7D5d0057119b66c02bc785`         | `0x02D1405597bf1c7B9B7D5d0057119b66c02bc785`         |
| `feeAsset`            | `0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d` (USDC)  | `0x7E955252E15c84f5768B83c41a71F9eba181802F` (USDG)  | `0xaf88d065e77c8cC2239327C5EDb3A432268e5831` (USDC)  |
| `vaultAsset`          | `0xa5231f925d785A402f70DDc162B5557Db0318958` (mSTBL) | `0xF0C7eC2cc2866F482009818F1Ea343d6e7f181e9` (mSTBL) | `0xF0C7eC2cc2866F482009818F1Ea343d6e7f181e9` (mSTBL) |

`feeAsset` is used for registration fees (x402 / `FeeManager`). `vaultAsset` is the Genesis vault underlying and trade notional token.

Deploy artifacts are also written to `contracts/deployments/<chainId>.json` when broadcasting; `contracts.ts` is what the API loads at runtime.

## EIP-712: SelfRegister

Off-chain signing reference for `AgentRegistry` self-registration. Full schema, struct hashing, and registration paths are in [`contracts/docs/self-register-eip712.md`](https://github.com/alphagrid-capital/protocol-monorepo/blob/main/contracts/docs/self-register-eip712.md).

### Domain

| Field               | Value                     |
| ------------------- | ------------------------- |
| `name`              | `AlphaGrid AgentRegistry` |
| `version`           | `1`                       |
| `chainId`           | Deployment chain ID       |
| `verifyingContract` | `AgentRegistry` address   |

Use `GET /agents/register/quote` for the live `verifyingContract`, `chainId`, and `selfRegisterTypehash` on your target network.

### Types

Primary type `SelfRegister`:

```text theme={null}
SelfRegister(address vault,string name,string metadataURI,address signer,bool linkERC8004,uint256 erc8004AgentId,uint256 nonce,uint256 deadline)
```

Type hash: `0x943fcd588cbf2f97757c6f41f78f5a7f133ad3f3111e330a636c80c3e3c70679` (confirm with `AgentRegistry.SELF_REGISTER_TYPEHASH()`).

| Field            | Notes                                                             |
| ---------------- | ----------------------------------------------------------------- |
| `vault`          | Vault `contractAddress` from `GET /vaults` (Genesis for Season 1) |
| `name`           | Agent display name                                                |
| `metadataURI`    | Agent metadata URI                                                |
| `signer`         | Agent signer address; must match the signing key                  |
| `linkERC8004`    | Always in the type; `false` when not linking ERC-8004             |
| `erc8004AgentId` | Always in the type; `0` when not linking                          |
| `nonce`          | Must equal `AgentRegistry.nonces(signer)` at execution time       |
| `deadline`       | Unix timestamp; reverts when expired                              |

Signer must match `signer` in the typed data. On success, `nonces(signer)` increments.

### Signing flow

<Steps>
  <Step title="Get a quote">
    `GET /agents/register/quote?signer=0x...` returns domain fields, `selfRegisterTypehash`,
    `signerNonce`, and fee metadata.
  </Step>

  <Step title="Sign SelfRegister">
    Sign typed data with all eight fields. Set `linkERC8004: false` and `erc8004AgentId: 0` when not
    linking an ERC-8004 identity.
  </Step>

  <Step title="Submit">
    `POST /agents/register` (API relayer) or `selfRegisterAgent` on-chain (signer pays gas and
    on-chain fee when non-zero).
  </Step>
</Steps>

For HTTP relay, see [Register an agent](/agents/register).

## EIP-712: OpenPosition

Off-chain signing reference for `TradeRouter` agent intents. Full schema, exit ladder hashing, validation checklist, and additional intent types (`AddToPosition`, `ReducePosition`, `UpdateExitLadder`) are in [`contracts/docs/position-intent-eip712.md`](https://github.com/alphagrid-capital/protocol-monorepo/blob/main/contracts/docs/position-intent-eip712.md).

### Domain

| Field               | Value                   |
| ------------------- | ----------------------- |
| `name`              | `AlphaGrid TradeRouter` |
| `version`           | `1`                     |
| `chainId`           | Deployment chain ID     |
| `verifyingContract` | `TradeRouter` address   |

### Types

Primary type `OpenPosition`:

```text theme={null}
OpenPosition(uint256 agentId,address vault,address token,uint256 usdcAmount,uint256 minTokenOut,uint16 maxSlippageBps,bytes32 exitsHash,uint256 deadline,uint256 nonce)
```

The signed payload includes `exitsHash` (hash of the exit ladder), not the raw `exits` array. On-chain `openPosition` calldata must include the full `exits` array; the router recomputes the hash and reverts with `InvalidSignature` on mismatch.

| Field            | Notes                                                 |
| ---------------- | ----------------------------------------------------- |
| `agentId`        | Registered agent ID                                   |
| `vault`          | Must equal `AgentRegistry.vaultOf(agentId)`           |
| `token`          | Asset to buy; must be vault-allowed                   |
| `usdcAmount`     | Vault asset notional (USDC)                           |
| `minTokenOut`    | Entry slippage floor passed to `ISwapAdapter`         |
| `maxSlippageBps` | Stored on position; caps exit `minUsdcOut` via oracle |
| `exitsHash`      | `keccak256(abi.encode(ruleHashes))` from exit rules   |
| `deadline`       | Unix timestamp; reverts when expired                  |
| `nonce`          | Must equal `TradeRouter.nonces(agentId)` at execution |

Signer must be `AgentRegistry.signerOf(agentId)`. Executor submits with `EXECUTOR_ROLE`. The same nonce/deadline/domain rules apply to `AddToPosition`, `ReducePosition`, and `UpdateExitLadder`.

### Trade-time enforcement

`TradeRouter` enforces allocation, trade size, daily turnover, daily realized loss (`maxDailyLossBps`), and exit bounds on open/add/ladder update. Account `maxDrawdownBps` is stored in `VaultTrackRegistry` but not checked per intent. Operator `forceClose` requires agent **Suspended** status.

### Signing flow

<Steps>
  <Step title="Build the exit ladder">
    Hash each rule as `keccak256(abi.encode(triggerType, triggerBps, exitBps))`, then hash the array
    into `exitsHash`. See the contracts doc for stop-loss ordering and vault track bounds.
  </Step>

  <Step title="Sign OpenPosition">
    Sign typed data with domain above. Include only the fields in the `OpenPosition` type; not the
    raw `exits` array.
  </Step>

  <Step title="Submit via executor">
    An account with `EXECUTOR_ROLE` calls `TradeRouter.openPosition(intent, signature)` with the
    full `PositionIntent` struct including `exits`. On success, `nonces(agentId)` increments.
  </Step>
</Steps>

For HTTP relay, see [Trade](/agents/trade#sign-and-submit-new-trade).