Accounts & Yield Types
- Account — An on-chain contract that issues ERC-20 shares representing a position in an underlying strategy.
- Yield Type — Logical grouping of accounts with similar mandates (
CORE,TREASURY,FRONTIER). Used as a filter when discovering accounts via the GraphQL API. - Want Asset — The token users receive when withdrawing from an account; often different from the deposit token.
Account Discovery
All contract addresses are available via the GraphQL API atPOST https://api.paxoslabs.com/graphql. See Setup & Prerequisites for the full query and response format.
What is a Smart Contract?
A smart contract is a program deployed on the Ethereum blockchain. Once deployed, anyone can call its functions by sending a transaction (for writes) or making a call (for reads). You interact with contracts using their address (like a URL) and their ABI (like an API schema).What is an ABI?
An Application Binary Interface (ABI) is a JSON description of a contract’s functions — their names, parameter types, and return types. Think of it as an OpenAPI/Swagger spec for a smart contract. Your code uses the ABI to encode function calls into the binary format the blockchain expects.What is a Token Approval?
ERC-20 tokens (like USDC) don’t allow contracts to spend your tokens by default. Before a contract can move tokens on your behalf, you must approve it by calling the token’sapprove(spender, amount) function. This is a safety mechanism — you explicitly opt in to each contract interaction.
What is an EIP-2612 Permit?
A permit is a gasless alternative toapprove defined by EIP-2612. Instead of sending an on-chain approval transaction, you sign an off-chain message that authorizes a contract to spend your tokens. The contract verifies this signature on-chain. Not all tokens support permits — USDT notably does not.
Shares vs. Assets
- Deposits mint account shares to the recipient. Shares are ERC-20 tokens representing your proportional ownership of the account’s assets.
- Withdrawals burn shares and return the want asset (e.g., USDC). The want asset may differ from the token you deposited.
- The exchange rate between shares and the underlying tokens changes over time as the account earns yield.
- All on-chain values are in base units (e.g., 1 USDC =
1000000with 6 decimals).
Slippage Controls
When depositing, theminimumMint parameter protects you from receiving fewer shares than expected due to exchange rate changes between when you prepare and when your transaction is mined. This is expressed as a minimum number of shares to receive — if the account would mint fewer, the transaction reverts. A common default is 0.5% (50 basis points) below the expected share amount.
Withdrawals
- Withdrawals are order-based, not instant. You submit an order to the WithdrawQueue and the account operator fulfills it (typically within 24 hours).
- You must approve your account shares to the WithdrawQueue before submitting an order.
- Once fulfilled, the want asset is sent directly to the address that submitted the order.
- Pending orders can be cancelled to recover your locked account shares.
Execution Responsibilities
When integrating directly with smart contracts, your application is responsible for:- Building calldata — ABI-encoding function calls with the correct parameters
- Submitting transactions — Signing and broadcasting via your chosen Ethereum library
- Handling gas — Estimating gas limits and setting appropriate gas prices
- Error handling — Parsing revert reasons from failed transactions
Contract Architecture
Amplify accounts are built on the Nucleus BoringVault framework — an open-source, audited account architecture. You can browse the full Solidity source, deployment configs, and audit reports in the GitHub repository. Three contracts handle user-facing operations:| Contract | Role | What You Call It For |
|---|---|---|
| DistributorCodeDepositor | Deposit entry point | Depositing tokens into the account |
| WithdrawQueue | Withdrawal order manager | Submitting and cancelling withdrawal orders |
| BoringVault | ERC-20 account share token | Approving shares for withdrawal, checking balances |
Lifecycle
Deposit
You approve the deposit token (e.g., USDC) to the DistributorCodeDepositor,
then call
deposit(). The account mints shares to your address.Withdraw
You approve your account shares to the WithdrawQueue, then call
submitOrder(). The account operator fulfills your order (typically within 24
hours) and sends the want asset to your address.Cancel (optional)
If your withdrawal is still pending, you can call
cancelOrder() on the
WithdrawQueue. Your locked account shares are returned to you.Glossary
| Term | Definition |
|---|---|
| ABI | Application Binary Interface — a JSON schema that describes how to encode/decode calls to a contract |
| Approval | An on-chain transaction granting a contract permission to transfer your tokens |
| Basis points (bps) | A unit of measurement where 1 bps = 0.01%. 50 bps = 0.5%, 100 bps = 1%. |
| EIP-2612 Permit | An off-chain signature that authorizes token spending without an on-chain approval transaction |
| ERC-20 | The standard interface for fungible tokens (USDC, USDT, etc.) |
| Gas | The fee paid in ETH to execute a transaction on Ethereum |
| Nonce | A sequential counter that prevents transaction replay |
| RPC | Remote Procedure Call — the API protocol used to communicate with an Ethereum node |
| Slippage | The difference between the expected and actual exchange rate. Controlled via minimumMint. |
| Account shares | ERC-20 tokens representing your deposit in the account; their value appreciates as the account earns yield |
| Want asset | The token you want to receive when withdrawing (e.g., USDC) |
| WithdrawQueue | The contract that manages withdrawal orders as an ordered queue |