hedera-curb 0.1.0 → 0.4.1

package/README.md

@@ -1,6 +1,6 @@
 # hedera-curb
 
-**Verifiable spend-control for Hedera AI agents.** Drop-in [Hedera Agent Kit](https://github.com/hashgraph/hedera-agent-kit-js) hooks that govern every payment your agent makes — per-task & daily budgets, a counterparty allowlist, and single-use human approval — and write every decision immutably to the Hedera Consensus Service.
+**Verifiable spend-control for Hedera AI agents.** Drop-in [Hedera Agent Kit](https://github.com/hashgraph/hedera-agent-kit-js) hooks that govern every payment your agent makes — per-task & rolling-24h budgets, a counterparty allowlist, and single-use human approval — and write every decision immutably to the Hedera Consensus Service.
 
 > ProveAI proves the model; Curb proves the spend.
 
@@ -10,50 +10,68 @@
 npm i hedera-curb @hashgraph/hedera-agent-kit @hiero-ledger/sdk
 ```
 
-## Use (≈12 lines)
+## Quickstart — two lines
 
 ```ts
-import { buildCurbHooks, InMemoryCurbStore } from 'hedera-curb';
-import { AgentMode } from '@hashgraph/hedera-agent-kit';
-import { coreAccountPlugin } from '@hashgraph/hedera-agent-kit/plugins';
-import { HederaAIToolkit } from '@hashgraph/hedera-agent-kit-ai-sdk';
+import { createCurb } from 'hedera-curb';
 
-const store = new InMemoryCurbStore();
-store.allowAccount(AGENT_ID, PROVIDER_ID); // who the agent may pay
+const curb = await createCurb({ client, agentAccountId }); // auto-creates audit + HCS-2 policy topics
+new HederaAIToolkit({ client, configuration: { context: { hooks: curb.hooks } } });
+```
+
+`createCurb` defaults the store to in-memory, auto-provisions the audit topic and an HCS-2 policy registry (owner-only writes), publishes the starting policy, and returns `{ hooks, config, store, auditTopicId, policyTopicId }`. Override anything:
+
+```ts
+await createCurb({ client, agentAccountId, perDay: 25, store: myRedisStore, auditTopicId, allowlist });
+```
+
+### Or provision from the terminal (no code)
 
-const cfg = { agentAccountId: AGENT_ID, auditTopicId: TOPIC_ID,
-  currency: 'HBAR' as const, perTask: 10, perDay: 25, autoUnder: 3, approveUnder: 10 };
+```bash
+npx hedera-curb init --network testnet
+# ✓ Audit topic: 0.0.x   ✓ Policy topic: 0.0.y (HCS-2, owner-only)
+```
 
-const toolkit = new HederaAIToolkit({ client, configuration: {
-  plugins: [coreAccountPlugin],
-  context: { mode: AgentMode.AUTONOMOUS, accountId: AGENT_ID,
-    hooks: buildCurbHooks({ cfg, store }) }, // ← that's the whole integration
-}});
+### Advanced: wire it yourself
+
+```ts
+import { buildCurbHooks, InMemoryCurbStore } from 'hedera-curb';
+const store = new InMemoryCurbStore();
+store.allowAccount(AGENT_ID, PROVIDER_ID);
+const cfg = { agentAccountId: AGENT_ID, auditTopicId: TOPIC_ID, currency: 'HBAR' as const, perTask: 10, perDay: 25, autoUnder: 3, approveUnder: 10 };
+// context: { hooks: buildCurbHooks({ cfg, store }) }
 ```
 
-Now every `transfer_hbar` the agent attempts passes the budget, allowlist, and approval policies **before** it executes, and every decision lands on your HCS audit topic.
+Now every governed transfer passes the budget, allowlist, and approval policies **before** it executes, and every decision lands on your HCS audit topic.
 
 ## Production storage
 
-`InMemoryCurbStore` is for tests / single-instance apps. For production, implement the 6-method `CurbStore` interface against Redis, Postgres, etc. — the policies stay durable and complete (never derived from a windowed read):
+`InMemoryCurbStore` is for tests / single-instance apps. For production, implement the `CurbStore` interface against Redis, Postgres, etc. Spend is a rolling-24h window split into **committed** (executed) and short-lived **holds** (atomic reservations) so two concurrent payments can't both slip under the cap:
 
 ```ts
 interface CurbStore {
   isAllowed(agent, account): Promise<boolean>;
-  getDailySpend(agent): Promise<number>;
+  getDailySpend(agent): Promise<number>;                       // committed (executed) spend
   incrDailySpend(agent, amount): Promise<void>;
+  tryReserveSpend(agent, key, amount, cap): Promise<boolean>;  // atomic hold; idempotent per key
+  commitSpend(agent, key, amount): Promise<void>;              // hold → committed on execution
   getApproval(requestId): Promise<'pending' | 'approved' | 'rejected' | null>;
   setApproval(requestId, status, meta?): Promise<void>;
   consumeApproval(requestId): Promise<void>;
 }
 ```
 
+## Beyond budgets
+
+The [full project](https://github.com/Madhav-Gupta-28/Curb) is a trust ladder: off-chain hooks (this package) → HCS audit + an HCS-2 **versioned policy registry** → an on-chain **`CurbVault`** contract that enforces caps + allowlist *in Hedera consensus* → non-custodial allowance / scheduled-transaction approvals. Pick how much to trust the server.
+
 ## Exports
 
-- `SpendLimitPolicy`, `CounterpartyAllowlistPolicy`, `ApprovalTierPolicy` — composable `AbstractPolicy`s.
-- `CurbAuditHook` — an immutable HCS record per settled payment.
+- `createCurb(opts)` — one-call setup (topics, store, hooks).
 - `buildCurbHooks(deps)` — the ordered policy + audit stack for `context.hooks`.
-- `CurbStore` + `InMemoryCurbStore`, `extractPayment`, `writeRecord`, and the `CurbConfig` / `CurbRecord` types.
+- `SpendLimitPolicy`, `CounterpartyAllowlistPolicy`, `ApprovalTierPolicy`, `CurbAuditHook`.
+- `createAuditTopic`, `createPolicyRegistry`, `publishPolicyVersion`, `readPolicyVersions`, `currentPolicy` — HCS-2 policy versioning.
+- `CurbStore` + `InMemoryCurbStore`, `extractPayment`, `paymentKey`, `writeRecord`, and the `CurbConfig` / `CurbRecord` types.
 
 ## License
 

package/dist/audit.d.ts

@@ -1,5 +1,10 @@
 import { Client } from '@hiero-ledger/sdk';
-import type { CurbConfig } from './config';
-import type { CurbRecord } from './records';
+import type { CurbConfig } from './config.js';
+import type { CurbRecord } from './records.js';
+/**
+ * Create an immutable HCS audit topic. No admin key (config can't change) and no submit key
+ * (records come from whichever client runs the hooks; junk writes are filtered on read by decode).
+ */
+export declare function createAuditTopic(client: Client, memo?: string): Promise<string>;
 /** Append an immutable record to the Curb audit topic on HCS. */
 export declare function writeRecord(client: Client, cfg: CurbConfig, partial: Omit<CurbRecord, 'v' | 'agent' | 'ts'>): Promise<CurbRecord>;

package/dist/audit.js

@@ -1,10 +1,24 @@
-import { TopicMessageSubmitTransaction } from '@hiero-ledger/sdk';
+import { TopicCreateTransaction, TopicMessageSubmitTransaction } from '@hiero-ledger/sdk';
+/**
+ * Create an immutable HCS audit topic. No admin key (config can't change) and no submit key
+ * (records come from whichever client runs the hooks; junk writes are filtered on read by decode).
+ */
+export async function createAuditTopic(client, memo = 'curb-audit') {
+    const receipt = await (await new TopicCreateTransaction().setTopicMemo(memo).execute(client)).getReceipt(client);
+    return receipt.topicId.toString();
+}
 /** Append an immutable record to the Curb audit topic on HCS. */
 export async function writeRecord(client, cfg, partial) {
     const rec = { v: 1, agent: cfg.agentAccountId, ts: Date.now(), ...partial };
-    await new TopicMessageSubmitTransaction({
-        topicId: cfg.auditTopicId,
-        message: JSON.stringify(rec),
-    }).execute(client);
+    try {
+        await new TopicMessageSubmitTransaction({
+            topicId: cfg.auditTopicId,
+            message: JSON.stringify(rec),
+        }).execute(client);
+    }
+    catch (e) {
+        // never let a transient HCS hiccup break enforcement — but surface it, don't drop silently.
+        console.error(`[curb] audit write failed (${rec.type}/${rec.reason ?? ''}):`, e.message);
+    }
     return rec;
 }

package/dist/build-hooks.d.ts

@@ -1,12 +1,13 @@
 import { RejectToolPolicy } from '@hashgraph/hedera-agent-kit/policies';
 import { HcsAuditTrailHook } from '@hashgraph/hedera-agent-kit/hooks';
-import { SpendLimitPolicy } from './policies/spend-limit';
-import { CounterpartyAllowlistPolicy } from './policies/counterparty-allowlist';
-import { ApprovalTierPolicy } from './policies/approval-tier';
-import { CurbAuditHook } from './hooks/curb-audit-hook';
-import type { CurbDeps } from './deps';
+import { SpendLimitPolicy } from './policies/spend-limit.js';
+import { CounterpartyAllowlistPolicy } from './policies/counterparty-allowlist.js';
+import { ApprovalTierPolicy } from './policies/approval-tier.js';
+import { CurbAuditHook } from './hooks/curb-audit-hook.js';
+import type { CurbDeps } from './deps.js';
 /**
  * The ordered Curb policy + audit stack, ready to drop into `configuration.context.hooks`.
- * Hard-disables every account-mutating / allowance tool, then governs `transfer_hbar`.
+ * Hard-disables account-mutating / allowance-granting tools, then governs every transfer
+ * (direct and allowance-based) through the budget, allowlist, and approval policies.
  */
 export declare function buildCurbHooks(d: CurbDeps): (SpendLimitPolicy | CounterpartyAllowlistPolicy | ApprovalTierPolicy | CurbAuditHook | RejectToolPolicy | HcsAuditTrailHook)[];

package/dist/build-hooks.js

@@ -1,13 +1,15 @@
 import { RejectToolPolicy } from '@hashgraph/hedera-agent-kit/policies';
 import { HcsAuditTrailHook } from '@hashgraph/hedera-agent-kit/hooks';
 import { coreAccountPluginToolNames } from '@hashgraph/hedera-agent-kit/plugins';
-import { SpendLimitPolicy } from './policies/spend-limit';
-import { CounterpartyAllowlistPolicy } from './policies/counterparty-allowlist';
-import { ApprovalTierPolicy } from './policies/approval-tier';
-import { CurbAuditHook } from './hooks/curb-audit-hook';
+import { GOVERNED_TRANSFER_TOOLS } from './tools.js';
+import { SpendLimitPolicy } from './policies/spend-limit.js';
+import { CounterpartyAllowlistPolicy } from './policies/counterparty-allowlist.js';
+import { ApprovalTierPolicy } from './policies/approval-tier.js';
+import { CurbAuditHook } from './hooks/curb-audit-hook.js';
 /**
  * The ordered Curb policy + audit stack, ready to drop into `configuration.context.hooks`.
- * Hard-disables every account-mutating / allowance tool, then governs `transfer_hbar`.
+ * Hard-disables account-mutating / allowance-granting tools, then governs every transfer
+ * (direct and allowance-based) through the budget, allowlist, and approval policies.
  */
 export function buildCurbHooks(d) {
     return [
@@ -15,14 +17,13 @@ export function buildCurbHooks(d) {
             coreAccountPluginToolNames.CREATE_ACCOUNT_TOOL,
             coreAccountPluginToolNames.DELETE_ACCOUNT_TOOL,
             coreAccountPluginToolNames.UPDATE_ACCOUNT_TOOL,
-            coreAccountPluginToolNames.APPROVE_HBAR_ALLOWANCE_TOOL,
+            coreAccountPluginToolNames.APPROVE_HBAR_ALLOWANCE_TOOL, // only the user grants allowances, never the agent
             coreAccountPluginToolNames.DELETE_HBAR_ALLOWANCE_TOOL,
-            coreAccountPluginToolNames.TRANSFER_HBAR_WITH_ALLOWANCE_TOOL,
         ]),
         new CounterpartyAllowlistPolicy(d),
         new SpendLimitPolicy(d),
         new ApprovalTierPolicy(d),
         new CurbAuditHook(d),
-        new HcsAuditTrailHook([coreAccountPluginToolNames.TRANSFER_HBAR_TOOL], d.cfg.auditTopicId),
+        new HcsAuditTrailHook(GOVERNED_TRANSFER_TOOLS, d.cfg.auditTopicId),
     ];
 }

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+// Provisions Curb's on-chain topics without touching the Agent Kit, so it runs anywhere the SDK is present.
+import { Client, PrivateKey } from '@hiero-ledger/sdk';
+// explicit .js extensions so the compiled CLI runs under pure Node ESM (the bin entrypoint)
+import { createAuditTopic } from './audit.js';
+import { createPolicyRegistry, publishPolicyVersion } from './policy-registry.js';
+import { DEFAULT_CONFIG } from './config.js';
+const flag = (name) => {
+    const i = process.argv.indexOf(`--${name}`);
+    return i >= 0 ? process.argv[i + 1] : undefined;
+};
+function parseKey(s) {
+    for (const parse of [PrivateKey.fromStringECDSA, PrivateKey.fromStringED25519, PrivateKey.fromStringDer]) {
+        try {
+            return parse(s);
+        }
+        catch {
+            /* try next encoding */
+        }
+    }
+    throw new Error('could not parse the private key (expected ECDSA / ED25519 / DER hex)');
+}
+async function init() {
+    const network = (flag('network') ?? process.env.HEDERA_NETWORK ?? 'testnet').toLowerCase();
+    const account = flag('account') ?? process.env.HEDERA_OPERATOR_ID ?? process.env.ACCOUNT_ID;
+    const key = flag('key') ?? process.env.HEDERA_OPERATOR_KEY ?? process.env.PRIVATE_KEY;
+    const agent = flag('agent') ?? process.env.AGENT_ACCOUNT_ID ?? account;
+    if (!account || !key) {
+        console.error('Missing credentials. Pass --account and --key, or set HEDERA_OPERATOR_ID / HEDERA_OPERATOR_KEY.');
+        process.exit(1);
+    }
+    console.log(`Provisioning Curb on ${network}…`);
+    const client = Client.forName(network).setOperator(account, parseKey(key));
+    const auditTopicId = await createAuditTopic(client);
+    const policyTopicId = await createPolicyRegistry(client);
+    const config = {
+        agentAccountId: agent,
+        auditTopicId,
+        ...DEFAULT_CONFIG,
+        perTask: Number(flag('per-task') ?? DEFAULT_CONFIG.perTask),
+        perDay: Number(flag('per-day') ?? DEFAULT_CONFIG.perDay),
+    };
+    await publishPolicyVersion(client, config, policyTopicId, 'initial policy').catch(() => { });
+    console.log(`\n✓ Audit topic:  ${auditTopicId}`);
+    console.log(`✓ Policy topic: ${policyTopicId}  (HCS-2, owner-only writes)`);
+    console.log('\nAdd these to your .env:\n');
+    console.log(`CURB_AUDIT_TOPIC_ID=${auditTopicId}`);
+    console.log(`CURB_POLICY_TOPIC_ID=${policyTopicId}`);
+    console.log('\nDone — drop `createCurb({ client, agentAccountId }).hooks` into the Agent Kit and you are governed.');
+    process.exit(0);
+}
+const cmd = process.argv[2];
+if (cmd === 'init') {
+    init().catch((e) => {
+        console.error(String(e?.message ?? e));
+        process.exit(1);
+    });
+}
+else {
+    console.log('Usage: hedera-curb init [--network testnet] [--account 0.0.x] [--key <priv>] [--agent 0.0.y] [--per-task 10] [--per-day 25]');
+    process.exit(cmd ? 1 : 0);
+}

package/dist/create-curb.d.ts

@@ -0,0 +1,38 @@
+import type { Client } from '@hiero-ledger/sdk';
+import { buildCurbHooks } from './build-hooks.js';
+import { type CurbStore } from './store.js';
+import { type CurbConfig, type Currency } from './config.js';
+export interface CreateCurbOptions {
+    /** Operator client — used to create topics and write the audit trail. */
+    client: Client;
+    /** The agent's Hedera account id (the governed / bounded-allowance account). */
+    agentAccountId: string;
+    /** Bring your own store (Redis, Postgres, …). Defaults to an in-memory store. */
+    store?: CurbStore;
+    /** Reuse an existing audit topic; omit to auto-create one. */
+    auditTopicId?: string;
+    /** Reuse an existing HCS-2 policy registry; omit to auto-create one; pass `false` to skip versioning. */
+    policyTopicId?: string | false;
+    currency?: Currency;
+    perTask?: number;
+    perDay?: number;
+    autoUnder?: number;
+    approveUnder?: number;
+}
+export interface Curb {
+    /** Drop straight into the Agent Kit's `configuration.context.hooks`. */
+    hooks: ReturnType<typeof buildCurbHooks>;
+    config: CurbConfig;
+    store: CurbStore;
+    auditTopicId: string;
+    policyTopicId?: string;
+}
+/**
+ * One-call setup for Curb. Auto-creates the audit topic (and an HCS-2 policy registry), defaults the
+ * store to in-memory, publishes the initial policy version, and returns ready-to-use Agent Kit hooks.
+ *
+ * @example
+ * const curb = await createCurb({ client, agentAccountId, perDay: 25 });
+ * new HederaAIToolkit({ client, configuration: { context: { hooks: curb.hooks } } });
+ */
+export declare function createCurb(opts: CreateCurbOptions): Promise<Curb>;

package/dist/create-curb.js

@@ -0,0 +1,38 @@
+import { buildCurbHooks } from './build-hooks.js';
+import { InMemoryCurbStore } from './store.js';
+import { createAuditTopic } from './audit.js';
+import { createPolicyRegistry, publishPolicyVersion } from './policy-registry.js';
+import { DEFAULT_CONFIG } from './config.js';
+/**
+ * One-call setup for Curb. Auto-creates the audit topic (and an HCS-2 policy registry), defaults the
+ * store to in-memory, publishes the initial policy version, and returns ready-to-use Agent Kit hooks.
+ *
+ * @example
+ * const curb = await createCurb({ client, agentAccountId, perDay: 25 });
+ * new HederaAIToolkit({ client, configuration: { context: { hooks: curb.hooks } } });
+ */
+export async function createCurb(opts) {
+    const store = opts.store ?? new InMemoryCurbStore();
+    const auditTopicId = opts.auditTopicId ?? (await createAuditTopic(opts.client));
+    const autoPolicy = opts.policyTopicId === undefined;
+    const policyTopicId = opts.policyTopicId === false ? undefined : (opts.policyTopicId ?? (await createPolicyRegistry(opts.client)));
+    const config = {
+        agentAccountId: opts.agentAccountId,
+        auditTopicId,
+        currency: opts.currency ?? DEFAULT_CONFIG.currency,
+        perTask: opts.perTask ?? DEFAULT_CONFIG.perTask,
+        perDay: opts.perDay ?? DEFAULT_CONFIG.perDay,
+        autoUnder: opts.autoUnder ?? DEFAULT_CONFIG.autoUnder,
+        approveUnder: opts.approveUnder ?? DEFAULT_CONFIG.approveUnder,
+    };
+    // seed the registry with the live caps so the on-chain policy is authoritative from day one
+    if (policyTopicId && autoPolicy) {
+        try {
+            await publishPolicyVersion(opts.client, config, policyTopicId, 'initial policy');
+        }
+        catch {
+            /* non-fatal: the registry exists; versions can be published later */
+        }
+    }
+    return { hooks: buildCurbHooks({ cfg: config, store }), config, store, auditTopicId, policyTopicId };
+}

package/dist/deps.d.ts

@@ -1,5 +1,5 @@
-import type { CurbConfig } from './config';
-import type { CurbStore } from './store';
+import type { CurbConfig } from './config.js';
+import type { CurbStore } from './store.js';
 /** Everything every Curb policy and hook needs at construction time. */
 export interface CurbDeps {
     cfg: CurbConfig;

package/dist/extract.d.ts

@@ -1,11 +1,14 @@
+/** Deterministic key for a payment (agent + recipient + amount) — used for spend holds and approvals. */
+export declare function paymentKey(agent: string, recipient: string, amount: number): string;
 export interface PaymentIntent {
     amount: number;
     currency: 'HBAR' | 'USDC';
     recipients: string[];
 }
 /**
- * Pull the payment amount + recipients out of a tool's normalised params.
- * HBAR transfers normalise to `{ hbarTransfers: [{ accountId, amount }] }` and include the
- * sender as a negative entry — we keep only the positive credits.
+ * Pull the payment amount + recipients out of a governed transfer's normalised params.
+ * Both `transfer_hbar` and `transfer_hbar_with_allowance` normalise recipients to
+ * `{ hbarTransfers: [{ accountId, amount }] }` (the sender/owner is a separate negative entry).
+ * We keep only the positive credits, which equal the amount actually spent.
  */
 export declare function extractPayment(method: string, normalised: any): PaymentIntent | null;

package/dist/extract.js

@@ -1,5 +1,10 @@
+import crypto from 'node:crypto';
 import { Hbar } from '@hiero-ledger/sdk';
-import { coreAccountPluginToolNames } from '@hashgraph/hedera-agent-kit/plugins';
+import { GOVERNED_TRANSFER_TOOLS } from './tools.js';
+/** Deterministic key for a payment (agent + recipient + amount) — used for spend holds and approvals. */
+export function paymentKey(agent, recipient, amount) {
+    return crypto.createHash('sha256').update(`${agent}:${recipient}:${amount}`).digest('hex').slice(0, 16);
+}
 function hbarToNumber(a) {
     if (a instanceof Hbar)
         return a.toBigNumber().toNumber();
@@ -10,12 +15,13 @@ function hbarToNumber(a) {
     return Number(a?.toString?.() ?? 0);
 }
 /**
- * Pull the payment amount + recipients out of a tool's normalised params.
- * HBAR transfers normalise to `{ hbarTransfers: [{ accountId, amount }] }` and include the
- * sender as a negative entry — we keep only the positive credits.
+ * Pull the payment amount + recipients out of a governed transfer's normalised params.
+ * Both `transfer_hbar` and `transfer_hbar_with_allowance` normalise recipients to
+ * `{ hbarTransfers: [{ accountId, amount }] }` (the sender/owner is a separate negative entry).
+ * We keep only the positive credits, which equal the amount actually spent.
  */
 export function extractPayment(method, normalised) {
-    if (method === coreAccountPluginToolNames.TRANSFER_HBAR_TOOL) {
+    if (GOVERNED_TRANSFER_TOOLS.includes(method)) {
         const transfers = normalised?.hbarTransfers ?? [];
         const credits = transfers.filter((t) => hbarToNumber(t.amount) > 0);
         return {

package/dist/hooks/curb-audit-hook.d.ts

@@ -1,5 +1,5 @@
 import { AbstractHook, type PostSecondaryActionParams } from '@hashgraph/hedera-agent-kit';
-import type { CurbDeps } from '../deps';
+import type { CurbDeps } from '../deps.js';
 /** Records every settled payment on HCS and advances the durable daily-spend counter. */
 export declare class CurbAuditHook extends AbstractHook {
     private d;

package/dist/hooks/curb-audit-hook.js

@@ -1,7 +1,7 @@
 import { AbstractHook } from '@hashgraph/hedera-agent-kit';
-import { coreAccountPluginToolNames } from '@hashgraph/hedera-agent-kit/plugins';
-import { extractPayment } from '../extract';
-import { writeRecord } from '../audit';
+import { GOVERNED_TRANSFER_TOOLS } from '../tools.js';
+import { extractPayment, paymentKey } from '../extract.js';
+import { writeRecord } from '../audit.js';
 // `toolResult` is typed `any` in the kit; these are the observed shapes for tx id.
 function extractTxId(toolResult) {
     return (toolResult?.raw?.transactionId ??
@@ -15,7 +15,7 @@ export class CurbAuditHook extends AbstractHook {
     d;
     name = 'curb.audit';
     description = 'Records every settled payment on HCS';
-    relevantTools = [coreAccountPluginToolNames.TRANSFER_HBAR_TOOL];
+    relevantTools = GOVERNED_TRANSFER_TOOLS;
     constructor(d) {
         super();
         this.d = d;
@@ -34,7 +34,9 @@ export class CurbAuditHook extends AbstractHook {
             allowed: true,
             reason: 'settled',
         });
-        if (intent?.amount)
-            await this.d.store.incrDailySpend(this.d.cfg.agentAccountId, intent.amount);
+        if (intent?.amount) {
+            const key = paymentKey(this.d.cfg.agentAccountId, intent.recipients[0], intent.amount);
+            await this.d.store.commitSpend(this.d.cfg.agentAccountId, key, intent.amount);
+        }
     }
 }

package/dist/index.d.ts

@@ -1,11 +1,14 @@
-export * from './config';
-export * from './records';
-export * from './store';
-export * from './deps';
-export * from './extract';
-export * from './audit';
-export * from './policies/spend-limit';
-export * from './policies/counterparty-allowlist';
-export * from './policies/approval-tier';
-export * from './hooks/curb-audit-hook';
-export * from './build-hooks';
+export * from './config.js';
+export * from './records.js';
+export * from './store.js';
+export * from './deps.js';
+export * from './tools.js';
+export * from './extract.js';
+export * from './audit.js';
+export * from './policy-registry.js';
+export * from './policies/spend-limit.js';
+export * from './policies/counterparty-allowlist.js';
+export * from './policies/approval-tier.js';
+export * from './hooks/curb-audit-hook.js';
+export * from './build-hooks.js';
+export * from './create-curb.js';

package/dist/index.js

@@ -1,11 +1,14 @@
-export * from './config';
-export * from './records';
-export * from './store';
-export * from './deps';
-export * from './extract';
-export * from './audit';
-export * from './policies/spend-limit';
-export * from './policies/counterparty-allowlist';
-export * from './policies/approval-tier';
-export * from './hooks/curb-audit-hook';
-export * from './build-hooks';
+export * from './config.js';
+export * from './records.js';
+export * from './store.js';
+export * from './deps.js';
+export * from './tools.js';
+export * from './extract.js';
+export * from './audit.js';
+export * from './policy-registry.js';
+export * from './policies/spend-limit.js';
+export * from './policies/counterparty-allowlist.js';
+export * from './policies/approval-tier.js';
+export * from './hooks/curb-audit-hook.js';
+export * from './build-hooks.js';
+export * from './create-curb.js';

package/dist/policies/approval-tier.d.ts

@@ -1,5 +1,5 @@
 import { AbstractPolicy, type PostParamsNormalizationParams } from '@hashgraph/hedera-agent-kit';
-import type { CurbDeps } from '../deps';
+import type { CurbDeps } from '../deps.js';
 /**
  * Tiered human-in-the-loop:
  *  - below `autoUnder`  → auto-approve

package/dist/policies/approval-tier.js

@@ -1,8 +1,8 @@
 import crypto from 'node:crypto';
 import { AbstractPolicy } from '@hashgraph/hedera-agent-kit';
-import { coreAccountPluginToolNames } from '@hashgraph/hedera-agent-kit/plugins';
-import { extractPayment } from '../extract';
-import { writeRecord } from '../audit';
+import { GOVERNED_TRANSFER_TOOLS } from '../tools.js';
+import { extractPayment } from '../extract.js';
+import { writeRecord } from '../audit.js';
 /**
  * Tiered human-in-the-loop:
  *  - below `autoUnder`  → auto-approve
@@ -13,7 +13,7 @@ export class ApprovalTierPolicy extends AbstractPolicy {
     d;
     name = 'curb.approval-tier';
     description = 'Requires single-use human approval for larger payments';
-    relevantTools = [coreAccountPluginToolNames.TRANSFER_HBAR_TOOL];
+    relevantTools = GOVERNED_TRANSFER_TOOLS;
     constructor(d) {
         super();
         this.d = d;

package/dist/policies/counterparty-allowlist.d.ts

@@ -1,5 +1,5 @@
 import { AbstractPolicy, type PostParamsNormalizationParams } from '@hashgraph/hedera-agent-kit';
-import type { CurbDeps } from '../deps';
+import type { CurbDeps } from '../deps.js';
 /** Blocks payments to any account not on the allowlist. */
 export declare class CounterpartyAllowlistPolicy extends AbstractPolicy {
     private d;

package/dist/policies/counterparty-allowlist.js

@@ -1,13 +1,13 @@
 import { AbstractPolicy } from '@hashgraph/hedera-agent-kit';
-import { coreAccountPluginToolNames } from '@hashgraph/hedera-agent-kit/plugins';
-import { extractPayment } from '../extract';
-import { writeRecord } from '../audit';
+import { GOVERNED_TRANSFER_TOOLS } from '../tools.js';
+import { extractPayment } from '../extract.js';
+import { writeRecord } from '../audit.js';
 /** Blocks payments to any account not on the allowlist. */
 export class CounterpartyAllowlistPolicy extends AbstractPolicy {
     d;
     name = 'curb.allowlist';
     description = 'Blocks payments to accounts not on the allowlist';
-    relevantTools = [coreAccountPluginToolNames.TRANSFER_HBAR_TOOL];
+    relevantTools = GOVERNED_TRANSFER_TOOLS;
     constructor(d) {
         super();
         this.d = d;

package/dist/policies/spend-limit.d.ts

@@ -1,6 +1,10 @@
 import { AbstractPolicy, type PostParamsNormalizationParams } from '@hashgraph/hedera-agent-kit';
-import type { CurbDeps } from '../deps';
-/** Blocks a payment that would breach the per-task or rolling daily budget (durable store counter). */
+import type { CurbDeps } from '../deps.js';
+/**
+ * Blocks a payment that would breach the per-task or rolling daily budget.
+ * The daily check is an **atomic reserve** (a short-lived hold) so two concurrent payments can't both
+ * slip under the cap; the hold is committed on execution by {@link CurbAuditHook}.
+ */
 export declare class SpendLimitPolicy extends AbstractPolicy {
     private d;
     name: string;

package/dist/policies/spend-limit.js

@@ -1,13 +1,17 @@
 import { AbstractPolicy } from '@hashgraph/hedera-agent-kit';
-import { coreAccountPluginToolNames } from '@hashgraph/hedera-agent-kit/plugins';
-import { extractPayment } from '../extract';
-import { writeRecord } from '../audit';
-/** Blocks a payment that would breach the per-task or rolling daily budget (durable store counter). */
+import { GOVERNED_TRANSFER_TOOLS } from '../tools.js';
+import { extractPayment, paymentKey } from '../extract.js';
+import { writeRecord } from '../audit.js';
+/**
+ * Blocks a payment that would breach the per-task or rolling daily budget.
+ * The daily check is an **atomic reserve** (a short-lived hold) so two concurrent payments can't both
+ * slip under the cap; the hold is committed on execution by {@link CurbAuditHook}.
+ */
 export class SpendLimitPolicy extends AbstractPolicy {
     d;
     name = 'curb.spend-limit';
     description = 'Blocks a payment that would exceed the per-task or rolling daily budget';
-    relevantTools = [coreAccountPluginToolNames.TRANSFER_HBAR_TOOL];
+    relevantTools = GOVERNED_TRANSFER_TOOLS;
     constructor(d) {
         super();
         this.d = d;
@@ -17,10 +21,21 @@ export class SpendLimitPolicy extends AbstractPolicy {
         if (!intent)
             return false;
         const { cfg, store } = this.d;
-        const already = await store.getDailySpend(cfg.agentAccountId);
-        const overTask = intent.amount > cfg.perTask;
-        const overDay = already + intent.amount > cfg.perDay;
-        const block = overTask || overDay;
+        if (intent.amount > cfg.perTask) {
+            await writeRecord(params.client, cfg, {
+                type: 'decision',
+                policy: this.name,
+                method,
+                amount: intent.amount,
+                currency: intent.currency,
+                counterparty: intent.recipients[0],
+                allowed: false,
+                reason: 'per_task_exceeded',
+            });
+            return true;
+        }
+        const key = paymentKey(cfg.agentAccountId, intent.recipients[0], intent.amount);
+        const reserved = await store.tryReserveSpend(cfg.agentAccountId, key, intent.amount, cfg.perDay);
         await writeRecord(params.client, cfg, {
             type: 'decision',
             policy: this.name,
@@ -28,9 +43,9 @@ export class SpendLimitPolicy extends AbstractPolicy {
             amount: intent.amount,
             currency: intent.currency,
             counterparty: intent.recipients[0],
-            allowed: !block,
-            reason: block ? (overTask ? 'per_task_exceeded' : 'per_day_exceeded') : 'within_budget',
+            allowed: reserved,
+            reason: reserved ? 'within_budget' : 'per_day_exceeded',
         });
-        return block;
+        return !reserved;
     }
 }

package/dist/policy-registry.d.ts

@@ -0,0 +1,35 @@
+import { Client } from '@hiero-ledger/sdk';
+import type { CurbConfig } from './config.js';
+/** The policy fields that are versioned on-chain. */
+export interface PolicySnapshot {
+    currency: string;
+    perTask: number;
+    perDay: number;
+    autoUnder: number;
+    approveUnder: number;
+}
+export interface PolicyVersion extends PolicySnapshot {
+    /** 1-based version number, in consensus order. */
+    version: number;
+    reason: string;
+    /** Publisher wall-clock (ms) at publish time. */
+    ts: number;
+    sequenceNumber: number;
+    consensusTimestamp: string;
+}
+/**
+ * Create an HCS-2 indexed registry topic for Curb policy versions. The submit key is set to the
+ * operator's key so ONLY the owner can publish policy versions — otherwise anyone could submit a
+ * fake policy (e.g. huge caps) that `resolveConfig` would adopt. Returns the topic id.
+ */
+export declare function createPolicyRegistry(client: Client, ttl?: number): Promise<string>;
+/** Publish the current config as a new immutable policy version on the registry. */
+export declare function publishPolicyVersion(client: Client, cfg: CurbConfig, registryTopicId: string, reason: string): Promise<PolicySnapshot>;
+/**
+ * Read the full policy version history from the HCS-2 registry via the mirror node (consensus order).
+ * Pass `trustedPayer` (the owner's account id) to only trust versions the owner published — a
+ * defense-in-depth against policy injection even on a topic without a submit key.
+ */
+export declare function readPolicyVersions(registryTopicId: string, mirrorBaseUrl: string, trustedPayer?: string): Promise<PolicyVersion[]>;
+/** The current (latest) policy version on the registry, or null if empty. */
+export declare function currentPolicy(registryTopicId: string, mirrorBaseUrl: string, trustedPayer?: string): Promise<PolicyVersion | null>;

package/dist/policy-registry.js

@@ -0,0 +1,96 @@
+import { TopicCreateTransaction, TopicMessageSubmitTransaction } from '@hiero-ledger/sdk';
+/**
+ * HCS-2 policy versioning for Curb.
+ *
+ * Curb's spending policy (caps + tiers) is published to an HCS-2 *indexed* registry topic, so every
+ * change is an immutable, consensus-timestamped version. Anyone can replay the topic to audit exactly
+ * what the limits were at any point and why they changed — the policy itself becomes verifiable, not
+ * just the payments it governs.
+ *
+ * Per HCS-2: topic memo `hcs-2:{registryType}:{ttl}` (0 = indexed, keep all records); each version is a
+ * `register` op whose `metadata` carries the policy inline as a data URI and `t_id` references the
+ * audit topic the policy governs.
+ */
+const HCS2 = 'hcs-2';
+const snapshot = (cfg) => ({
+    currency: cfg.currency,
+    perTask: cfg.perTask,
+    perDay: cfg.perDay,
+    autoUnder: cfg.autoUnder,
+    approveUnder: cfg.approveUnder,
+});
+/**
+ * Create an HCS-2 indexed registry topic for Curb policy versions. The submit key is set to the
+ * operator's key so ONLY the owner can publish policy versions — otherwise anyone could submit a
+ * fake policy (e.g. huge caps) that `resolveConfig` would adopt. Returns the topic id.
+ */
+export async function createPolicyRegistry(client, ttl = 86400) {
+    const tx = new TopicCreateTransaction().setTopicMemo(`${HCS2}:0:${ttl}`);
+    const submitKey = client.operatorPublicKey;
+    if (submitKey)
+        tx.setSubmitKey(submitKey);
+    const receipt = await (await tx.execute(client)).getReceipt(client);
+    return receipt.topicId.toString();
+}
+/** Publish the current config as a new immutable policy version on the registry. */
+export async function publishPolicyVersion(client, cfg, registryTopicId, reason) {
+    const snap = snapshot(cfg);
+    const payload = { ...snap, reason, ts: Date.now() };
+    const metadata = `data:application/json;base64,${Buffer.from(JSON.stringify(payload)).toString('base64')}`;
+    const message = { p: HCS2, op: 'register', t_id: cfg.auditTopicId, metadata, m: reason };
+    await new TopicMessageSubmitTransaction({
+        topicId: registryTopicId,
+        message: JSON.stringify(message),
+    }).execute(client);
+    return snap;
+}
+/**
+ * Read the full policy version history from the HCS-2 registry via the mirror node (consensus order).
+ * Pass `trustedPayer` (the owner's account id) to only trust versions the owner published — a
+ * defense-in-depth against policy injection even on a topic without a submit key.
+ */
+export async function readPolicyVersions(registryTopicId, mirrorBaseUrl, trustedPayer) {
+    const versions = [];
+    let url = `${mirrorBaseUrl}/topics/${registryTopicId}/messages?order=asc&limit=100`;
+    let n = 0;
+    while (url) {
+        const res = await fetch(url);
+        if (!res.ok)
+            break;
+        const json = await res.json();
+        for (const m of (json.messages ?? [])) {
+            if (trustedPayer && m.payer_account_id !== trustedPayer)
+                continue; // ignore non-owner versions
+            try {
+                const msg = JSON.parse(Buffer.from(m.message, 'base64').toString('utf8'));
+                if (msg.p !== HCS2 || msg.op !== 'register' || typeof msg.metadata !== 'string')
+                    continue;
+                const b64 = msg.metadata.startsWith('data:') ? msg.metadata.split(',')[1] : msg.metadata;
+                const p = JSON.parse(Buffer.from(b64, 'base64').toString('utf8'));
+                versions.push({
+                    version: ++n,
+                    currency: p.currency,
+                    perTask: p.perTask,
+                    perDay: p.perDay,
+                    autoUnder: p.autoUnder,
+                    approveUnder: p.approveUnder,
+                    reason: p.reason ?? msg.m ?? '',
+                    ts: p.ts ?? 0,
+                    sequenceNumber: m.sequence_number,
+                    consensusTimestamp: m.consensus_timestamp,
+                });
+            }
+            catch {
+                /* skip malformed entries */
+            }
+        }
+        const next = json.links?.next;
+        url = next ? new URL(next, mirrorBaseUrl).toString() : null;
+    }
+    return versions;
+}
+/** The current (latest) policy version on the registry, or null if empty. */
+export async function currentPolicy(registryTopicId, mirrorBaseUrl, trustedPayer) {
+    const all = await readPolicyVersions(registryTopicId, mirrorBaseUrl, trustedPayer);
+    return all.length ? all[all.length - 1] : null;
+}

package/dist/store.d.ts

@@ -7,12 +7,24 @@ export interface ApprovalMeta {
 /**
  * The operational state Curb needs at runtime. Bring your own implementation
  * (Redis, Postgres, …) or use {@link InMemoryCurbStore} for tests / single-process apps.
- * Everything here is durable and complete — never derived from a windowed read.
+ *
+ * Spend is a rolling 24h window (matching the on-chain CurbVault) split into two parts:
+ *  - **committed** — actually-executed payments; this is what {@link getDailySpend} returns and what
+ *    `/verify` reconciles against the HCS audit log.
+ *  - **holds** — short-lived in-flight reservations placed atomically by the policy so two concurrent
+ *    payments can't both pass the cap check (the TOCTOU race). A hold becomes committed on execution,
+ *    or expires on its own if the payment never lands.
  */
 export interface CurbStore {
     isAllowed(agent: string, account: string): Promise<boolean>;
+    /** Committed (executed) spend in the rolling window. */
     getDailySpend(agent: string): Promise<number>;
+    /** Add to committed spend directly (e.g. seeding/migration). */
     incrDailySpend(agent: string, amount: number): Promise<void>;
+    /** Atomically reserve a hold if committed + holds + amount ≤ cap. Idempotent per `key`. */
+    tryReserveSpend(agent: string, key: string, amount: number, cap: number): Promise<boolean>;
+    /** Convert a hold into committed spend once the payment executes. */
+    commitSpend(agent: string, key: string, amount: number): Promise<void>;
     getApproval(requestId: string): Promise<ApprovalStatus | null>;
     setApproval(requestId: string, status: ApprovalStatus, meta?: ApprovalMeta): Promise<void>;
     consumeApproval(requestId: string): Promise<void>;
@@ -20,14 +32,18 @@ export interface CurbStore {
 /** Zero-dependency in-memory store — great for tests and single-instance deployments. */
 export declare class InMemoryCurbStore implements CurbStore {
     private allow;
-    private spend;
+    private committed;
+    private holds;
     private approvals;
-    private day;
     /** Seed an allowed counterparty. */
     allowAccount(agent: string, account: string): void;
+    private pruneCommitted;
+    private pruneHolds;
     isAllowed(agent: string, account: string): Promise<boolean>;
     getDailySpend(agent: string): Promise<number>;
     incrDailySpend(agent: string, amount: number): Promise<void>;
+    tryReserveSpend(agent: string, key: string, amount: number, cap: number): Promise<boolean>;
+    commitSpend(agent: string, key: string, amount: number): Promise<void>;
     getApproval(requestId: string): Promise<ApprovalStatus | null>;
     setApproval(requestId: string, status: ApprovalStatus): Promise<void>;
     consumeApproval(requestId: string): Promise<void>;

package/dist/store.js

@@ -1,22 +1,50 @@
+const WINDOW_MS = 24 * 60 * 60 * 1000;
+const HOLD_TTL_MS = 2 * 60 * 1000; // an in-flight payment resolves well within 2 min
 /** Zero-dependency in-memory store — great for tests and single-instance deployments. */
 export class InMemoryCurbStore {
     allow = new Set();
-    spend = new Map();
+    committed = new Map();
+    holds = new Map();
     approvals = new Map();
-    day = () => new Date().toISOString().slice(0, 10);
     /** Seed an allowed counterparty. */
     allowAccount(agent, account) {
         this.allow.add(`${agent}:${account}`);
     }
+    pruneCommitted(agent) {
+        const cutoff = Date.now() - WINDOW_MS;
+        const arr = (this.committed.get(agent) ?? []).filter((e) => e.ts > cutoff);
+        this.committed.set(agent, arr);
+        return arr;
+    }
+    pruneHolds(agent) {
+        const cutoff = Date.now() - HOLD_TTL_MS;
+        const arr = (this.holds.get(agent) ?? []).filter((e) => e.ts > cutoff);
+        this.holds.set(agent, arr);
+        return arr;
+    }
     async isAllowed(agent, account) {
         return this.allow.has(`${agent}:${account}`);
     }
     async getDailySpend(agent) {
-        return this.spend.get(`${agent}:${this.day()}`) ?? 0;
+        return this.pruneCommitted(agent).reduce((s, e) => s + e.amount, 0);
     }
     async incrDailySpend(agent, amount) {
-        const k = `${agent}:${this.day()}`;
-        this.spend.set(k, (this.spend.get(k) ?? 0) + amount);
+        this.pruneCommitted(agent).push({ ts: Date.now(), amount });
+    }
+    async tryReserveSpend(agent, key, amount, cap) {
+        const committed = this.pruneCommitted(agent).reduce((s, e) => s + e.amount, 0);
+        const holds = this.pruneHolds(agent);
+        if (holds.some((h) => h.key === key))
+            return true; // idempotent — same payment re-checked
+        const held = holds.reduce((s, h) => s + h.amount, 0);
+        if (committed + held + amount > cap)
+            return false;
+        holds.push({ ts: Date.now(), key, amount });
+        return true;
+    }
+    async commitSpend(agent, key, amount) {
+        this.pruneCommitted(agent).push({ ts: Date.now(), amount });
+        this.holds.set(agent, (this.holds.get(agent) ?? []).filter((h) => h.key !== key));
     }
     async getApproval(requestId) {
         return this.approvals.get(requestId) ?? null;

package/dist/tools.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The value-moving tools Curb governs:
+ *  - `transfer_hbar` (custodial: agent spends its own bounded account)
+ *  - `transfer_hbar_with_allowance` (non-custodial: agent spends the user's account, capped by an allowance)
+ */
+export declare const GOVERNED_TRANSFER_TOOLS: string[];

package/dist/tools.js

@@ -0,0 +1,10 @@
+import { coreAccountPluginToolNames } from '@hashgraph/hedera-agent-kit/plugins';
+/**
+ * The value-moving tools Curb governs:
+ *  - `transfer_hbar` (custodial: agent spends its own bounded account)
+ *  - `transfer_hbar_with_allowance` (non-custodial: agent spends the user's account, capped by an allowance)
+ */
+export const GOVERNED_TRANSFER_TOOLS = [
+    coreAccountPluginToolNames.TRANSFER_HBAR_TOOL,
+    coreAccountPluginToolNames.TRANSFER_HBAR_WITH_ALLOWANCE_TOOL,
+];

package/package.json

@@ -1,17 +1,21 @@
 {
   "name": "hedera-curb",
-  "version": "0.1.0",
+  "version": "0.4.1",
   "description": "Verifiable spend-control policies for Hedera AI agents — drop-in Hedera Agent Kit hooks for budgets, allowlists, human approval, and an immutable HCS audit trail.",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "hedera-curb": "./dist/cli.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": ["dist", "README.md"],
   "sideEffects": false,