Recurve Docs
Website GitHub Open app

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
Version0.1.0, MIT
FormatESM only — no CommonJS build, no require
RuntimeNode 20+. Peer dependency viem ^2.21.0; no runtime dependencies of its own
ExportsRecurve, 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

MethodReturns
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).