@buildaureon/sdk 0.1.0

package/examples/e2e-policy-rebalance/verify-sizing.ts

@@ -0,0 +1,147 @@
+/**
+ * Verify underweight Auto sizing lands near 20% (not 98%).
+ */
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  createPublicClient,
+  createWalletClient,
+  http,
+  type Address,
+  type Hex,
+} from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import {
+  createAureonClient,
+  createSessionTokenProvider,
+  LOCAL_API_BASE_URL,
+} from "../../src/index.js";
+
+const BACKEND = join(dirname(fileURLToPath(import.meta.url)), "../../../backend");
+const env = Object.fromEntries(
+  readFileSync(join(BACKEND, ".env"), "utf8")
+    .split(/\r?\n/)
+    .filter((l) => l && !l.startsWith("#") && l.includes("="))
+    .map((l) => {
+      const i = l.indexOf("=");
+      return [l.slice(0, i), l.slice(i + 1).trim()] as const;
+    })
+);
+const key = JSON.parse(
+  readFileSync(join(BACKEND, ".secrets/robinhood-testnet-wallet.json"), "utf8")
+).privateKey as Hex;
+const account = privateKeyToAccount(key);
+const rpc = env.AUREON_RPC_URL!;
+const chainId = Number(env.AUREON_CHAIN_ID || 46630);
+const publicClient = createPublicClient({ transport: http(rpc) });
+const walletClient = createWalletClient({ account, transport: http(rpc) });
+const chain = {
+  id: chainId,
+  name: "rh",
+  nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+  rpcUrls: { default: { http: [rpc] } },
+} as const;
+
+const session = createSessionTokenProvider(null);
+const aureon = createAureonClient({
+  baseUrl: LOCAL_API_BASE_URL,
+  apiKey: env.AUREON_API_KEYS!.split(",")[0]!.trim(),
+  getAccessToken: session.getAccessToken,
+});
+
+const { message } = await aureon.getAuthNonce(account.address);
+session.setToken(
+  (
+    await aureon.verifyWallet({
+      address: account.address,
+      message,
+      signature: await walletClient.signMessage({ account, message }),
+    })
+  ).token
+);
+
+// Fresh Auto objective
+const objective = await aureon.createObjective({
+  name: `SizeFix 20% TSLA ${Date.now()}`,
+  kind: "balanced_portfolio",
+  targetWeight: 0.2,
+  tolerance: 0.05,
+  targetSymbol: "TSLA",
+  priority: "high",
+  automationMode: "auto",
+});
+console.log("objective", objective.id);
+
+// Dump almost all TSLA so we're heavily underweight, keep/add WETH
+const vault = await aureon.getVault();
+console.log(
+  "before",
+  vault.balances.filter((b) => b.quantity > 0).map((b) => `${b.symbol}:${b.quantity}`)
+);
+const tsla = vault.balances.find((b) => b.symbol.toUpperCase() === "TSLA");
+if (tsla && tsla.quantity > 0.0001) {
+  const amt = Math.max(tsla.quantity - 0.00001, 0).toFixed(8);
+  const prep = await aureon.prepareVaultWithdraw({ symbol: "TSLA", amount: amt });
+  for (const step of prep.steps) {
+    const hash = await walletClient.sendTransaction({
+      account,
+      chain,
+      to: step.to as Address,
+      data: step.data as Hex,
+      value: 0n,
+    });
+    await publicClient.waitForTransactionReceipt({ hash });
+    console.log("withdrew TSLA", hash);
+  }
+}
+
+const dep = await aureon.prepareVaultDeposit({ symbol: "ETH", amount: "0.0004" });
+for (const step of dep.steps) {
+  const hash = await walletClient.sendTransaction({
+    account,
+    chain,
+    to: step.to as Address,
+    data: step.data as Hex,
+    value: BigInt(step.value),
+  });
+  await publicClient.waitForTransactionReceipt({ hash });
+  console.log("depositETH", hash);
+}
+
+await aureon.refreshWatchdog();
+const h1 = (await aureon.getHealth(objective.id))[0]!;
+console.log("health underweight", {
+  state: h1.state,
+  current: h1.currentMetric,
+  message: h1.message,
+});
+
+const plan = await aureon.getRestorePlan(objective.id);
+console.log("plan", {
+  message: plan.message,
+  amountHuman: plan.amountHuman,
+  approxUsd: plan.approxUsd,
+  sell: (plan as { sellSymbol?: string }).sellSymbol,
+  buy: (plan as { buySymbol?: string }).buySymbol,
+});
+
+const receipt = await aureon.restoreObjective(objective.id);
+console.log("exec", receipt.status, receipt.transactionHash);
+
+await aureon.refreshWatchdog();
+const h2 = (await aureon.getHealth(objective.id))[0]!;
+console.log("health after", {
+  state: h2.state,
+  current: h2.currentMetric,
+  message: h2.message,
+});
+
+const weightPct = (h2.currentMetric ?? 0) * 100;
+const ok = weightPct >= 5 && weightPct <= 45; // near 20% with band (was ~98% before)
+console.log(
+  ok
+    ? `PASS sizing : TSLA weight ~${weightPct.toFixed(1)}% (want ~20%)`
+    : `FAIL sizing : TSLA weight ~${weightPct.toFixed(1)}% still overshot`
+);
+if (!ok) process.exitCode = 1;

