@vaultline-app/sdk

Typed TypeScript SDK for Vaultline on Robinhood Chain: token locks, burns, commitment checks and ERC-8021 referral tags. It wraps viem and has no React dependency.

Status: v0, testnet first. The contracts are not audited yet, and BurnRouter is testnet-only until its audit is done. Pin an exact version.

Install

npm install @vaultline-app/sdk viem

ESM only, Node 20+ or any modern bundler. Types are included.

Setup

import { createVaultline } from "@vaultline-app/sdk";
import { createPublicClient, createWalletClient, custom, defineChain, http } from "viem";

// Robinhood Chain testnet (chain 46630). Mainnet is chain 4663.
const robinhoodTestnet = defineChain({
  id: 46630,
  name: "Robinhood Chain Testnet",
  nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
  rpcUrls: { default: { http: ["https://rpc.testnet.chain.robinhood.com/rpc"] } },
});

const vl = createVaultline({
  publicClient: createPublicClient({ chain: robinhoodTestnet, transport: http() }),
  // Only needed for writes (lock, extendLock, burn). Must carry an account.
  walletClient: createWalletClient({ chain: robinhoodTestnet, transport: custom(window.ethereum) }),
  // Addresses are config. Take them from Vaultline's deployment record for the chain:
  // packages/contracts/deployments/<chainId>.json (tokenLock) and
  // <chainId>.burnrouter.json (burnRouter, optional).
  addresses: { tokenLock: "0x...", burnRouter: "0x..." },
  partner: "0xYourWallet", // optional: referral tag on locks, on-chain fee share on burns
  apiBaseUrl: "https://<vaultline app origin>", // optional: needed for commitment checks
});

Usage

// Token info, including the Robinhood stock-token flag and lookalike warning
const t = await vl.token("0xToken");
// { symbol, decimals, stock: { ticker, name, verified } | null, lookalikeWarning, burnAllowed, ... }

// Lock tokens until a date (approves first unless approve: false)
const { lockId, txHash } = await vl.lock({
  token: "0xToken",
  amount: 25_000_000n * 10n ** 18n,
  unlockAt: new Date("2027-10-03"),
});

// Unlock times can only be extended, never shortened
await vl.extendLock({ lockId, unlockAt: new Date("2028-01-01") });

// Burn through BurnRouter (refuses stock tokens before asking the wallet)
const receipt = await vl.burn({ token: "0xToken", amount: 10n ** 24n, memo: "season-2" });

// Server side: verify a burn before granting a perk
await vl.verifyBurn(receipt.burnId, { token: "0xToken", minAmount: 10n ** 24n, memo: "season-2" });

// Commitment checks (Conviction Pass), no wallet needed; uses apiBaseUrl
const ok = await vl.isCommitted("0xWallet", "0xToken", {
  minAmount: 10n ** 24n,
  until: new Date("2027-01-01"),
});
const amount = await vl.committedAmount("0xWallet", "0xToken", { until: new Date("2027-01-01") });

The SDK reads every fee from the chain before sending; none is hardcoded.

Errors

Every error the SDK throws on purpose extends VaultlineError and has a stable code: StockTokenNotSupportedError, NotConfiguredError, WalletRequiredError, InvalidArgumentError, BurnNotFoundError, BurnVerificationError, ApiError and EventNotFoundError. Messages may change between versions; codes won't.

Referral tags

encodeReferralTag, decodeReferralTag, findReferralTags and REFERRAL_SURFACES are exported for reading and writing Vaultline's ERC-8021 attribution suffix yourself.

License

MIT