Skip to main content
The Fluton SDK is not yet published to npm. It will ship as @fluton/sdk. This page lists the pool client as it exists today; the planned intent client is described on Intent client.
The Fluton Pool client has two entry points. @fluton/sdk is the full surface, including the snarkjs prover and its node wrappers (proof, transact) and the node CoFHE client (cofheNode). @fluton/sdk/browser leaves those three out and exports inputs, the circuit-input assembly, directly; the node entry reaches the same names through proof. Everything else is in both, and the tables say when an export is not. Throughout, amounts are bigint in note units, asset ids are 1-based numbers, publicClient and walletClient are viem clients, and pool is the pool’s address.

Keys and addresses

One secret, the spend key, derives everything else: the Poseidon keypair notes are created for, the x25519 keypair ciphertexts are encrypted to, the shielded address a payer needs and the read-only view key. Keys and view keys explains the split; Notes and proofs explains the note itself. Types: SpendKeyDomain (chainId, pool), Keypair (publicKey, plus privateKey and nullifierKey when present), Utxo (amount, asset, blinding, keypair, index, its leaf position, once landed, encryptTo for watch-only outputs), ShieldedAddress, EncryptionKeypair and ViewKey.

Scanning and the tree

Scanning rebuilds the pool’s commitment trees and discovers the notes a key owns by trial decryption. An indexer is an optional accelerator that is verified against the pool before a single leaf is trusted; Keys, notes and scanning walks through the checks. A leaf’s position is its tree’s number times 2^levels plus its index in that tree. It is what the pool logs for every commitment and what a note’s index holds, and it identifies a note on its own: the pool starts another tree when a transaction’s three leaves no longer fit the current one (Notes and proofs). ScanOptions is the window: fromBlock (default 0), chunkSize (unset means one call), toBlock (default the latest block, read fresh) and indexer. IndexerSource is url, chainId, pool, and optionally timeoutMs (default 8000), pageSize (default 5000) and onFallback. A scan returns DiscoveredNote values (utxo, spent) and AssetBalances, asset id to bigint; an IndexedCommitment is commitment, index (the position) and encryptedOutput. A failed indexer check raises IndexerError internally and the scan continues from RPC.

Pool reads

The read side of the pool: its configuration and asset registry, the fee arithmetic, ExtData, and the receipt, obligation and attempt records. TOKEN and eTOKEN explains the records; Fees and referrals explains the arithmetic. Types: PoolConfig, PoolAsset (id, wrapper, underlying, rate), PoolFormat ("confidential" or "public"; FORMAT_CODE maps them to 0 and 1), ExtData, ReferralBonus (fixedBps, expiringBps, expiresAt, issuedAt), DepositState, ObligationState, AttemptState, ObligationWithAttempts, WrapperClaim and TxEffects. The enums mirror the pool: DepositStatus (None, Pending, Verified, Failed, Finalized, Cancelled), ObligationKind (Withdraw, Refund, Burn), ObligationStatus (None, InFlight, RetryAllowed, Settled) and AttemptStatus (None, InFlight, Succeeded, Failed). WithdrawFeeChangedError carries bound, current and bps.

Transactions

Every transaction is one join-split assembled by transactWith, proven by a ProveFn the caller supplies, and submitted from a wallet or through a relayer. The node entry wraps it with the snarkjs prover; a browser supplies its own. Deposits, withdrawals and transfers describes the flow step by step. TransactParams takes pool and asset, and optionally inputs, outputs (at most two), extAmount, withdrawFee, format (default "confidential"), recipient, fee, depositId, referrer, screen, wrapEther, onStatus, scan, relay and the TxHooks under Outcomes. WithdrawParams is pool, notes, amount, recipient, format and the options; TransferParams is pool, notes, amount, to and the options without withdrawFee. A TransactResult carries hash, all three outputs with leaf indices, feeNote when relayed, the withdrawFee kept and effects. TransactionCircuitInputs, SolidityProof, ProveFn and CircuitFiles describe the proving side. WrapEtherParams is token, need (the token base units the wallet must hold afterwards) and optionally onStatus, pollMs and polls; a WrapEtherResult is wrapped (0 when nothing had to be wrapped) and the wrap’s hash when one was sent. InsufficientEtherError carries needed and held, in wei.

eTOKEN deposits, obligations and claims