package/examples/e2e-vault-flow/main.ts

@@ -0,0 +1,270 @@
+/**
+ * @fileoverview Live SDK e2e against local AUREON API + Robinhood testnet vault.
+ *
+ * Exercises: wallet auth → sync → vault prepare deposit/withdraw (signed) →
+ * createObjective (Automatic) → restore plan.
+ *
+ * Env (loaded from backend/.env + .secrets automatically when unset):
+ *   AUREON_API_URL   default http://127.0.0.1:8787
+ *   AUREON_API_KEY   from backend/.env AUREON_API_KEYS (first key)
+ *   AUREON_E2E_KEY   hex private key (defaults to vault-deployer.key)
+ *
+ *   pnpm --filter @buildaureon/sdk exec tsx examples/e2e-vault-flow/main.ts
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  createPublicClient,
+  createWalletClient,
+  http,
+  type Hex,
+} from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import {
+  createAureonClient,
+  createSessionTokenProvider,
+  isAureonError,
+  LOCAL_API_BASE_URL,
+} from "../../src/index.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, "../../..");
+const BACKEND = join(ROOT, "backend");
+
+function loadDotEnv(path: string): Record<string, string> {
+  if (!existsSync(path)) return {};
+  const out: Record<string, string> = {};
+  for (const line of readFileSync(path, "utf8").split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const i = trimmed.indexOf("=");
+    if (i < 0) continue;
+    out[trimmed.slice(0, i)] = trimmed.slice(i + 1).trim();
+  }
+  return out;
+}
+
+function firstApiKey(raw: string | undefined): string | null {
+  if (!raw) return null;
+  const key = raw.split(",")[0]?.trim();
+  return key || null;
+}
+
+function loadPrivateKey(): Hex {
+  if (process.env.AUREON_E2E_KEY?.startsWith("0x")) {
+    return process.env.AUREON_E2E_KEY as Hex;
+  }
+  const fromEnv = loadDotEnv(join(BACKEND, ".env")).AUREON_VAULT_DEPLOYER_KEY;
+  if (fromEnv?.startsWith("0x")) return fromEnv as Hex;
+  const keyPath = join(BACKEND, ".secrets/vault-deployer.key");
+  if (!existsSync(keyPath)) {
+    throw new Error("Missing AUREON_E2E_KEY / vault-deployer.key");
+  }
+  const hex = readFileSync(keyPath, "utf8").trim();
+  if (!/^0x[0-9a-fA-F]{64}$/.test(hex)) {
+    throw new Error("vault-deployer.key must be a 32-byte hex private key");
+  }
+  return hex as Hex;
+}
+
+function log(step: string, data?: unknown): void {
+  if (data === undefined) {
+    console.log(`✓ ${step}`);
+    return;
+  }
+  console.log(`✓ ${step}`, data);
+}
+
+async function main(): Promise<void> {
+  const env = loadDotEnv(join(BACKEND, ".env"));
+  const baseUrl =
+    process.env.AUREON_API_URL ?? env.AUREON_API_URL ?? LOCAL_API_BASE_URL;
+  const apiKey =
+    process.env.AUREON_API_KEY ?? firstApiKey(env.AUREON_API_KEYS);
+  const rpcUrl = env.AUREON_RPC_URL ?? "https://rpc.testnet.chain.robinhood.com";
+  const chainId = Number(env.AUREON_CHAIN_ID ?? 46630);
+
+  if (!apiKey) throw new Error("AUREON_API_KEY / AUREON_API_KEYS missing");
+
+  const account = privateKeyToAccount(loadPrivateKey());
+  const publicClient = createPublicClient({ transport: http(rpcUrl) });
+  const walletClient = createWalletClient({
+    account,
+    transport: http(rpcUrl),
+  });
+
+  const session = createSessionTokenProvider(null);
+  const aureon = createAureonClient({
+    baseUrl,
+    apiKey,
+    getAccessToken: session.getAccessToken,
+  });
+
+  const ping = await aureon.ping();
+  log("ping", ping);
+
+  const { message } = await aureon.getAuthNonce(account.address);
+  const signature = await walletClient.signMessage({
+    account,
+    message,
+  });
+  const login = await aureon.verifyWallet({
+    address: account.address,
+    message,
+    signature,
+  });
+  session.setToken(login.token);
+  log("auth", { wallet: login.walletAddress });
+
+  const me = await aureon.me();
+  if (me.walletAddress.toLowerCase() !== account.address.toLowerCase()) {
+    throw new Error("session wallet mismatch");
+  }
+
+  const synced = await aureon.syncPortfolio();
+  log("syncPortfolio", {
+    chainId: synced.chainId,
+    positions: synced.portfolio.positions.length,
+    totalNotionalUsd: synced.portfolio.totalNotionalUsd,
+  });
+
+  const vaultBefore = await aureon.getVault();
+  const statusBefore = await aureon.getVaultStatus();
+  const wethBefore =
+    vaultBefore.balances.find((b) => b.symbol.toUpperCase() === "WETH")
+      ?.quantity ?? 0;
+  log("vault before", {
+    address: vaultBefore.address,
+    empty: statusBefore.empty,
+    weth: wethBefore,
+    canRestore: statusBefore.canRestore,
+  });
+
+  const depositAmount = "0.0001";
+  const ethBal = await publicClient.getBalance({ address: account.address });
+  if (ethBal < 200000000000000n) {
+    throw new Error(
+      `Wallet ${account.address} needs ≥0.0002 ETH for deposit+gas (have ${ethBal})`
+    );
+  }
+
+  const deposit = await aureon.prepareVaultDeposit({
+    symbol: "ETH",
+    amount: depositAmount,
+  });
+  log("prepareVaultDeposit", {
+    steps: deposit.steps.map((s) => s.functionName),
+    amountHuman: deposit.amountHuman,
+  });
+
+  for (const step of deposit.steps) {
+    const hash = await walletClient.sendTransaction({
+      account,
+      chain: {
+        id: chainId,
+        name: "Robinhood Chain Testnet",
+        nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+        rpcUrls: { default: { http: [rpcUrl] } },
+      },
+      to: step.to as `0x${string}`,
+      data: step.data as Hex,
+      value: BigInt(step.value),
+    });
+    await publicClient.waitForTransactionReceipt({ hash });
+    log(`deposit tx ${step.functionName}`, { hash });
+  }
+
+  const vaultAfterDeposit = await aureon.getVault();
+  const wethAfterDeposit =
+    vaultAfterDeposit.balances.find((b) => b.symbol.toUpperCase() === "WETH")
+      ?.quantity ?? 0;
+  log("vault after deposit", { weth: wethAfterDeposit });
+  if (!(wethAfterDeposit > wethBefore)) {
+    throw new Error("expected vault WETH to increase after depositETH");
+  }
+
+  const withdrawAmount = "0.00005";
+  const withdraw = await aureon.prepareVaultWithdraw({
+    amount: withdrawAmount,
+  });
+  for (const step of withdraw.steps) {
+    const hash = await walletClient.sendTransaction({
+      account,
+      chain: {
+        id: chainId,
+        name: "Robinhood Chain Testnet",
+        nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+        rpcUrls: { default: { http: [rpcUrl] } },
+      },
+      to: step.to as `0x${string}`,
+      data: step.data as Hex,
+      value: BigInt(step.value),
+    });
+    await publicClient.waitForTransactionReceipt({ hash });
+    log(`withdraw tx ${step.functionName}`, { hash });
+  }
+
+  const vaultAfterWithdraw = await aureon.getVault();
+  const wethAfterWithdraw =
+    vaultAfterWithdraw.balances.find((b) => b.symbol.toUpperCase() === "WETH")
+      ?.quantity ?? 0;
+  log("vault after withdraw", { weth: wethAfterWithdraw });
+  if (!(wethAfterWithdraw < wethAfterDeposit)) {
+    throw new Error("expected vault WETH to decrease after withdraw");
+  }
+
+  await aureon.syncPortfolio();
+
+  const objective = await aureon.createObjective({
+    name: `SDK E2E Auto ${Date.now()}`,
+    kind: "balanced_portfolio",
+    targetWeight: 0.2,
+    tolerance: 0.05,
+    targetSymbol: "WETH",
+    priority: "high",
+  });
+  log("createObjective", {
+    id: objective.id,
+    automationMode: objective.automationMode,
+    summary: objective.policy.summary,
+  });
+  if (objective.automationMode !== "auto") {
+    throw new Error(
+      `SDK create must default to auto, got ${objective.automationMode}`
+    );
+  }
+
+  const health = await aureon.getHealth(objective.id);
+  log("health", health[0] ? { state: health[0].state, message: health[0].message } : null);
+
+  try {
+    const plan = await aureon.getRestorePlan(objective.id);
+    log("getRestorePlan", {
+      kind: plan.kind,
+      amountHuman: plan.amountHuman,
+      message: plan.message,
+    });
+  } catch (err) {
+    if (isAureonError(err)) {
+      log("getRestorePlan (expected if already in band)", {
+        code: err.code,
+        message: err.message,
+      });
+    } else {
+      throw err;
+    }
+  }
+
+  console.log("\nE2E OK : vault up/down + Automatic objective via SDK");
+}
+
+main().catch((error) => {
+  if (isAureonError(error)) {
+    console.error(`${error.code}: ${error.message}`);
+  } else {
+    console.error(error instanceof Error ? error.message : error);
+  }
+  process.exitCode = 1;
+});

package/examples/market-event/main.ts

@@ -0,0 +1,65 @@
+/**
+ * @fileoverview Controlled market event example (simulation helper).
+ *
+ * Env: AUREON_API_KEY, AUREON_TOKEN, optional AUREON_API_URL
+ *
+ *   pnpm --filter @buildaureon/sdk example:market
+ */
+
+import {
+  createAureonClient,
+  createSessionTokenProvider,
+  DEFAULT_API_BASE_URL,
+  isAureonError,
+} from "../../src/index.js";
+
+async function main(): Promise<void> {
+  const session = createSessionTokenProvider(process.env.AUREON_TOKEN ?? null);
+  if (!session.getAccessToken()) {
+    throw new Error("Set AUREON_TOKEN from a wallet verify session.");
+  }
+
+  const aureon = createAureonClient({
+    baseUrl: process.env.AUREON_API_URL ?? DEFAULT_API_BASE_URL,
+    apiKey: process.env.AUREON_API_KEY ?? null,
+    getAccessToken: session.getAccessToken,
+  });
+
+  const objective = await aureon.createObjective({
+    name: "Maintain 20% Stable Assets",
+    kind: "stable_allocation",
+    targetWeight: 0.2,
+    tolerance: 0.02,
+  });
+
+  const result = await aureon.applyMarketEvent({
+    name: "NVDA Stock Token Rally",
+    description: "Controlled mark appreciation on NVIDIA Stock Token",
+    symbol: "NVDA",
+    priceChangeRatio: 0.45,
+    autoRestore: true,
+  });
+
+  console.log(
+    JSON.stringify(
+      {
+        objectiveId: objective.id,
+        eventId: result.event.id,
+        executions: result.executions.length,
+        settlement: result.executions[0]?.settlement ?? null,
+        health: result.health.find((h) => h.objectiveId === objective.id)?.state,
+      },
+      null,
+      2
+    )
+  );
+}
+
+main().catch((error) => {
+  if (isAureonError(error)) {
+    console.error(`${error.code}: ${error.message}`);
+  } else {
+    console.error(error);
+  }
+  process.exitCode = 1;
+});

