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

# Transaction integration

> Execution profile, quotes, deposits, redemptions and claims.

[Quickstart](/en/developers/integrate-earn-usdt) · [Data API](/en/developers/data-api) · [Financial equations](/en/developers/financial-data)

## Execution profile

Pin `kaia-earnusdt-2026-07` in the integration release.

| Contract              | Address                                      |
| --------------------- | -------------------------------------------- |
| SuperEarnRouter       | `0x7437892a3e2e658038758dd7ca638334c0c2006c` |
| SuperVault / EarnUSDT | `0x2e4e573d86c70688cd97d76bc5ddc1bb265bf5d6` |
| CooldownVault / seCDV | `0x4e4654ce4ca7ff0ba66a0a4a588a4bd55a6f9a33` |
| USDT                  | `0xd077a400968890eacc75cdc901f0356c943e4fdb` |

| Check                   | Expected value                                                   |
| ----------------------- | ---------------------------------------------------------------- |
| Chain                   | Kaia `8217`                                                      |
| Router                  | Deployed bytecode at the pinned address                          |
| `SuperVault.token()`    | CooldownVault address                                            |
| `CooldownVault.asset()` | USDT address                                                     |
| Decimals                | USDT / seCDV / EarnUSDT: 6; KAIA: 18                             |
| Product availability    | Active deployment for writes; retain inactive holdings for reads |

* Disable writes on any profile mismatch. Upgrade addresses and ABIs through a reviewed integration release.
* Use chain-qualified IDs from the Data API for data joins.

### Minimal ABIs

<Accordion title="Viem read and transaction interfaces">
  ```ts theme={null}
  import { parseAbi } from "viem";

  export const routerAbi = parseAbi([
    "function previewDeposit(address yVault, uint256 amount) view returns (uint256 expectedShares)",
    "function previewRedeem(address yVault, uint256 yShares) view returns (uint256 assets)",
    "function previewWithdraw(address yVault, uint256 assets) view returns (uint256 ySharesNeeded)",
    "function previewClaim(address yVault, uint256 requestId) view returns (bool isClaimable, uint256 maxAssetsOut)",
    "function maxRedeemableShares(address yVault) view returns (uint256 maxShares)",
    "function deposit(address yVault, uint256 amount, uint256 minSharesOut) returns (uint256 yShares)",
    "function depositWithPermit(address yVault, uint256 amount, address receiver, uint256 minSharesOut, uint256 deadline, uint8 v, bytes32 r, bytes32 s) returns (uint256 yShares)",
    "function depositWithReferral(address yVault, uint256 amount, uint256 minSharesOut, bytes32 referralCode) returns (uint256 yShares)",
    "function depositWithPermitAndReferral(address yVault, uint256 amount, address receiver, uint256 minSharesOut, bytes32 referralCode, uint256 deadline, uint8 v, bytes32 r, bytes32 s) returns (uint256 yShares)",
    "function redeem(address yVault, uint256 yShares, uint256 minAssetsOut) returns (uint256 requestId)"
  ]);

  export const erc20Abi = parseAbi([
    "function balanceOf(address account) view returns (uint256)",
    "function allowance(address owner, address spender) view returns (uint256)",
    "function approve(address spender, uint256 amount) returns (bool)",
    "function nonces(address owner) view returns (uint256)",
    "function permit(address owner, address spender, uint256 value, uint256 deadline, uint8 v, bytes32 r, bytes32 s)"
  ]);

  export const vaultReadAbi = parseAbi([
    "function token() view returns (address)",
    "function pricePerShare() view returns (uint256)",
    "function maxAvailableShares() view returns (uint256)",
    "function decimals() view returns (uint8)"
  ]);

  export const cooldownVaultAbi = parseAbi([
    "function asset() view returns (address)",
    "function cooldownPeriod() view returns (uint256)",
    "function maxLossThresholdBps() view returns (uint256)",
    "function claim(uint256 requestId, uint256 maxLossBps) returns (uint256 claimable)"
  ]);
  ```
</Accordion>

## Quotes and minimum output

For quoted output `q` in raw token units and chosen slippage tolerance `s` in basis points:

```text theme={null}
minOut = floor(q * (10,000 - s) / 10,000)
```

| Quantity | Constraint                                                  |
| -------- | ----------------------------------------------------------- |
| `q`      | Positive integer; shares for deposit, USDT atoms for redeem |
| `s`      | Integer basis points, `0 <= s < 10,000`                     |
| `minOut` | Positive integer; reject quotes whose result rounds to zero |

* Set tolerance through an explicit product/user policy; refresh the quote before signing.
* Use integer arithmetic. A 100 bps tolerance equals 1%.
* Validate chain, wallet balance, allowance and KAIA for gas before submission.

## Deposit