Everything on the Fhenix CoFHE side: token-first eTOKEN deposits, the authenticated confirmation of every confidential movement, retries, wrapper claims and encrypted balances. The functions that decrypt take a CofheDecryptor, which a connected client from @cofhe/sdk satisfies; the browser builds its own, and the node entry offers createNodeCofheClient. TOKEN and eTOKEN explains why a receipt alone proves nothing here. ConfirmOutcome is either { kind: "confirmed", success, hash } or { kind: "stale", status }; DecryptedForTx is { value, signature }. An UnwrapResult is unshieldHash, claimId, the claim’s hash (null when it had been claimed already) and the amount unwrapped. UnwrapHooks are onStatus, onSubmitted(hash), called when the unshield is sent, and onUnshielded({ hash, claimId }), called when it ran: persist what they hand you, because once the unshield ran only its claim pays the tokens back. UnwrapShortfallError (requested, unwrapped, claimHash) means the encrypted balance was below the amount asked for, so less was burned, possibly nothing; what was burned has been claimed.

Relayer client

A relayer submits a finished transaction and pays the gas in exchange for a fee note in output slot 2. The client reads the relayer’s identity before any proof is made and quotes the fee at current gas prices. Running a relayer documents the service itself. A RelayClient carries address, pool, chainId, noteAddress (parsed) and noteAddressText, and minFees per served asset id. RelayQuote has at, gasPrice and fees keyed by asset id and kind. The errors are RelayFeeChangedError (offered, fee, min, thrown before proving), RelayRefusedError (a 400: nothing was broadcast) and RelayOutcomeUnknownError (anything else: the transaction may have been sent; nullifiers names the notes). RelayStatus and RelayFeesResponse are the JSON bodies of GET /status and GET /fees. FEE_SLOT is 2.

Screening

Every pull of value needs a screening of the depositor. The SDK fetches it through the backend API client, checks it against the pool’s current screeningSigner, renews it when it is close to expiry and replaces it once when the pool calls it stale. Deposit screening explains where the verdict comes from. A DepositScreening is nonce, expiresAt (unix seconds) and signature (65 bytes); a ScreenFn is any function returning a fresh one, and a ScreeningSubject is the chainId, pool and depositor it certifies. ScreeningRefusedError carries the depositor and screening’s code and reason when given. SCREENING_MIN_REMAINING_S is 60, MAX_SCREENING_TTL_S is 3600, and DEPOSIT_SCREENING_TYPES is the typed-data definition.

Referrals and bonuses

The pool credits a deposit’s referrer by address. Short codes, the Discord and voucher-code bonuses and deposit screening live in Fluton’s backend API, which the SDK treats as untrusted: every record is wallet-signed and verified before use, and a bonus attestation is checked against the pool’s own bonusSigner. Invite and referrals shows the wallet side. Types: ApiClient, ApiHealth, ReferralDomain (chainId, pool), ReferralClaim, ReferralRecord (a claim with signature and updatedAt), ReferralRef, ReferralBonusDomain, ReferralBonusAttestation (a ReferralBonus with its referrer), SignedReferralBonus, BonusCodeClaim, DiscordLinkClaim, BonusStatus, DiscordBonusRoleInfo (a role’s name and the bps it adds, as the API lists them) and ChainClock (what waitForBonusDate needs of a public client). Errors: ApiError (status, 0 when unreachable), ReferralError, ReferralBonusError, BonusError. The EIP-712 domain is REFERRAL_BONUS_DOMAIN_NAME (PrivacyPool) and REFERRAL_BONUS_DOMAIN_VERSION (1), with REFERRAL_BONUS_TYPES and REFERRAL_BONUS_PRIMARY_TYPE as the typed-data definition; REFERRAL_CODE_PATTERN, BONUS_CODE_PATTERN and DISCORD_TICKET_PATTERN are the formats.

Outcomes

A hash is a poor handle for a transaction: a relayer’s re-send changes it and the page may be gone before it arrives. What never changes is the proof, so the SDK hands you its identity before anything is sent and answers from pool state afterwards. TxHooks has onPrepared(tx), called with a PreparedTx (pool, root, nullifiers, commitments, fromBlock) while nothing has been sent, where throwing aborts the send, and onSubmitted(hash), called as soon as it is on its way, where an exception is ignored. TxOutcome is one of landed (with hash, receipt and effects), reverted (with hash), superseded (with by) and pending; the first three are final. The pool keeps every root, so a prepared transaction stays valid until its notes are spent. TransactionRevertedError carries functionName and hash.

Chains

The public networks the pool client knows, as viem chains, and the Chainlink ETH/USD feed of each.

ABIs and constants

Both entry points export the ABIs the SDK calls through: poolAbi, erc20Abi, wrappedEtherAbi and confidentialWrapperAbi. The constants below are the protocol’s fixed points, shared with the circuits and the contracts. The concept pages behind these numbers are Notes and proofs, Private transfers and Fees and referrals.