steward-arc-sdk 0.1.0

package/README.md

@@ -0,0 +1,57 @@
+# steward-sdk
+
+If your agent pays anyone in USDC on Arc, put STEWARD in front of it: one contract call gives you per-payee caps + period limits +
+expiry the agent can't exceed, an on-chain decision log, and an escalation path. Ten lines.
+
+Contracts + docs: https://github.com/big14way/steward (Tameion Agents Hackathon, Canteen × Circle × Arc).
+
+## TypeScript
+
+```bash
+npm i steward-arc-sdk viem
+```
+
+```ts
+import { Steward } from "steward-arc-sdk";
+import { privateKeyToAccount } from "viem/accounts";
+
+const s = new Steward({
+  allowanceManager: "0x…",   // the owner created an allowance for your agent address + the payee
+  auditLog: "0x…",
+  account: privateKeyToAccount(process.env.AGENT_PK as `0x${string}`),
+});
+
+// rules → canonical hash → AuditLog.record() → pay() | escalate()
+const r = await s.decide({
+  allowanceId: 0n, amount: 150_000_000n, memo: "logo v2",
+  inputs: { milestone: "logo v2", evidence: "ipfs://…" }, evidence: true, screenOk: true,
+  reason: "Milestone delivered with evidence; within per-tx and period caps.",   // your LLM's text, never an amount
+});
+console.log(r.action, r.hash, r.payTx ?? r.escalateTx);
+```
+
+What `decide` does: `SCREEN_FAIL` if `screenOk === false` · `HOLD` if `evidence === false` · `ESCALATE` if over the per-tx cap or no room ·
+`PARTIAL` if only part fits (pays that part, escalates the rest under `keccak256("STEWARD/remainder" ‖ hash)`) · else `PAY`.
+Every outcome is `record()`ed on `AuditLog` with the keccak256 of a canonical JSON record you get back (`r.canonical`), so an auditor can replay it.
+A decision hash pays once, even if you retry. Arc's 20 gwei floor is handled.
+
+## Python
+
+```bash
+pip install steward-sdk
+```
+
+```python
+from steward_sdk import Steward
+
+s = Steward(allowance_manager="0x…", audit_log="0x…", agent_private_key=os.environ["AGENT_PK"])
+r = s.decide(allowance_id=0, amount=150_000_000, memo="logo v2",
+             inputs={"milestone": "logo v2", "evidence": "ipfs://…"}, evidence=True, screen_ok=True)
+print(r.action, r.hash, r.pay_tx or r.escalate_tx)
+```
+
+## Owner side
+
+The owner (a Circle Developer-Controlled wallet in the reference app) calls `create(agent, payee, capPerPeriod, perTxCap, period, expiry)`,
+`fund(id, amount)`, `approveAndPay(id, amount, hash)` for escalations, and `revoke(id)` to pull unspent funds and lock the agent out.
+The reference FastAPI service + Telegram bot in the main repo does this with one tap.

package/dist/index.cjs

