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

# Concepts

> Key ideas to understand before integrating Amplify Earn.

Before wiring up calldata, align on a few terms used throughout the docs.

## Vaults and share tokens

* **Vault** — an on-chain contract that issues an ERC-20 *share token* representing a user's position. The vault address is the share token address.
* **Share token** — the ERC-20 a user holds after depositing. Its `decimals()` may differ from the underlying asset's decimals; always read live, never assume.
* **Deposit asset** — the ERC-20 a user deposits into the vault.
* **Want asset** — the ERC-20 a user receives when withdrawing; can be the same as the deposit asset, or different.

## How the SDK works

For **transactions** (`deposit.prepare`, `withdraw.prepare`, `withdraw.cancel`), the response includes ABI-encoded calldata that your app submits via the user's wallet — viem, wagmi, ethers, or anything else that can call `eth_sendTransaction`.

For **reads** (`vaults.list`, `vaults.getApys`, `users.getPositions`, …), the response is the parsed JSON payload.

The SDK does not sign transactions or hold private keys.

## The deposit flow

1. **Authorize** — call `client.core.authorization.detect({ tokenAddress: depositAsset, ... })`. The response tells you whether the user already has allowance, needs a standard `approve()` transaction, or can use an EIP-2612 permit signature.
2. **Sign or approve** — if `method === 'permit'`, ask the user's wallet to sign the typed data the API returned. If `method === 'approval'`, submit the encoded `approve()` transaction.
3. **Prepare** — call `client.amplify.deposit.prepare(...)`. If you signed a permit in step 2, pass `permitSignature` + `permitDeadline`.
4. **Submit** — send the transaction the prepare response returned.

## The withdrawal flow

Withdrawals settle through a `WithdrawQueue` contract. There is no inline permit path:

1. **Authorize** — call `client.core.authorization.detect({ tokenAddress: vaultAddress, ... })` against the share token. If `method !== 'already_approved'`, the user must submit a standard `approve(WithdrawQueue, amount)` transaction first.
2. **Prepare** — call `client.amplify.withdraw.prepare(...)`. The response is calldata for `WithdrawQueue.submitOrder`.
3. **Submit** — send the transaction.
4. (Optional) **Cancel** — `client.amplify.withdraw.cancel(...)` returns calldata for cancelling a pending order. Look up `orderIndex` via `client.amplify.withdraw.listRequests(...)`.

## Amounts and decimals

All amount fields in the SDK are **decimal strings in token base units**. For a user input of "10" against a 6-decimal token, send `"10000000"`. For 18 decimals, send `"10000000000000000000"`.

Always read `decimals()` live from the relevant token contract. Different vaults and chains use different decimals; hardcoded fallbacks are bugs.

## Errors

Every method throws `AmplifyError` with `statusCode?`, `body?`, `message`, and `rawResponse?`. Timeouts surface as `AmplifyTimeoutError`. Use `err instanceof AmplifyError` (or `AmplifyTimeoutError`) to narrow.