package/examples/quickstart/main.ts

@@ -0,0 +1,71 @@
+/**
+ * @fileoverview Quickstart example for @buildaureon/sdk against the AUREON API.
+ *
+ * Env:
+ *   AUREON_API_KEY  : product key (required on hosted API)
+ *   AUREON_TOKEN    : wallet Bearer session
+ *   AUREON_API_URL  : optional override (defaults to https://api.aureonlabs.network)
+ *
+ *   pnpm --filter @buildaureon/sdk example:quickstart
+ */
+
+import {
+  createAureonClient,
+  createSessionTokenProvider,
+  DEFAULT_API_BASE_URL,
+  formatWeight,
+  isAureonError,
+} from "../../src/index.js";
+
+async function main(): Promise<void> {
+  const session = createSessionTokenProvider(process.env.AUREON_TOKEN ?? null);
+  const aureon = createAureonClient({
+    baseUrl: process.env.AUREON_API_URL ?? DEFAULT_API_BASE_URL,
+    apiKey: process.env.AUREON_API_KEY ?? null,
+    getAccessToken: session.getAccessToken,
+  });
+
+  const ping = await aureon.ping();
+  console.log("connected", ping);
+
+  if (!session.getAccessToken()) {
+    throw new Error(
+      "Set AUREON_TOKEN from a wallet verify session (nonce → sign → verifyWallet)."
+    );
+  }
+
+  const me = await aureon.me();
+  console.log("wallet", me.walletAddress);
+
+  const synced = await aureon.syncPortfolio();
+  console.log("synced", {
+    chainId: synced.chainId,
+    positions: synced.portfolio.positions.length,
+    stableWeight: formatWeight(synced.portfolio.stableWeight),
+  });
+
+  const vault = await aureon.getVaultStatus();
+  console.log("vault", {
+    empty: vault.empty,
+    canRestore: vault.canRestore,
+    totalNotionalUsd: vault.totalNotionalUsd,
+  });
+
+  const objectives = await aureon.listObjectives();
+  console.log(
+    "objectives",
+    objectives.map((o) => ({
+      name: o.name,
+      automationMode: o.automationMode,
+    }))
+  );
+}
+
+main().catch((error) => {
+  if (isAureonError(error)) {
+    console.error(`${error.code}: ${error.message}`);
+  } else {
+    console.error(error instanceof Error ? error.message : error);
+  }
+  process.exitCode = 1;
+});