@@ -0,0 +1,149 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ACTION_CODE: () => ACTION_CODE,
+  AM_ABI: () => AM_ABI,
+  LOG_ABI: () => LOG_ABI,
+  MIN_FEE_PER_GAS: () => MIN_FEE_PER_GAS,
+  REMAINDER_TAG: () => REMAINDER_TAG,
+  Steward: () => Steward,
+  applyRules: () => applyRules,
+  arcTestnet: () => import_chains.arcTestnet,
+  canonical: () => canonical,
+  decisionHash: () => decisionHash,
+  remainderHash: () => remainderHash
+});
+module.exports = __toCommonJS(index_exports);
+var import_viem = require("viem");
+var import_chains = require("viem/chains");
+var AM_ABI = [
+  { type: "function", name: "pay", stateMutability: "nonpayable", inputs: [{ name: "id", type: "uint256" }, { name: "amount", type: "uint128" }, { name: "decisionHash", type: "bytes32" }, { name: "memo", type: "string" }], outputs: [] },
+  { type: "function", name: "escalate", stateMutability: "nonpayable", inputs: [{ name: "id", type: "uint256" }, { name: "amount", type: "uint128" }, { name: "decisionHash", type: "bytes32" }, { name: "reason", type: "string" }], outputs: [] },
+  { type: "function", name: "allowances", stateMutability: "view", inputs: [{ name: "id", type: "uint256" }], outputs: [
+    { name: "owner", type: "address" },
+    { name: "agent", type: "address" },
+    { name: "payee", type: "address" },
+    { name: "capPerPeriod", type: "uint128" },
+    { name: "perTxCap", type: "uint128" },
+    { name: "period", type: "uint64" },
+    { name: "periodStart", type: "uint64" },
+    { name: "expiry", type: "uint64" },
+    { name: "spentThisPeriod", type: "uint128" },
+    { name: "funded", type: "uint128" },
+    { name: "revoked", type: "bool" }
+  ] },
+  { type: "function", name: "usedDecision", stateMutability: "view", inputs: [{ name: "h", type: "bytes32" }], outputs: [{ type: "bool" }] },
+  { type: "function", name: "nextId", stateMutability: "view", inputs: [], outputs: [{ type: "uint256" }] }
+];
+var LOG_ABI = [
+  { type: "function", name: "record", stateMutability: "nonpayable", inputs: [{ name: "allowanceId", type: "uint256" }, { name: "decisionHash", type: "bytes32" }, { name: "action", type: "uint8" }, { name: "amount", type: "uint128" }], outputs: [] }
+];
+var ACTION_CODE = { HOLD: 0, PAY: 1, PARTIAL: 2, ESCALATE: 3, SCREEN_FAIL: 6 };
+var MIN_FEE_PER_GAS = 20000000000n;
+var REMAINDER_TAG = "STEWARD/remainder";
+function canonical(obj) {
+  const sort = (v) => Array.isArray(v) ? v.map(sort) : v && typeof v === "object" ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, sort(v[k])])) : typeof v === "bigint" ? v.toString() : v;
+  return JSON.stringify(sort(obj));
+}
+var decisionHash = (record) => (0, import_viem.keccak256)((0, import_viem.stringToHex)(canonical(record)));
+var remainderHash = (hash) => (0, import_viem.keccak256)(`0x${(0, import_viem.stringToHex)(REMAINDER_TAG).slice(2)}${hash.slice(2)}`);
+function applyRules(a, p) {
+  if (p.screenOk === false) return { action: "SCREEN_FAIL", rule: "R1_screen", pay: 0n, remainder: p.amount };
+  if (p.evidence === false) return { action: "HOLD", rule: "R2_no_evidence", pay: 0n, remainder: 0n };
+  if (p.amount > a.perTxCap) return { action: "ESCALATE", rule: "R3_over_per_tx", pay: 0n, remainder: p.amount };
+  const room = a.capPerPeriod - a.spentThisPeriod;
+  const liquid = a.funded - (p.reserveFloor ?? 0n) - (p.obligations ?? 0n);
+  const allowed = [p.amount, room, liquid].reduce((m, x) => x < m ? x : m);
+  if (allowed <= 0n) return { action: "ESCALATE", rule: "R4_no_room", pay: 0n, remainder: p.amount };
+  if (allowed < p.amount) return { action: "PARTIAL", rule: "R4_partial", pay: allowed, remainder: p.amount - allowed };
+  return { action: "PAY", rule: "R5_pay", pay: p.amount, remainder: 0n };
+}
+var Steward = class {
+  constructor(cfg) {
+    this.cfg = cfg;
+    const chain = cfg.chain ?? import_chains.arcTestnet;
+    const transport = cfg.transport ?? (0, import_viem.http)(cfg.rpc ?? "https://rpc.testnet.arc.io");
+    this.pub = (0, import_viem.createPublicClient)({ chain, transport });
+    this.wallet = (0, import_viem.createWalletClient)({ chain, transport, account: cfg.account });
+  }
+  cfg;
+  pub;
+  wallet;
+  async allowance(id) {
+    const [owner, agent, payee, capPerPeriod, perTxCap, period, periodStart, expiry, spentThisPeriod, funded, revoked] = await this.pub.readContract({ address: this.cfg.allowanceManager, abi: AM_ABI, functionName: "allowances", args: [id] });
+    return { owner, agent, payee, capPerPeriod, perTxCap, period, periodStart, expiry, spentThisPeriod, funded, revoked };
+  }
+  async fees() {
+    const block = await this.pub.getBlock();
+    const base = block.baseFeePerGas ?? 0n;
+    const maxFeePerGas = base + base / 4n > MIN_FEE_PER_GAS ? base + base / 4n : MIN_FEE_PER_GAS;
+    return { maxFeePerGas, maxPriorityFeePerGas: 1000000000n };
+  }
+  async write(address, abi, functionName, args) {
+    const fees = await this.fees();
+    const hash = await this.wallet.writeContract({ address, abi, functionName, args, ...fees });
+    const rcpt = await this.pub.waitForTransactionReceipt({ hash });
+    if (rcpt.status !== "success") throw new Error(`tx reverted ${hash}`);
+    return hash;
+  }
+  /** rules → canonical hash → AuditLog.record() → pay() | escalate(). Every call is recorded, including HOLD. */
+  async decide(p) {
+    const a = await this.allowance(p.allowanceId);
+    const r = applyRules(a, p);
+    const blockNumber = await this.pub.getBlockNumber();
+    const record = {
+      allowanceId: p.allowanceId.toString(),
+      requested: p.amount.toString(),
+      amount: r.pay.toString(),
+      remainder: r.remainder.toString(),
+      action: r.action,
+      rule: r.rule,
+      memo: p.memo,
+      reason: p.reason ?? `${r.rule}: ${r.action} by policy`,
+      inputs: p.inputs,
+      blockNumber: blockNumber.toString()
+    };
+    const hash = decisionHash(record);
+    const recordTx = await this.write(this.cfg.auditLog, LOG_ABI, "record", [p.allowanceId, hash, ACTION_CODE[r.action], r.pay]);
+    let payTx, escalateTx, rHash;
+    if (r.action === "PAY" || r.action === "PARTIAL") payTx = await this.write(this.cfg.allowanceManager, AM_ABI, "pay", [p.allowanceId, r.pay, hash, p.memo]);
+    if (r.remainder > 0n) {
+      rHash = r.action === "PARTIAL" ? remainderHash(hash) : hash;
+      escalateTx = await this.write(this.cfg.allowanceManager, AM_ABI, "escalate", [p.allowanceId, r.remainder, rHash, record.reason.slice(0, 200)]);
+    }
+    return { action: r.action, rule: r.rule, pay: r.pay, remainder: r.remainder, hash, remainderHash: rHash, recordTx, payTx, escalateTx, canonical: canonical(record), record };
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ACTION_CODE,
+  AM_ABI,
+  LOG_ABI,
+  MIN_FEE_PER_GAS,
+  REMAINDER_TAG,
+  Steward,
+  applyRules,
+  arcTestnet,
+  canonical,
+  decisionHash,
+  remainderHash
+});

