Routers and Adapters

How calls reach a venue#

The Pool holds private assets and checks proofs. An adapter executes a specific operation at a public venue. The router calls existing Pool functions in order. The proof fixes the private receiver, so neither the router nor the adapter can substitute another recipient.

A route key contains adapter, uint8 operation, input asset and output asset, in that order. The Pool records the admitted adapter runtime hash and checks privacyPool. Reversing direction or changing the operation or pair needs a separate admission. Deploying an adapter is only the first step; the publisher must admit its route before the Pool can use it.

Transaction router#

FuyuTransactionRouter holds no tokens or allowances and has no privileged role. transactActionAndFinalize forwards an action to the Pool and emits ActionSettledInOneTransaction. The Pool appends the measured output note before the transaction completes. Any failure reverts the call.

transactBatch forwards one to eight TransactCall entries in order, each with its own authorization. A later proof can refer to the root created by an earlier call in the transaction. This lets you chain change notes for multi-recipient sends or consolidate notes without waiting between transactions. EmptyBatch and BatchTooLarge reject calls outside those bounds.

A submitted bundle runs atomically, but anyone who sees its proofs can also submit them individually to the Pool. Design each proof as a complete authorized payment. Releasing a bundle does not revoke those individual submission paths, and secrecy is not an execution guarantee.

struct TransactCall {
    ActionPoolKernel.Proof proof;
    uint256[39] signals;
    ActionPoolKernel.Request request;
    bytes[2] kemCiphertexts;
    bytes senderCapsule;
    bytes safeSignatures;
}
function transactBatch(TransactCall[] calldata _calls) external;
// MAX_BATCH = 8

// IActionAdapter callback; implemented by adapters and called only by the Pool.
function execute(
    uint8 _operation, uint256 _amountIn, uint256 _minOut,
    uint256 _deadline, bytes32 _actionData
) external returns (address tokenOut, uint256 amountOut);

Adapter types#

Only the Pool can call execute. The adapter takes a positive exact input and returns the output token and measured amount. Its constructor and operation rules constrain actionData and the permitted venue calls. A caller cannot use it to forward arbitrary targets or calldata.

Fixed multi-step plans#

FuyuPlanAdapter fixes the input/output, steps, code hashes and static identity checks at deployment. A plan has at most four steps. It supports Uniswap V3 exact-input single-hop or two/three-hop paths and ERC-4626 deposit/redeem. Every token on the plan is distinct. Read steps, tokens, codePins, identityPins and planDigest to inspect what the adapter will execute.

The proof sets one final minimum. The adapter derives earlier floors when the remaining vault steps have deterministic previewMint or previewWithdraw conversions. Otherwise, an earlier step must produce a nonzero output and the final minimum checks the overall result. Users cannot replace targets or supply arbitrary intermediate floors at execution.

Each step's reported output must match measured balance changes. The final step pays directly to the Pool. After execution, adapter balances must return to their starting values, allowances must clear and identities must still match. StepFailed wraps a venue revert, StepInexact reports dishonest or partial effects, and StepBelowFloor reports a short output. Any of these rolls back the whole action.

Asynchronous withdrawals#

When a vault accepts only a withdrawal request, the underlying is not available yet. AsyncRedeemTicketAdapter issues a fungible ticket for the requested position. You can hold that ticket in a private Pool note. harvest settles venue requests that are ready and records the assets or cancelled shares received.

Use lifecycle, batchCount and previewClaim to show pending, claimable and refundable positions. A later private action consumes tickets to claim underlying or refund shares. Previews reflect the current venue state; a submitted request still needs settlement. Show ticket units separately from their estimated underlying value and retain the ticket token address.

Redeem settled payment credits#

FuyuPaymentCreditAdapter supports REDEEM = 0 and requires actionData zero. It fixes Pool, credit issuer, backing asset, chain and code hashes. Input must be positive and fit uint128. The output minimum must also be positive and no greater than the input.

The adapter checks Pool and adapter balances, the credit supply burn and the underlying gain. Redemption must return one underlying unit per credit unit. It cannot reserve holds, authorize usage or claim an unsettled session. First settle the earnings or refund on the rail; only then are the credits transferable.

Add an adapter route#

Choose an operation with known input and output assets. Record dependency code hashes, transfer behavior and receiver restrictions. For upgradeable venues or tokens, also check implementation or registry state where needed; a proxy's runtime hash alone will not identify its implementation. Use exact-transfer nonrebasing assets unless your accounting design handles other behavior.

Build the quote and proof with the same route, amount and minimum. Before broadcasting, check venue identity, capacity and expiry again. Test reentry, dishonest reports, changed dependencies, partial pulls, donations, leftover approvals and failure at the final append. After revoking new action admission, verify that holders can still exit directly and finalize queued outputs.

DeFi calls expose input, intermediate and output amounts, venue paths and timing. They omit the private note owner, but those public amounts and times can still link activity. Explain that visibility in the product instead of describing the venue call as confidential.