steward-arc-sdk 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Godswill Idolor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -5,6 +5,39 @@ expiry the agent can't exceed, an on-chain decision log, and an escalation path.
 
 Contracts + docs: https://github.com/big14way/steward (Tameion Agents Hackathon, Canteen × Circle × Arc).
 
+## Step 0: create a budget for your agent (the owner does this once)
+
+The owner wallet creates an allowance on the deployed `AllowanceManager` (Arc Testnet) and funds it with USDC. Your agent can then pay
+that one payee, within those limits, and nothing else.
+
+```ts
+import { createPublicClient, createWalletClient, http, parseAbi } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { arcTestnet } from "steward-arc-sdk";
+
+const AM = "0x3AAfC635a1D1391c9FD8b5B9d8A518Fe980cb7E6";    // AllowanceManager on Arc Testnet
+const USDC = "0x3600000000000000000000000000000000000000";  // USDC on Arc (6 decimals)
+const abi = parseAbi([
+  "function nextId() view returns (uint256)",
+  "function create(address agent, address payee, uint128 capPerPeriod, uint128 perTxCap, uint64 period, uint64 expiry) returns (uint256)",
+  "function fund(uint256 id, uint128 amount)",
+  "function approve(address spender, uint256 amount) returns (bool)",
+]);
+const pub = createPublicClient({ chain: arcTestnet, transport: http() });
+const owner = createWalletClient({ account: privateKeyToAccount(process.env.OWNER_PK as `0x${string}`), chain: arcTestnet, transport: http() });
+const gas = { maxFeePerGas: 25_000_000_000n, maxPriorityFeePerGas: 1_000_000_000n };  // Arc's floor is 20 gwei
+
+const id = await pub.readContract({ address: AM, abi, functionName: "nextId" });
+// 50 USDC per payment, 200 USDC per week, no expiry
+await pub.waitForTransactionReceipt({ hash: await owner.writeContract({ address: AM, abi, functionName: "create",
+  args: [AGENT_ADDRESS, PAYEE_ADDRESS, 200_000_000n, 50_000_000n, 604_800n, 0n], ...gas }) });
+await pub.waitForTransactionReceipt({ hash: await owner.writeContract({ address: USDC, abi, functionName: "approve", args: [AM, 200_000_000n], ...gas }) });
+await pub.waitForTransactionReceipt({ hash: await owner.writeContract({ address: AM, abi, functionName: "fund", args: [id, 200_000_000n], ...gas }) });
+console.log("allowanceId", id);   // pass this to steward.decide()
+```
+
+Prefer a UI? The hosted app does the same from *Contractors → Add contractor*.
+
 ## TypeScript
 
 ```bash
@@ -50,6 +83,40 @@ r = s.decide(allowance_id=0, amount=150_000_000, memo="logo v2",
 print(r.action, r.hash, r.pay_tx or r.escalate_tx)
 ```
 