package/dist/index.d.cts

@@ -0,0 +1,212 @@
+import { Hex, Chain, Account, Transport } from 'viem';
+export { arcTestnet } from 'viem/chains';
+
+declare const AM_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "pay";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "id";
+        readonly type: "uint256";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint128";
+    }, {
+        readonly name: "decisionHash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "memo";
+        readonly type: "string";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "escalate";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "id";
+        readonly type: "uint256";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint128";
+    }, {
+        readonly name: "decisionHash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "reason";
+        readonly type: "string";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "allowances";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "id";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "owner";
+        readonly type: "address";
+    }, {
+        readonly name: "agent";
+        readonly type: "address";
+    }, {
+        readonly name: "payee";
+        readonly type: "address";
+    }, {
+        readonly name: "capPerPeriod";
+        readonly type: "uint128";
+    }, {
+        readonly name: "perTxCap";
+        readonly type: "uint128";
+    }, {
+        readonly name: "period";
+        readonly type: "uint64";
+    }, {
+        readonly name: "periodStart";
+        readonly type: "uint64";
+    }, {
+        readonly name: "expiry";
+        readonly type: "uint64";
+    }, {
+        readonly name: "spentThisPeriod";
+        readonly type: "uint128";
+    }, {
+        readonly name: "funded";
+        readonly type: "uint128";
+    }, {
+        readonly name: "revoked";
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "usedDecision";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "h";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "nextId";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}];
+declare const LOG_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "record";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "allowanceId";
+        readonly type: "uint256";
+    }, {
+        readonly name: "decisionHash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "action";
+        readonly type: "uint8";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint128";
+    }];
+    readonly outputs: readonly [];
+}];
+type Action = "HOLD" | "PAY" | "PARTIAL" | "ESCALATE" | "SCREEN_FAIL";
+declare const ACTION_CODE: Record<Action, number>;
+/** Arc's minimum base fee. Anything lower is dropped silently with no receipt. */
+declare const MIN_FEE_PER_GAS = 20000000000n;
+/** Remainder key for a PARTIAL: pay() consumed the decision hash, approveAndPay() consumes this one. Same tag as the Python agent. */
+declare const REMAINDER_TAG = "STEWARD/remainder";
+type Allowance = {
+    owner: Hex;
+    agent: Hex;
+    payee: Hex;
+    capPerPeriod: bigint;
+    perTxCap: bigint;
+    period: bigint;
+    periodStart: bigint;
+    expiry: bigint;
+    spentThisPeriod: bigint;
+    funded: bigint;
+    revoked: boolean;
+};
+type DecideParams = {
+    allowanceId: bigint;
+    /** requested amount, 6-dp USDC */
+    amount: bigint;
+    /** on-chain memo (≤ 60 chars recommended) */
+    memo: string;
+    /** anything you want hashed into the decision record (milestone id, evidence, model inputs…) */
+    inputs: Record<string, unknown>;
+    /** false → SCREEN_FAIL. Default true. */
+    screenOk?: boolean;
+    /** false → HOLD. Default true. */
+    evidence?: boolean;
+    reserveFloor?: bigint;
+    obligations?: bigint;
+    /** a human-readable reason (your LLM's, or leave empty for a rules-only reason). Never sets amounts. */
+    reason?: string;
+};
+type DecisionRecord = {
+    allowanceId: string;
+    requested: string;
+    amount: string;
+    remainder: string;
+    action: Action;
+    rule: string;
+    memo: string;
+    reason: string;
+    inputs: Record<string, unknown>;
+    blockNumber: string;
+};
+type DecideResult = {
+    action: Action;
+    rule: string;
+    pay: bigint;
+    remainder: bigint;
+    hash: Hex;
+    remainderHash?: Hex;
+    recordTx: Hex;
+    payTx?: Hex;
+    escalateTx?: Hex;
+    canonical: string;
+    record: DecisionRecord;
+};
+/** Sorted-key, whitespace-free JSON (arrays keep order). Same idea as the Python agent's canonical_json. */
+declare function canonical(obj: unknown): string;
+declare const decisionHash: (record: unknown) => Hex;
+declare const remainderHash: (hash: Hex) => Hex;
+/** Deterministic rules. The LLM (if any) only supplies `reason`. */
+declare function applyRules(a: Allowance, p: DecideParams): {
+    action: Action;
+    rule: string;
+    pay: bigint;
+    remainder: bigint;
+};
+declare class Steward {
+    private cfg;
+    private pub;
+    private wallet;
+    constructor(cfg: {
+        rpc?: string;
+        chain?: Chain;
+        allowanceManager: Hex;
+        auditLog: Hex;
+        account: Account;
+        transport?: Transport;
+    });
+    allowance(id: bigint): Promise<Allowance>;
+    private fees;
+    private write;
+    /** rules → canonical hash → AuditLog.record() → pay() | escalate(). Every call is recorded, including HOLD. */
+    decide(p: DecideParams): Promise<DecideResult>;
+}
+
+export { ACTION_CODE, AM_ABI, type Action, type Allowance, type DecideParams, type DecideResult, type DecisionRecord, LOG_ABI, MIN_FEE_PER_GAS, REMAINDER_TAG, Steward, applyRules, canonical, decisionHash, remainderHash };