| Step | Action                                                            |
| ---- | ----------------------------------------------------------------- |
| 1    | Parse USDT into 6-decimal atoms                                   |
| 2    | Read `previewDeposit(vault, amount)` and calculate `minSharesOut` |
| 3    | Select permit or approve flow below                               |
| 4    | Submit, wait for a successful receipt, refresh balances/activity  |

| Authorization          | Transaction                                                                                     |
| ---------------------- | ----------------------------------------------------------------------------------------------- |
| EIP-2612 permit        | `depositWithPermit(vault, amount, receiver, minSharesOut, deadline, v, r, s)`                   |
| ERC-20 allowance       | Confirm `allowance(owner, Router)`; `approve` if needed; `deposit(vault, amount, minSharesOut)` |
| Assigned referral code | Corresponding `depositWithReferral` or `depositWithPermitAndReferral`                           |

| USDT permit field | Value                                                                            |
| ----------------- | -------------------------------------------------------------------------------- |
| Domain            | `name: "Tether USD"`, `version: "1"`, `chainId: 8217`, `verifyingContract: USDT` |
| Message           | Owner, Router spender, exact amount, current nonce, short deadline               |
| Referral          | Assigned `bytes32` code; deposit only                                            |

**Cautions**

* Stop an attempt after a rejected signature. Offer approve-plus-deposit as a separate user action.
* User-facing deposits and redemptions MUST use the Router.
* Retain receipt amounts and transaction hashes for reconciliation.

## Redemption

| Step | Action                                                                              |
| ---- | ----------------------------------------------------------------------------------- |
| 1    | Share input: `previewRedeem`; asset input: `previewWithdraw`, then `previewRedeem`  |
| 2    | Read `maxRedeemableShares(vault)`; apply the integration's explicit capacity buffer |
| 3    | Check EarnUSDT ownership and Router allowance                                       |
| 4    | Compute `minAssetsOut`; submit `redeem(vault, shares, minAssetsOut)`                |
| 5    | Decode receipt events for request ID and filled amount                              |
| 6    | Refresh `/accounts/{account}/redemptions` and `/activity` until claimed             |

| Capacity / fill       | Meaning                                                         |
| --------------------- | --------------------------------------------------------------- |
| `maxRedeemableShares` | Vault-wide concurrent redemption-debt headroom                  |
| `type(uint256).max`   | Debt cap disabled                                               |
| Zero                  | No current headroom                                             |
| Partial fill          | Receipt records filled amount; Router returns unfilled EarnUSDT |

**Cautions**

* Quotes and headroom can change before inclusion. Preserve transaction failures for the user to review.
* Queue `shares` uses seCDV units; filled EarnUSDT comes from the Router receipt.
* Keep request IDs scoped to their queue contract and chain.

## Claim lifecycle

| Field / state                        | Meaning                                                             | Action                               |
| ------------------------------------ | ------------------------------------------------------------------- | ------------------------------------ |
| `status: pending`                    | Unpaid request                                                      | Refresh until claimed                |
| `claimability: ready / fully_funded` | Request plus earlier FIFO reservations funded at the observed block | Show current readiness               |
| `waiting / not_fully_funded`         | Funding incomplete at that block                                    | Continue refresh                     |
| `unknown`                            | Observation unavailable or unsupported                              | Show unknown readiness               |
| `status: claimed`                    | Durable settlement result                                           | Read `claim`; `claimability` is null |
| `cooldownEndsAt`                     | Normal repayment-window boundary                                    | Display alongside funding state      |

* The keeper normally settles fully funded requests, including before cooldown expiry.
* Earlier FIFO requests reserve liquidity first. Funding gaps can persist after expiry.
* Each claimability observation carries `basis: fully_funded_fifo`, `maxLossBps: 0`, `observedAt` and `blockNumber`.

### Optional direct claim

| Requirement          | Implementation                                                                     |
| -------------------- | ---------------------------------------------------------------------------------- |
| Intentional claim UX | Call `CooldownVault.claim(requestId, maxLossBps)`                                  |
| Preflight            | Simulate that exact call with `eth_call`, intended caller and loss tolerance       |
| Third-party caller   | `maxLossBps` at or below `maxLossThresholdBps`; higher tolerance requires receiver |
| Confirmation         | Show simulated payout and explicit loss tolerance                                  |

**Cautions**

* A direct-claim client MUST simulate immediately before submission. Clock status and `previewClaim` alone provide insufficient execution evidence.
* A ready observation can change before transaction inclusion.
* `SHOULD_WAIT`, `INSUFFICIENT_ASSETS` or `EXCESSIVE_LOSS` requires a fresh user decision; preserve the selected tolerance.

## Release checks

* Test decimals, partial evidence, cursor continuation and inactive holdings.
* Test rejected signatures, allowance, gas, debt-cap races and partial fills.
* Test early funding, post-cooldown funding gaps, FIFO reservations and claimed receipts.
* Save API request IDs, observation times and transaction hashes for support.