Reference
SDK reference
@recurvemoney/sdk wraps the contracts for all three roles: depositor, agent, and watcher. Every method, what it sends, and what it returns.
Package
npm install @recurvemoney/sdk viem
| Version | 0.1.0, MIT |
| Format | ESM only — no CommonJS build, no require |
| Runtime | Node 20+. Peer dependency viem ^2.21.0; no runtime dependencies of its own |
| Exports | Recurve, VaultReader, DepositorClient, AgentClient, WatcherClient; enums ProposalState, Verdict; types RecurveConfig, RecurveAddresses, VaultSnapshot, Proposal, RedeemResult, WatcherStake; ABIs vaultAbi, governorAbi, registryAbi, erc20Abi |
The SDK ships no chain definitions, no addresses and reads no environment. It never
formats: every amount is a bigint in on-chain base units.
Entry point
import {Recurve, ProposalState, Verdict} from "@recurvemoney/sdk";
const recurve = new Recurve({
publicClient, // viem PublicClient
walletClient, // viem WalletClient with an account; omit for read-only
addresses: {vault, governor, registry},
});
recurve.vault // VaultReader: snapshot, sharesOf, canRedeemInstantly, pendingRequests
recurve.depositor // DepositorClient: deposit, redeem, claim, veto
recurve.agent // AgentClient: propose, execute, settle, proposal, secondsUntilExecutable
recurve.watcher // WatcherClient: stake, castVerdict, stakeOf, blockCount, minStake
Each sub-client can also be constructed on its own with the same config. The config covers
one vault, its governor and its registry; the $RECURVE token address is not part of it and is
passed to stake directly. Nothing validates that the clients and the addresses are
on the same chain — pass a viem chain to both clients yourself.
How writes behave
Every write signs with the wallet's account, passes walletClient.chain through,
waits for the receipt, and returns the transaction hash (propose returns the
proposal id instead). No gas, nonce or value overrides are accepted. Only redeem
and propose simulate before sending; the rest rely on viem's gas estimate to
surface a revert. Every write rejects before any RPC call when it cannot sign — without a
walletClient, and with one that has no hoisted account:
This call needs a walletClient; the SDK was built read-only.
walletClient has no account attached.
VaultReader
| Method | Returns |
|---|---|
snapshot() | VaultSnapshot: address, asset, totalAssets, float, deployedAssets, totalSupply, sharePrice (asset base units per 1e18 shares; exactly 1e18 while supply is zero). Six reads, not one multicall — they can straddle a block |
sharesOf(owner) | Share balance |
canRedeemInstantly(shares) | previewRedeem(shares) <= float(). Advisory: the float can move before the transaction lands |
pendingRequests(owner) | Queue ids for an owner. There is no read for a request's status; claim reverts until it is ready |
DepositorClient
deposit(assets: bigint, opts?: {skipDelegate?: boolean}): Promise<Hex>
redeem(shares: bigint, receiver?: Address): Promise<RedeemResult>
claim(requestId: bigint): Promise<Hex>
veto(proposalId: Hex): Promise<Hex>
deposit — up to three transactions: an unlimited
approve of the asset to the vault if the allowance is short, deposit
with the signer as receiver, then delegate to the signer unless
skipDelegate. Delegates on every deposit. Returns the deposit hash only. The deposit
cap is enforced by the contract, not checked here.
redeem — simulates requestRedeem(shares, receiver ??
signer, signer), sends it, and returns:
interface RedeemResult {
instant: boolean; // the float covered it and the exit cleared in this transaction
requestId?: bigint; // queue position; absent when instant
txHash: Hex;
}
instant comes from the simulation; requestId is corrected from the
WithdrawalQueued event in the receipt. Its type is bigint | undefined
and TypeScript will not narrow it from instant — check it explicitly.
claim — claimRedeem(requestId); reverts
RequestNotReady until the idle balance covers the request. Assets go to the
receiver fixed at redeem time. veto —
governor.veto(id); the SDK exposes no read for the threshold or for a holder's
weight at the snapshot.
AgentClient
propose(target: Address, assets: bigint, callData: Hex = "0x"): Promise<Hex> // the proposal id
execute(proposalId: Hex): Promise<Hex>
settle(proposalId: Hex, returned: bigint): Promise<Hex>
proposal(proposalId: Hex): Promise<Proposal> // read
secondsUntilExecutable(proposalId: Hex): Promise<number> // read
propose simulates, sends, and returns the id from the
ProposalPosted event — not the simulated value, which goes stale the moment the
transaction lands in a different second. The transaction hash is not returned. Empty calldata
posts a funds-only proposal.
interface Proposal {
id: Hex; target: Address; assets: bigint; callData: Hex;
postedAt: bigint; // unix seconds
snapshot: bigint; // block whose vote weights count: one before the proposal landed
vetoWeight: bigint;
state: ProposalState; // None 0, Pending 1, Vetoed 2, Blocked 3, Executed 4, Settled 5
}
An unknown id returns all-zero fields with state === ProposalState.None rather
than throwing. secondsUntilExecutable compares
executableAt with the machine's clock and clamps at zero, as a JS
number; zero means the window has closed, or the id is unknown. Not exposed:
vetoWindow, isAgent, any proposal listing (ids come from
ProposalPosted logs, which you scan with viem).
WatcherClient
stake(token: Address, amount: bigint): Promise<Hex>
castVerdict(proposalId: Hex, verdict: Verdict): Promise<Hex>
stakeOf(watcher: Address): Promise<WatcherStake> // read
blockCount(proposalId: Hex): Promise<bigint> // read
minStake(): Promise<bigint> // read
stake takes the $RECURVE token address (the parameter is
still named arcToken in the published typings), approves the registry without
limit if the allowance is short, and stakes. It does not compare amount with
minStake. castVerdict sends Verdict.Approve
(1) or Verdict.Block (2); it does not stop you sending None, which the
contract counts as a block — don't.
interface WatcherStake { stake: bigint; pendingUnstake: bigint; unstakeRequestedAt: bigint; active: boolean; }
Not exposed as methods: requestUnstake, unstake,
isActive. They are in registryAbi; call them with viem directly, as on
the watcher skill.
ABIs and errors
The four exported ABIs are trimmed to what the clients call and carry no error
entries, so a revert through the SDK arrives as an undecoded selector. To see names like
VetoWindowOpen in viem's errors, decode with the full ABI from the protocol repo
(the app carries every custom error in app/src/lib/abi.ts).