package/dist/index.d.ts

@@ -0,0 +1,212 @@
+import { Hex, Chain, Account, Transport } from 'viem';
+export { arcTestnet } from 'viem/chains';
+
+declare const AM_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "pay";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "id";
+        readonly type: "uint256";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint128";
+    }, {
+        readonly name: "decisionHash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "memo";
+        readonly type: "string";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "escalate";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "id";
+        readonly type: "uint256";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint128";
+    }, {
+        readonly name: "decisionHash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "reason";
+        readonly type: "string";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "allowances";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "id";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "owner";
+        readonly type: "address";
+    }, {
+        readonly name: "agent";
+        readonly type: "address";
+    }, {
+        readonly name: "payee";
+        readonly type: "address";
+    }, {
+        readonly name: "capPerPeriod";
+        readonly type: "uint128";
+    }, {
+        readonly name: "perTxCap";
+        readonly type: "uint128";
+    }, {
+        readonly name: "period";
+        readonly type: "uint64";
+    }, {
+        readonly name: "periodStart";
+        readonly type: "uint64";
+    }, {
+        readonly name: "expiry";
+        readonly type: "uint64";
+    }, {
+        readonly name: "spentThisPeriod";
+        readonly type: "uint128";
+    }, {
+        readonly name: "funded";
+        readonly type: "uint128";
+    }, {
+        readonly name: "revoked";
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "usedDecision";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "h";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "nextId";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}];
+declare const LOG_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "record";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "allowanceId";
+        readonly type: "uint256";
+    }, {
+        readonly name: "decisionHash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "action";
+        readonly type: "uint8";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint128";
+    }];
+    readonly outputs: readonly [];
+}];
+type Action = "HOLD" | "PAY" | "PARTIAL" | "ESCALATE" | "SCREEN_FAIL";
+declare const ACTION_CODE: Record<Action, number>;
+/** Arc's minimum base fee. Anything lower is dropped silently with no receipt. */
+declare const MIN_FEE_PER_GAS = 20000000000n;
+/** Remainder key for a PARTIAL: pay() consumed the decision hash, approveAndPay() consumes this one. Same tag as the Python agent. */
+declare const REMAINDER_TAG = "STEWARD/remainder";
+type Allowance = {
+    owner: Hex;
+    agent: Hex;
+    payee: Hex;
+    capPerPeriod: bigint;
+    perTxCap: bigint;
+    period: bigint;
+    periodStart: bigint;
+    expiry: bigint;
+    spentThisPeriod: bigint;
+    funded: bigint;
+    revoked: boolean;
+};
+type DecideParams = {
+    allowanceId: bigint;
+    /** requested amount, 6-dp USDC */
+    amount: bigint;
+    /** on-chain memo (≤ 60 chars recommended) */
+    memo: string;
+    /** anything you want hashed into the decision record (milestone id, evidence, model inputs…) */
+    inputs: Record<string, unknown>;
+    /** false → SCREEN_FAIL. Default true. */
+    screenOk?: boolean;
+    /** false → HOLD. Default true. */
+    evidence?: boolean;
+    reserveFloor?: bigint;
+    obligations?: bigint;
+    /** a human-readable reason (your LLM's, or leave empty for a rules-only reason). Never sets amounts. */
+    reason?: string;
+};
+type DecisionRecord = {
+    allowanceId: string;
+    requested: string;
+    amount: string;
+    remainder: string;
+    action: Action;
+    rule: string;
+    memo: string;
+    reason: string;
+    inputs: Record<string, unknown>;
+    blockNumber: string;
+};
+type DecideResult = {
+    action: Action;
+    rule: string;
+    pay: bigint;
+    remainder: bigint;
+    hash: Hex;
+    remainderHash?: Hex;
+    recordTx: Hex;
+    payTx?: Hex;
+    escalateTx?: Hex;
+    canonical: string;
+    record: DecisionRecord;
+};
+/** Sorted-key, whitespace-free JSON (arrays keep order). Same idea as the Python agent's canonical_json. */
+declare function canonical(obj: unknown): string;
+declare const decisionHash: (record: unknown) => Hex;
+declare const remainderHash: (hash: Hex) => Hex;
+/** Deterministic rules. The LLM (if any) only supplies `reason`. */
+declare function applyRules(a: Allowance, p: DecideParams): {
+    action: Action;
+    rule: string;
+    pay: bigint;
+    remainder: bigint;
+};
+declare class Steward {
+    private cfg;
+    private pub;
+    private wallet;
+    constructor(cfg: {
+        rpc?: string;
+        chain?: Chain;
+        allowanceManager: Hex;
+        auditLog: Hex;
+        account: Account;
+        transport?: Transport;
+    });
+    allowance(id: bigint): Promise<Allowance>;
+    private fees;
+    private write;
+    /** rules → canonical hash → AuditLog.record() → pay() | escalate(). Every call is recorded, including HOLD. */
+    decide(p: DecideParams): Promise<DecideResult>;
+}
+
+export { ACTION_CODE, AM_ABI, type Action, type Allowance, type DecideParams, type DecideResult, type DecisionRecord, LOG_ABI, MIN_FEE_PER_GAS, REMAINDER_TAG, Steward, applyRules, canonical, decisionHash, remainderHash };