package/fixtures/reference-objectives.json

@@ -0,0 +1,18 @@
+{
+  "objectives": [
+    {
+      "name": "Maintain 20% Stable Assets",
+      "kind": "stable_allocation",
+      "targetWeight": 0.2,
+      "tolerance": 0.02,
+      "priority": "high"
+    },
+    {
+      "name": "Balanced Stock Token Sleeve",
+      "kind": "balanced_portfolio",
+      "targetWeight": 0.55,
+      "tolerance": 0.05,
+      "priority": "medium"
+    }
+  ]
+}

package/fixtures/reference-portfolio.json

@@ -0,0 +1,10 @@
+{
+  "portfolioId": "portfolio_operator_primary",
+  "positions": [
+    { "symbol": "USDG", "category": "stable", "quantity": 24000, "markPriceUsd": 1 },
+    { "symbol": "NVDA", "category": "stock_token", "quantity": 45, "markPriceUsd": 920 },
+    { "symbol": "AAPL", "category": "stock_token", "quantity": 80, "markPriceUsd": 210 },
+    { "symbol": "GOOGL", "category": "stock_token", "quantity": 60, "markPriceUsd": 175 },
+    { "symbol": "ETH", "category": "gas", "quantity": 8.5, "markPriceUsd": 3400 }
+  ]
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@buildaureon/sdk",
+  "version": "0.1.0",
+  "description": "Official TypeScript SDK for AUREON Financial Compass on Robinhood Chain",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "docs",
+    "examples",
+    "config",
+    "fixtures"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsx --test tests/**/*.test.ts",
+    "bench": "tsx benchmarks/client-throughput.ts",
+    "example:quickstart": "tsx examples/quickstart/main.ts",
+    "example:market": "tsx examples/market-event/main.ts",
+    "example:e2e": "tsx examples/e2e-vault-flow/main.ts",
+    "example:e2e-policy": "tsx examples/e2e-policy-rebalance/main.ts",
+    "cli": "tsx cli/aureon-cli.ts",
+    "prepublishOnly": "pnpm build"
+  },
+  "keywords": [
+    "aureon",
+    "robinhood-chain",
+    "fco",
+    "financial-compass",
+    "sdk",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/buildaureon/aureon-sdk"
+  },
+  "license": "MIT",
+  "author": "AUREON Labs (https://github.com/buildaureon)",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "tsup": "^8.5.1",
+    "tsx": "^4.23.1",
+    "typescript": "^5.9.3",
+    "viem": "^2.55.1"
+  }
+}