Earn (ERC-4626 Vaults)

Earn lets a user put a shielded balance to work in an ERC-4626 yield vault (for example a Morpho vault) and pull it back out — without the funds ever leaving the shielded pool. A deposit spends a private asset note, routes it through the vault via the external call gateway, and credits the vault shares back as a new private note; a withdraw redeems those share notes the same way. The vault call itself is public on-chain, but the account that owns the deposited note is not.

Preview feature — pending external audit. The External Call Gateway (Earn) moves user funds through operator-approved external targets and ships to mainnet only after a gateway-specific security audit (see the External Call Gateway Audit Gate in AUDIT_SCOPE.md). Treat the API as stable-but-unaudited and gate production use on your own review. Earn is enabled per deployment: the server advertises the executor as externalGatewayAddress in /info only when the gateway is enabled. Detect support at runtime with sdk.vault.getGatewayConfig(), which returns the executor address, request constraints, and availability. Deployments without a gateway return enabled: false; feature-gate on that field and the relevant availability.

How it works

An earn deposit is a gateway unshield. Instead of paying a private note out to a public address, the SDK signs an authorization that lets the gateway run the vault call and credit the result straight back into the pool:

 asset note (private) ──spend──▶  gateway executes vault deposit  ──▶  share note (private)
                                          │
                        failure / expiry / below minOut
                                          ▼
                                  input refunded as a private note

Preview & authorize. The SDK reads the vault on-chain (asset(), previewDeposit / previewRedeem), derives a minOutputAmount floor from your slippage bound, and signs the PB:WITHDRAW:GATEWAY authorization for exactly that request.
Execute. The gateway spends the input note and calls the vault. The output is measured on-chain, not trusted from the preview.
Credit. The measured vault output is credited as a new gateway-origin private note. The owner’s identifying keys never appear in the transaction.
Refund on failure. If the vault reverts, the request expires, or the fill would land below the signed minOutputAmount, the input is refunded as a private note via the fallback receipt. Funds never leave the pool uncredited.

A withdraw is the mirror image: it redeems share notes and credits the asset output.

SDK API shape

The earn surface lives on the vault resource (sdk.vault). Reads are public; the two write operations require an authenticated session.

Method	Auth	Purpose
`getGatewayConfig()`	public	Gateway discovery: executor address, request constraints, rescue delay, availability. Use it to feature-gate.
`listEarnVaults()`	public	Vault catalog: APY, TVL, warnings, and per-operation availability.
`getEarnVaultHistory(vault, metric, period?)`	public	One cached chart series (TVL or net APY) for a vault.
`getEarnVaultCharts(vault, period?)`	public	Both chart series for a vault, fetched concurrently.
`earnDeposit(params)`	session	Deposit assets into a vault; credits a share note.
`earnRedeem(params)`	session	Redeem share notes; credits an asset note.

earnDeposit / earnRedeem take an EarnParams. amount is net — exactly what enters the vault call (assets for a deposit, shares for a redeem); the unshield fee is charged on top, so your notes must cover amount + fee. maxSlippageBps bounds the fill below the on-chain preview (default 100 = 1%).

// Detect gateway support and browse vaults — no session required
const gateway = await sdk.vault.getGatewayConfig();
const vaults = await sdk.vault.listEarnVaults();

// Deposit 100 USDC (net) into a vault; the fee is charged on top
const result = await sdk.vault.earnDeposit({
  vaultAddress: '0xVault…',
  amount: 100_000000n,   // net assets entering the vault (6-decimal USDC)
  maxSlippageBps: 100,   // reject a fill more than 1% below the preview
});

// Later: redeem shares back to the underlying asset
await sdk.vault.earnRedeem({ vaultAddress: '0xVault…', amount: shares });

privacy-boost earn vaults
privacy-boost earn deposit  --vault 0xVault… --amount 100 --human --decimals 6
privacy-boost earn withdraw --vault 0xVault… --amount 50  --human

Tracking settlement

An earn operation returns an EarnResult with a requestId. Because the credit lands in a later epoch than the unshield, poll the unshield status and read the gateway projection — gateway.creditStatus === 'completed' is the terminal state. The top-level completed flag only covers the unshield epoch, not the vault credit.

privacy-boost earn status <REQUEST_ID>