package/dist/index.js

@@ -0,0 +1,120 @@
+// src/index.ts
+import {
+  createPublicClient,
+  createWalletClient,
+  http,
+  keccak256,
+  stringToHex
+} from "viem";
+import { arcTestnet } from "viem/chains";
+var AM_ABI = [
+  { type: "function", name: "pay", stateMutability: "nonpayable", inputs: [{ name: "id", type: "uint256" }, { name: "amount", type: "uint128" }, { name: "decisionHash", type: "bytes32" }, { name: "memo", type: "string" }], outputs: [] },
+  { type: "function", name: "escalate", stateMutability: "nonpayable", inputs: [{ name: "id", type: "uint256" }, { name: "amount", type: "uint128" }, { name: "decisionHash", type: "bytes32" }, { name: "reason", type: "string" }], outputs: [] },
+  { type: "function", name: "allowances", stateMutability: "view", inputs: [{ name: "id", type: "uint256" }], outputs: [
+    { name: "owner", type: "address" },
+    { name: "agent", type: "address" },
+    { name: "payee", type: "address" },
+    { name: "capPerPeriod", type: "uint128" },
+    { name: "perTxCap", type: "uint128" },
+    { name: "period", type: "uint64" },
+    { name: "periodStart", type: "uint64" },
+    { name: "expiry", type: "uint64" },
+    { name: "spentThisPeriod", type: "uint128" },
+    { name: "funded", type: "uint128" },
+    { name: "revoked", type: "bool" }
+  ] },
+  { type: "function", name: "usedDecision", stateMutability: "view", inputs: [{ name: "h", type: "bytes32" }], outputs: [{ type: "bool" }] },
+  { type: "function", name: "nextId", stateMutability: "view", inputs: [], outputs: [{ type: "uint256" }] }
+];
+var LOG_ABI = [
+  { type: "function", name: "record", stateMutability: "nonpayable", inputs: [{ name: "allowanceId", type: "uint256" }, { name: "decisionHash", type: "bytes32" }, { name: "action", type: "uint8" }, { name: "amount", type: "uint128" }], outputs: [] }
+];
+var ACTION_CODE = { HOLD: 0, PAY: 1, PARTIAL: 2, ESCALATE: 3, SCREEN_FAIL: 6 };
+var MIN_FEE_PER_GAS = 20000000000n;
+var REMAINDER_TAG = "STEWARD/remainder";
+function canonical(obj) {
+  const sort = (v) => Array.isArray(v) ? v.map(sort) : v && typeof v === "object" ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, sort(v[k])])) : typeof v === "bigint" ? v.toString() : v;
+  return JSON.stringify(sort(obj));
+}
+var decisionHash = (record) => keccak256(stringToHex(canonical(record)));
+var remainderHash = (hash) => keccak256(`0x${stringToHex(REMAINDER_TAG).slice(2)}${hash.slice(2)}`);
+function applyRules(a, p) {
+  if (p.screenOk === false) return { action: "SCREEN_FAIL", rule: "R1_screen", pay: 0n, remainder: p.amount };
+  if (p.evidence === false) return { action: "HOLD", rule: "R2_no_evidence", pay: 0n, remainder: 0n };
+  if (p.amount > a.perTxCap) return { action: "ESCALATE", rule: "R3_over_per_tx", pay: 0n, remainder: p.amount };
+  const room = a.capPerPeriod - a.spentThisPeriod;
+  const liquid = a.funded - (p.reserveFloor ?? 0n) - (p.obligations ?? 0n);
+  const allowed = [p.amount, room, liquid].reduce((m, x) => x < m ? x : m);
+  if (allowed <= 0n) return { action: "ESCALATE", rule: "R4_no_room", pay: 0n, remainder: p.amount };
+  if (allowed < p.amount) return { action: "PARTIAL", rule: "R4_partial", pay: allowed, remainder: p.amount - allowed };
+  return { action: "PAY", rule: "R5_pay", pay: p.amount, remainder: 0n };
+}
+var Steward = class {
+  constructor(cfg) {
+    this.cfg = cfg;
+    const chain = cfg.chain ?? arcTestnet;
+    const transport = cfg.transport ?? http(cfg.rpc ?? "https://rpc.testnet.arc.io");
+    this.pub = createPublicClient({ chain, transport });
+    this.wallet = createWalletClient({ chain, transport, account: cfg.account });
+  }
+  cfg;
+  pub;
+  wallet;
+  async allowance(id) {
+    const [owner, agent, payee, capPerPeriod, perTxCap, period, periodStart, expiry, spentThisPeriod, funded, revoked] = await this.pub.readContract({ address: this.cfg.allowanceManager, abi: AM_ABI, functionName: "allowances", args: [id] });
+    return { owner, agent, payee, capPerPeriod, perTxCap, period, periodStart, expiry, spentThisPeriod, funded, revoked };
+  }
+  async fees() {
+    const block = await this.pub.getBlock();
+    const base = block.baseFeePerGas ?? 0n;
+    const maxFeePerGas = base + base / 4n > MIN_FEE_PER_GAS ? base + base / 4n : MIN_FEE_PER_GAS;
+    return { maxFeePerGas, maxPriorityFeePerGas: 1000000000n };
+  }
+  async write(address, abi, functionName, args) {
+    const fees = await this.fees();
+    const hash = await this.wallet.writeContract({ address, abi, functionName, args, ...fees });
+    const rcpt = await this.pub.waitForTransactionReceipt({ hash });
+    if (rcpt.status !== "success") throw new Error(`tx reverted ${hash}`);
+    return hash;
+  }
+  /** rules → canonical hash → AuditLog.record() → pay() | escalate(). Every call is recorded, including HOLD. */
+  async decide(p) {
+    const a = await this.allowance(p.allowanceId);
+    const r = applyRules(a, p);
+    const blockNumber = await this.pub.getBlockNumber();
+    const record = {
+      allowanceId: p.allowanceId.toString(),
+      requested: p.amount.toString(),
+      amount: r.pay.toString(),
+      remainder: r.remainder.toString(),
+      action: r.action,
+      rule: r.rule,
+      memo: p.memo,
+      reason: p.reason ?? `${r.rule}: ${r.action} by policy`,
+      inputs: p.inputs,
+      blockNumber: blockNumber.toString()
+    };
+    const hash = decisionHash(record);
+    const recordTx = await this.write(this.cfg.auditLog, LOG_ABI, "record", [p.allowanceId, hash, ACTION_CODE[r.action], r.pay]);
+    let payTx, escalateTx, rHash;
+    if (r.action === "PAY" || r.action === "PARTIAL") payTx = await this.write(this.cfg.allowanceManager, AM_ABI, "pay", [p.allowanceId, r.pay, hash, p.memo]);
+    if (r.remainder > 0n) {
+      rHash = r.action === "PARTIAL" ? remainderHash(hash) : hash;
+      escalateTx = await this.write(this.cfg.allowanceManager, AM_ABI, "escalate", [p.allowanceId, r.remainder, rHash, record.reason.slice(0, 200)]);
+    }
+    return { action: r.action, rule: r.rule, pay: r.pay, remainder: r.remainder, hash, remainderHash: rHash, recordTx, payTx, escalateTx, canonical: canonical(record), record };
+  }
+};
+export {
+  ACTION_CODE,
+  AM_ABI,
+  LOG_ABI,
+  MIN_FEE_PER_GAS,
+  REMAINDER_TAG,
+  Steward,
+  applyRules,
+  arcTestnet,
+  canonical,
+  decisionHash,
+  remainderHash
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "steward-arc-sdk",
+  "version": "0.1.0",
+  "description": "Per-payee on-chain allowances, a replayable decision log and human escalation for AI agents that pay people in USDC on Arc.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/big14way/steward.git",
+    "directory": "packages/steward-sdk"
+  },
+  "homepage": "https://github.com/big14way/steward/tree/main/packages/steward-sdk",
+  "keywords": [
+    "arc",
+    "circle",
+    "usdc",
+    "agent",
+    "allowance",
+    "tameion",
+    "viem"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "test": "node --test test/*.test.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "viem": ">=2"
+  },
+  "devDependencies": {
+    "tsup": "^8",
+    "typescript": "^5",
+    "viem": "^2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}