Smart Contracts
Choose a contract for funding, private transfers, merchant payments or recovery.
Choose a contract#
ActionPool holds supported assets and checks the proofs that spend private notes. The contracts around it handle receiving addresses, wallet approvals, prepaid payment budgets and calls to external venues. Choose the interface by the result you need: a private note, a public withdrawal, merchant credits or the output of a DeFi action.
Your client keeps the private keys and note openings. It sends contracts the public proof signals, encrypted delivery envelopes and execution request. Sessions and subscriptions hold public budgets, so their parties, amounts and progress are visible onchain. Funding one with private assets makes that payment public, even if you later return a refund to the Pool.
Contract map#
The names below refer to implementations in the protocol repository. Load addresses from the deployment your app uses. The same contract name on two chains refers to two separate deployments. Check the deployed code as well as any address predicted by a factory.
| Component | Contracts | Responsibility |
|---|---|---|
| Confidential custody | ActionPool, ActionPoolKernel | Hold assets, maintain notes and nullifiers, check screened spends, and settle withdrawals and actions |
| Source admission | PolicySet, FuyuGovernor, FuyuCoverageRenewer | Maintain the source list, delay configuration changes, and renew coverage |
| Proofs and hashes | PinnedSpendVerifier, SpendGroth16Verifier, Poseidon3, TreeConstants | Verify spends with a fixed key and compute scalar-field commitments and tree hashes |
| Account recovery | FuyuAccountRegistry, FuyuAccountRegistryFactory | Store independent accounts, their fixed controllers and versioned encrypted profiles |
| Receiving | FuyuReceiveDirectory | Publish versioned receiving descriptors with the public owner's approval |
| Deposit addresses | FuyuDepositRecoveryPortal, FuyuAnonymousPortal, FuyuAnonymousPortalFactory | Receive ordinary ERC-20 transfers, then credit private notes or recover to a fixed destination |
| Private claim links | FuyuClaimController, FuyuClaimControllerFactory | Authorize the recipient before a deadline and the refund signer afterward |
| Public escrow | FuyuUnregisteredEscrow | Let a recipient claim a public token payment before a timed refund |
| Atomic sequencing | FuyuTransactionRouter | Settle an action immediately or run up to eight private spends in order |
| Venue execution | Yield, swap, plan, ticket and payment-credit adapters | Execute a fixed operation for one Pool and measure the input and output |
| Payment budgets | FuyuPaymentSessions, FuyuPaymentAuthorizations, FuyuSubscriptionPayments | Settle cumulative vouchers, reserve holds and charge prepaid billing periods |
| Payment funding | FuyuSessionFunding, FuyuPaymentFunding, FuyuPaymentSplitter | Deploy fixed funding terms, handle close/refund calls and pay fixed beneficiary shares |
| Earn | FuyuEarnVault, FuyuEarnAdapter, FuyuEarnToken | Manage Flex, Term and withdrawal tickets, including their return to private notes |
| Migration | FuyuMigrationReceiver, FuyuMigrationReceiverFactory | Receive assets from a fixed source and credit the chosen Fuyu account |
| Venue catalog | ReviewedVenueRegistry | Track Active and ExitOnly venues against their code hashes and identities |
Check the deployment#
Save the chain identifier, Pool address and deployment block before scanning history or making a proof. Read domain, spendVerifier, accountRegistry and policyPublisher from that Pool. The domain includes the chain and Pool address, so accounts and proofs from another deployment are not interchangeable.
The deployment artifact should list the other contract addresses, their Pool or rail connections and expected runtime code hashes. Factory addresses also depend on the constructor terms. Check the factory and those terms before approving an allowance or sending assets to a Portal or escrow.
Use the deployment manifest to configure the app, then read current state at a known block. Token support, route admission, source coverage and wallet policy can change after deployment. To check liquidity, query the venue; compiling its contracts locally tells you nothing about its live capacity.
Who can change what#
The holder proves ownership of the input notes. If those notes have a spending controller, that controller must also approve execution. A relayer can submit the public inputs, but the proof fixes the recipient, fee payee and delivery envelopes. Anyone can finalize an action that has already executed; the finalizer cannot take its output.
The publisher admits new tokens and adapter routes and manages source policies. After genesis, a governor delays proposals that widen admission. Disabling a token stops new deposits without blocking withdrawal of notes already credited in that token. The guardian can make specified risk-reducing changes but has no general permission to transfer assets.
Each payment rail has its own authority rules. Voucher signers authorize cumulative earnings. Merchant operators capture registered holds. Any caller can charge the current subscription period under the fixed terms. Refunds always go to the recorded beneficiary, regardless of who calls the refund function.
Submit and check an operation#
Load a deployment, check how its contracts connect, and recover history through finalized blocks. Read the state your operation depends on. Build the request, prepare the proof or signature, save the intent and simulate the transaction before submitting it. If submission times out, check its receipt and contract state before retrying.
Contract amounts use native token units. Keep calculations in integers and convert values for display in your UI. Store the token address and decimals together; budgets, cumulative vouchers, minimum outputs and note amounts all depend on that asset identity. Confirm payment from settlement state, not an allowance change or HTTP response.
- Read the Pool reference for custody, proofs and queued outputs.
- Read Portals for wallet and exchange transfers into private balances.
- Read payment rails for streaming, API usage, holds and subscriptions.
- Read adapters for swaps, yield, ordered plans and asynchronous tickets.
Reference revision#
This reference describes protocol revision 4def6e17d671d284e755a03d07d99a925b631512. Before using a venue, check that your Pool admits its adapter, ordered asset pair and operation. Source code for an adapter does not make that route available on every chain.
The Networks guide lists deployment addresses, supported assets and faucets. This revision uses development proof keys. An independent audit, production key ceremony and mainnet release are still separate requirements.