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.@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 bytransactWith, 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 aCofheDecryptor, 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 currentscreeningSigner, 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 ownbonusSigner. 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.