Vault history charts

getEarnVaultHistory and getEarnVaultCharts return cached TVL and net-APY series suitable for rendering a chart. Both are public — usable before login.

metric is 'tvlUsd' or 'netApy'; period is '1w' | '1m' | '3m' | 'all' (server default 1w). getEarnVaultCharts fetches both metrics at once and rejects if either fails — call getEarnVaultHistory twice if you want partial results.
APY values are decimal ratios (0.05 = 5%); TVL values are USD. Points ascend by timestamp.
A null points[].value is an upstream gap — render it as a gap rather than interpolate across it.
Check metadata.state before presenting the data as current. Today it is one of fresh, stale (upstream unavailable — this is the last good series), synthetic (deterministic testnet data), or unsupported. It is an open set: treat an unrecognized state as renderable data of unknown freshness, not an error.
While the server’s cache warms, a cold request may answer 503 with a retry-after hint; the SDK’s standard retry policy already honors it.

const { tvlUsd, netApy } = await sdk.vault.getEarnVaultCharts('0xVault…', '1m');
for (const point of netApy.points) {
  if (point.value === null) continue; // upstream gap
  plot(point.timestamp, point.value); // decimal ratio: 0.05 = 5%
}

# One series
privacy-boost earn history --vault 0xVault… --metric netApy --period 1m
# Both series (omit --metric)
privacy-boost earn history --vault 0xVault…

Trust and privacy

Earn is a deposit-and-credit extension: the gateway can only spend the note you authorize and credit the measured result back into the pool. It grants no new authority to move or seize funds.

Actor	Can	Cannot
Owner	authorize a deposit/redeem of their own notes; spend the credited note	—
Gateway executor / operator	run the approved vault call; measure and settle the exact output	learn which account owns the note; redirect the credit; spend from the pool
Relay / prover	submit the gateway epoch from non-spend values	change the amount, target vault, or recipient; credit a different account
TEE	observe the request; derive the owner’s credited note via the registry	sign anything; custody, move, or seize funds

A gateway-origin note joins the same shared note tree as every other deposit and transfer, so its anonymity set is the full mixed pool. Earn hides who deposited into the vault, not that the vault was used — the vault call (target and amount) is public on-chain. The minOutputAmount floor is signed, so no operator can settle a deposit into a worse-than-authorized fill; the worst case is a refund of the input.

Launch limitations

These are known constraints of the current (pre-audit) preview; design around them:

Pre-audit. The gateway contracts are outside the completed audit scope until the External Call Gateway Audit Gate clears. Do not custody significant value on it in production before then.
Enabled per deployment. A deployment without a gateway has no externalGatewayAddress in /info, and getGatewayConfig() returns enabled: false. Always feature-gate on enabled and the operation’s availability.canSubmit value.
Operator-curated catalog. Only vaults the operator approves are usable. listEarnVaults() reports per-operation availability and any warnings — honor them before offering a deposit.
Slippage is a floor, not a guarantee of execution. A fill below the signed minOutputAmount refunds the input via the fallback receipt instead of executing; surface that outcome rather than treating the request as failed.
History is a best-effort cached read. Freshness is reported by metadata.state, and a cold cache can briefly 503. Do not treat a stale or unknown state as an error.
Single-chain. Earn works on a chain that hosts both a pool and a deployed gateway.

Using it from the SDK

TypeScript / WASM — the earn methods on sdk.vault. See the TypeScript API reference.
CLI — the earn subcommands. See the Commands reference.
iOS / Android / React Native — the earn deposit/redeem and catalog methods plus JSON-passthrough history reads (getEarnVaultHistoryJson, getEarnVaultChartsJson), matching the existing earn read surface.

Quickstart

Setup

SDKs

Earn (ERC-4626 Vaults)

Earn (ERC-4626 Vaults)

How it works

SDK API shape

Tracking settlement

Vault history charts

Trust and privacy

Launch limitations

Using it from the SDK

​Earn (ERC-4626 Vaults)

​How it works

​SDK API shape

​Tracking settlement

​Vault history charts

​Trust and privacy

​Launch limitations

​Using it from the SDK

Earn (ERC-4626 Vaults)

How it works

SDK API shape

Tracking settlement

Vault history charts

Trust and privacy

Launch limitations

Using it from the SDK