SDK

Install

The SDK lives in the repo as packages/sdk and ships as TypeScript source (ES modules). Inside the monorepo, depend on it with "@hushd/sdk": "workspace:*". Node-only helpers, an encrypted note file and cached proving artifacts, are in @hushd/sdk/node.

Call loadPoseidon() once before anything that hashes: identities, notes and proofs all use it.

A trade, end to end

import {
  awaitMatch, checkMatchedTerms, DeskApi, identityFromSeed, loadPoseidon, openRfq,
  packageRequest, PrivateWallet, RelayerClient, settleAsTrader, TESTNET,
  type PackageDraft,
} from "@hushd/sdk";
import { cachedArtifacts, EncryptedFileStore } from "@hushd/sdk/node";

await loadPoseidon();
const id = identityFromSeed(seed); // 32 bytes you keep secret
const relayer = new RelayerClient(TESTNET.api);
const api = new DeskApi(TESTNET.api);
const wallet = new PrivateWallet(TESTNET, id, {
  artifacts: await cachedArtifacts({ cacheDir: ".hushd/circuits" }),
  relayer,
  store: new EncryptedFileStore(".hushd/notes", seed),
});
await wallet.restore();
await wallet.sync();

// Sell 100 USDC for wNEAR, taking the best quote.
const draft: PackageDraft = {
  kind: "spot",
  sell: { token: "usdc.hushd.testnet", amount: 100_000_000n },
  buy: { token: "wnear.hushd.testnet", minAmount: 0n },
};
// the request names a one-time address for this deal alone (dealIdentity), never yours
const { request, ask, refundBlinding, dealIdentity } = packageRequest(id, TESTNET, draft);
const { rfqId } = await openRfq({ net: TESTNET, api, relayer, request, ask, windowMs: 45_000 });
const match = await awaitMatch(api, dealIdentity, rfqId);
checkMatchedTerms(match.terms, draft); // throws unless the match is what you asked for
const { moved } = await settleAsTrader({
  net: TESTNET, api, wallet, refundBlinding, // re-derives the deal's owner key and its one-time address
  dealId: match.dealId, terms: match.terms, makerAddress: match.maker_address,
});
// moved.state "moved": the tokens are in your balance; "waiting": the next wallet.sync() moves them

The enclave picks the best quote, but you check the result before your leg is proved: checkMatchedTerms refuses a match that pays less than your minAmount, in another token, or as another package. A deal you do not settle simply expires.

For a hedged package, keep the refundBlinding that packageRequest returns: it re-derives the key that closes the hedge, the note a slashed bond pays you, and the deal's one-time address. The maker pays your leg to that address; the wallet keeps the note's opening and moves it into your balance with a private send through the relayer, trying again on each sync until it lands. The desk page in the app does exactly this, in app/src/app/app/page.tsx.

A private payment

// The deposit is yours to sign: send call to the token contract (1 yocto attached).
const { call, selfPost } = wallet.shield("usdc.hushd.testnet", 25_000_000n);
await relayer.post(selfPost, "note"); // so your seed alone can recover this note

// Later, from the private balance, through the relayer.
const { txHash } = await wallet.send("hushd1…", "usdc.hushd.testnet", 10_000_000n, "invoice 7");

Pay as a link

To pay someone who is not on Hushd yet, pay into a one-time note and hand them a link. The link carries the note's opening after the #, which browsers never send to a server. Whoever opens it first claims the payment into a new note for their own receive key, made on their device, so after the claim you cannot spend it back. Until then you can take it back.

import { checkLink, claimLink, linkUrl, parseLink, payAsLink, sentLinks, takeBackLink, TESTNET } from "@hushd/sdk";

// The payer: the link is saved in the wallet's encrypted store before the payment goes out.
const { link } = await payAsLink(wallet, "usdc.hushd.testnet", 25_000_000n);
const url = linkUrl("https://hushd.net", link); // https://hushd.net/app/claim#…, share it privately

// The claimer: check the pool first, then claim into their own wallet. The relayer pays the gas.
const theirs = parseLink(url);
const check = await checkLink(TESTNET, theirs); // "ready", "claimed" or "missing"
if (check.state === "ready") await claimLink(theirs, { to: theirWallet, artifacts, relayer, tree: check.tree });

// Later, the payer: where each link stands, and taking back one nobody claimed.
const [first] = await sentLinks(wallet); // state: "waiting", "claimed", "taken back", …
if (first?.state === "waiting") await takeBackLink(wallet, first.link, { artifacts, relayer });

Exports

Lower down, the SDK also exports what these are built from: notes (makeNote, nullifierOf), the Merkle tree (MerkleTree, depth 20), Poseidon, the joinsplit prover, the pool's call arguments (shieldCall, transactRequest, swapLeg), the domain hashes (assetField, extHash, swapExtHash, proofContext) and the sealed boxes (sealJson, openJson).

Guardrails

• The SDK never holds a NEAR key. A deposit is a call you sign; everything private goes through the relayer.
• Proofs are made where the SDK runs. The prover needs the circuits' artifacts, checked against their sha256 in manifest.json.
• The relayer checks every proof before sending it, and can refuse. It cannot change what was proved.