+## Agent on a Circle wallet (no raw key)
+
+Most Arc agents sign with a Circle Developer-Controlled wallet. Pass the Circle client you already have instead of `account`;
+STEWARD sends `record`, `pay` and `escalate` through Circle's contract-execution API and waits for the on-chain hash.
+The allowance's `agent` must be that wallet's address. Same rules, same hashes.
+
+```ts
+import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";
+import { Steward } from "steward-arc-sdk";
+
+const client = initiateDeveloperControlledWalletsClient({ apiKey: process.env.CIRCLE_API_KEY!, entitySecret: process.env.CIRCLE_ENTITY_SECRET! });
+const s = new Steward({
+  allowanceManager: "0x3AAfC635a1D1391c9FD8b5B9d8A518Fe980cb7E6",   // Arc Testnet
+  auditLog: "0x89264D27AFbCb2Ac90b8a3802340C26Ea1326866",
+  circle: { client, walletId: process.env.AGENT_WALLET_ID! },
+});
+const r = await s.decide({ allowanceId: 0n, amount: 150_000_000n, memo: "logo v2", inputs: { milestone: "logo v2" } });
+```
+
+```python
+# pip install "steward-sdk[circle]"
+from circle.web3 import utils
+from steward_sdk import Steward
+
+client = utils.init_developer_controlled_wallets_client(api_key=os.environ["CIRCLE_API_KEY"], entity_secret=os.environ["CIRCLE_ENTITY_SECRET"])
+s = Steward(allowance_manager="0x3AAfC635a1D1391c9FD8b5B9d8A518Fe980cb7E6", audit_log="0x89264D27AFbCb2Ac90b8a3802340C26Ea1326866",
+            circle_client=client, circle_wallet_id=os.environ["AGENT_WALLET_ID"])
+r = s.decide(allowance_id=0, amount=150_000_000, memo="logo v2", inputs={"milestone": "logo v2"})
+```
+
+Tested live on Arc Testnet with both SDKs (a `HOLD` recorded through a Circle wallet:
+[TypeScript](https://explorer.testnet.arc.io/tx/0x1618d269880dae697842db31470db89e383e48b42450e829b0b8458f94e8a73f),
+[Python](https://explorer.testnet.arc.io/tx/0xbb36c711456a84a2de37992f10b81409807db2436abdaecddb4d257bf9c1fda8)).
+
 ## Owner side
 
 The owner (a Circle Developer-Controlled wallet in the reference app) calls `create(agent, payee, capPerPeriod, perTxCap, period, expiry)`,

package/dist/index.cjs

@@ -77,13 +77,19 @@ function applyRules(a, p) {
   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 SIGNATURES = {
+  record: "record(uint256,bytes32,uint8,uint128)",
+  pay: "pay(uint256,uint128,bytes32,string)",
+  escalate: "escalate(uint256,uint128,bytes32,string)"
+};
 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 });
+    this.wallet = cfg.account ? (0, import_viem.createWalletClient)({ chain, transport, account: cfg.account }) : void 0;
+    if (!cfg.account && !cfg.circle) throw new Error("Steward needs either `account` (a viem account) or `circle` (a Circle wallet)");
   }
   cfg;
   pub;
@@ -98,7 +104,31 @@ var Steward = class {
     const maxFeePerGas = base + base / 4n > MIN_FEE_PER_GAS ? base + base / 4n : MIN_FEE_PER_GAS;
     return { maxFeePerGas, maxPriorityFeePerGas: 1000000000n };
   }
+  /** Submit through Circle and wait for the on-chain hash. The idempotency key is fixed first, so a retry can't double-submit. */
+  async writeCircle(address, functionName, args) {
+    const c = this.cfg.circle;
+    const idempotencyKey = globalThis.crypto.randomUUID();
+    const res = await c.client.createContractExecutionTransaction({
+      walletId: c.walletId,
+      contractAddress: address,
+      abiFunctionSignature: SIGNATURES[functionName],
+      abiParameters: args.map((a) => typeof a === "bigint" || typeof a === "number" ? a.toString() : a),
+      fee: { type: "level", config: { feeLevel: c.feeLevel ?? "MEDIUM" } },
+      idempotencyKey
+    });
+    const id = res.data?.id;
+    if (!id) throw new Error("Circle did not return a transaction id");
+    const deadline = Date.now() + (c.timeoutMs ?? 12e4);
+    while (Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, c.pollMs ?? 2e3));
+      const t = (await c.client.getTransaction({ id })).data?.transaction;
+      if ((t?.state === "COMPLETE" || t?.state === "CONFIRMED") && t.txHash) return t.txHash;
+      if (t?.state === "FAILED" || t?.state === "DENIED" || t?.state === "CANCELLED") throw new Error(`Circle tx ${id} ${t.state}: ${t.errorReason ?? ""}`);
+    }
+    throw new Error(`Circle tx ${id} not confirmed in time`);
+  }
   async write(address, abi, functionName, args) {
+    if (!this.wallet) return this.writeCircle(address, 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 });

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { Hex, Chain, Account, Transport } from 'viem';
+import { Hex, Chain, Transport, Account } from 'viem';
 export { arcTestnet } from 'viem/chains';
 
 declare const AM_ABI: readonly [{
@@ -190,23 +190,75 @@ declare function applyRules(a: Allowance, p: DecideParams): {
     pay: bigint;
     remainder: bigint;
 };
+/**
+ * The part of a Circle Developer-Controlled Wallets client STEWARD uses. Pass the client you already have:
+ * `initiateDeveloperControlledWalletsClient({ apiKey, entitySecret })` from `@circle-fin/developer-controlled-wallets`.
+ */
+type CircleClientLike = {
+    createContractExecutionTransaction(req: {
+        walletId?: string;
+        walletAddress?: string;
+        blockchain?: string;
+        contractAddress: string;
+        abiFunctionSignature: string;
+        abiParameters: unknown[];
+        fee: {
+            type: "level";
+            config: {
+                feeLevel: "LOW" | "MEDIUM" | "HIGH";
+            };
+        };
+        idempotencyKey?: string;
+    }): Promise<{
+        data?: {
+            id?: string;
+        };
+    }>;
+    getTransaction(req: {
+        id: string;
+    }): Promise<{
+        data?: {
+            transaction?: {
+                state?: string;
+                txHash?: string;
+                errorReason?: string;
+            };
+        };
+    }>;
+};
+/** Sign with a Circle developer-controlled wallet instead of a raw key. The allowance's `agent` must be this wallet's address. */
+type CircleSigner = {
+    client: CircleClientLike;
+    walletId: string;
+    feeLevel?: "LOW" | "MEDIUM" | "HIGH";
+    pollMs?: number;
+    timeoutMs?: number;
+};
+type StewardConfig = {
+    rpc?: string;
+    chain?: Chain;
+    allowanceManager: Hex;
+    auditLog: Hex;
+    transport?: Transport;
+} & ({
+    account: Account;
+    circle?: undefined;
+} | {
+    circle: CircleSigner;
+    account?: undefined;
+});
 declare class Steward {
     private cfg;
     private pub;
     private wallet;
-    constructor(cfg: {
-        rpc?: string;
-        chain?: Chain;
-        allowanceManager: Hex;
-        auditLog: Hex;
-        account: Account;
-        transport?: Transport;
-    });
+    constructor(cfg: StewardConfig);
     allowance(id: bigint): Promise<Allowance>;
     private fees;
+    /** Submit through Circle and wait for the on-chain hash. The idempotency key is fixed first, so a retry can't double-submit. */
+    private writeCircle;
     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 };
+export { ACTION_CODE, AM_ABI, type Action, type Allowance, type CircleClientLike, type CircleSigner, type DecideParams, type DecideResult, type DecisionRecord, LOG_ABI, MIN_FEE_PER_GAS, REMAINDER_TAG, Steward, applyRules, canonical, decisionHash, remainderHash };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Hex, Chain, Account, Transport } from 'viem';
+import { Hex, Chain, Transport, Account } from 'viem';
 export { arcTestnet } from 'viem/chains';
 
 declare const AM_ABI: readonly [{
@@ -190,23 +190,75 @@ declare function applyRules(a: Allowance, p: DecideParams): {
     pay: bigint;
     remainder: bigint;
 };
+/**
+ * The part of a Circle Developer-Controlled Wallets client STEWARD uses. Pass the client you already have:
+ * `initiateDeveloperControlledWalletsClient({ apiKey, entitySecret })` from `@circle-fin/developer-controlled-wallets`.
+ */
+type CircleClientLike = {
+    createContractExecutionTransaction(req: {
+        walletId?: string;
+        walletAddress?: string;
+        blockchain?: string;
+        contractAddress: string;
+        abiFunctionSignature: string;
+        abiParameters: unknown[];
+        fee: {
+            type: "level";
+            config: {
+                feeLevel: "LOW" | "MEDIUM" | "HIGH";
+            };
+        };
+        idempotencyKey?: string;
+    }): Promise<{
+        data?: {
+            id?: string;
+        };
+    }>;
+    getTransaction(req: {
+        id: string;
+    }): Promise<{
+        data?: {
+            transaction?: {
+                state?: string;
+                txHash?: string;
+                errorReason?: string;
+            };
+        };
+    }>;
+};
+/** Sign with a Circle developer-controlled wallet instead of a raw key. The allowance's `agent` must be this wallet's address. */
+type CircleSigner = {
+    client: CircleClientLike;
+    walletId: string;
+    feeLevel?: "LOW" | "MEDIUM" | "HIGH";
+    pollMs?: number;
+    timeoutMs?: number;
+};
+type StewardConfig = {
+    rpc?: string;
+    chain?: Chain;
+    allowanceManager: Hex;
+    auditLog: Hex;
+    transport?: Transport;
+} & ({
+    account: Account;
+    circle?: undefined;
+} | {
+    circle: CircleSigner;
+    account?: undefined;
+});
 declare class Steward {
     private cfg;
     private pub;
     private wallet;
-    constructor(cfg: {
-        rpc?: string;
-        chain?: Chain;
-        allowanceManager: Hex;
-        auditLog: Hex;
-        account: Account;
-        transport?: Transport;
-    });
+    constructor(cfg: StewardConfig);
     allowance(id: bigint): Promise<Allowance>;
     private fees;
+    /** Submit through Circle and wait for the on-chain hash. The idempotency key is fixed first, so a retry can't double-submit. */
+    private writeCircle;
     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 };
+export { ACTION_CODE, AM_ABI, type Action, type Allowance, type CircleClientLike, type CircleSigner, type DecideParams, type DecideResult, type DecisionRecord, LOG_ABI, MIN_FEE_PER_GAS, REMAINDER_TAG, Steward, applyRules, canonical, decisionHash, remainderHash };

package/dist/index.js

@@ -49,13 +49,19 @@ function applyRules(a, p) {
   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 SIGNATURES = {
+  record: "record(uint256,bytes32,uint8,uint128)",
+  pay: "pay(uint256,uint128,bytes32,string)",
+  escalate: "escalate(uint256,uint128,bytes32,string)"
+};
 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 });
+    this.wallet = cfg.account ? createWalletClient({ chain, transport, account: cfg.account }) : void 0;
+    if (!cfg.account && !cfg.circle) throw new Error("Steward needs either `account` (a viem account) or `circle` (a Circle wallet)");
   }
   cfg;
   pub;
@@ -70,7 +76,31 @@ var Steward = class {
     const maxFeePerGas = base + base / 4n > MIN_FEE_PER_GAS ? base + base / 4n : MIN_FEE_PER_GAS;
     return { maxFeePerGas, maxPriorityFeePerGas: 1000000000n };
   }
+  /** Submit through Circle and wait for the on-chain hash. The idempotency key is fixed first, so a retry can't double-submit. */
+  async writeCircle(address, functionName, args) {
+    const c = this.cfg.circle;
+    const idempotencyKey = globalThis.crypto.randomUUID();
+    const res = await c.client.createContractExecutionTransaction({
+      walletId: c.walletId,
+      contractAddress: address,
+      abiFunctionSignature: SIGNATURES[functionName],
+      abiParameters: args.map((a) => typeof a === "bigint" || typeof a === "number" ? a.toString() : a),
+      fee: { type: "level", config: { feeLevel: c.feeLevel ?? "MEDIUM" } },
+      idempotencyKey
+    });
+    const id = res.data?.id;
+    if (!id) throw new Error("Circle did not return a transaction id");
+    const deadline = Date.now() + (c.timeoutMs ?? 12e4);
+    while (Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, c.pollMs ?? 2e3));
+      const t = (await c.client.getTransaction({ id })).data?.transaction;
+      if ((t?.state === "COMPLETE" || t?.state === "CONFIRMED") && t.txHash) return t.txHash;
+      if (t?.state === "FAILED" || t?.state === "DENIED" || t?.state === "CANCELLED") throw new Error(`Circle tx ${id} ${t.state}: ${t.errorReason ?? ""}`);
+    }
+    throw new Error(`Circle tx ${id} not confirmed in time`);
+  }
   async write(address, abi, functionName, args) {
+    if (!this.wallet) return this.writeCircle(address, 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 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "steward-arc-sdk",
-  "version": "0.1.0",
+  "version": "0.2.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": {
@@ -31,7 +31,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts --clean",