Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

8.6 KB
Raw Blame
import { beforeEach, describe, expect, it } from "vitest";
import { SpendGuard } from "../src/core/SpendGuard.js";
const AGENT = "agt_test";
function fixedClock(start = 17e11) {
  let t = start;
  return {
    now: () => t,
    advance: (ms) => {
      t += ms;
    },
    set: (ms) => {
      t = ms;
    }
  };
}
function makeTx(overrides = {}) {
  return { agentId: AGENT, valueUsd: 100, ...overrides };
}
function makeGuard(config, clock = fixedClock()) {
  return { guard: new SpendGuard(config, { now: clock.now }), clock };
}
describe("SpendGuard", () => {
  describe("per-tx maximum", () => {
    let guard;
    beforeEach(() => {
      guard = new SpendGuard({ perTxMaxUsd: 1e3 });
    });
    it("allows a transaction at the per-tx limit", () => {
      const result = guard.check(makeTx({ valueUsd: 1e3 }));
      expect(result.allowed).toBe(true);
    });
    it("blocks a transaction over the per-tx max with a deterministic reason", () => {
      const result = guard.check(makeTx({ valueUsd: 1500 }));
      expect(result.allowed).toBe(false);
      expect(result.code).toBe("CAP_PER_TX");
      expect(result.reason).toBe(
        "Transaction $1,500 exceeds per-transaction maximum of $1,000"
      );
    });
    it("is deterministic - identical inputs yield identical results", () => {
      const a = guard.check(makeTx({ valueUsd: 2e3 }));
      const b = guard.check(makeTx({ valueUsd: 2e3 }));
      expect(a).toEqual(b);
    });
  });
  describe("rolling spend cap", () => {
    it("blocks the next tx once cumulative spend crosses the rolling cap", () => {
      const { guard } = makeGuard({ rollingMaxUsd: 1e3 });
      guard.recordSpend(AGENT, 500);
      guard.recordSpend(AGENT, 300);
      expect(guard.check(makeTx({ valueUsd: 150 })).allowed).toBe(true);
      const blocked = guard.check(makeTx({ valueUsd: 300 }));
      expect(blocked.allowed).toBe(false);
      expect(blocked.code).toBe("CAP_ROLLING");
      expect(blocked.remainingRollingUsd).toBe(0);
    });
    it("slides the window - old spend outside the window no longer counts", () => {
      const { guard, clock } = makeGuard({ rollingMaxUsd: 1e3, rollingWindowMs: 6e4 });
      guard.recordSpend(AGENT, 900);
      expect(guard.check(makeTx({ valueUsd: 200 })).allowed).toBe(false);
      clock.advance(60001);
      expect(guard.check(makeTx({ valueUsd: 200 })).allowed).toBe(true);
    });
    it("enforces the daily (rolling 24h) cap independently", () => {
      const { guard } = makeGuard({ dailyMaxUsd: 5e3 });
      guard.recordSpend(AGENT, 4900);
      const blocked = guard.check(makeTx({ valueUsd: 200 }));
      expect(blocked.allowed).toBe(false);
      expect(blocked.code).toBe("CAP_DAILY");
    });
    it("tracks spend per agent, not globally", () => {
      const { guard } = makeGuard({ rollingMaxUsd: 1e3 });
      guard.recordSpend("agt_a", 900);
      expect(guard.check(makeTx({ agentId: "agt_b", valueUsd: 900 })).allowed).toBe(true);
      expect(guard.check(makeTx({ agentId: "agt_a", valueUsd: 900 })).allowed).toBe(false);
    });
  });
  describe("reserve floor", () => {
    let guard;
    beforeEach(() => {
      guard = new SpendGuard({ reserveFloorUsd: 1e3 });
    });
    it("allows a tx that leaves the balance at the floor", () => {
      const result = guard.check(makeTx({ balanceUsd: 1500, valueUsd: 500 }));
      expect(result.allowed).toBe(true);
    });
    it("blocks a tx that would drain below the reserve floor", () => {
      const result = guard.check(makeTx({ balanceUsd: 1200, valueUsd: 500 }));
      expect(result.allowed).toBe(false);
      expect(result.code).toBe("RESERVE_FLOOR");
    });
    it("cannot enforce the floor without a balance (passes through)", () => {
      const result = guard.check(makeTx({ valueUsd: 5e3 }));
      expect(result.allowed).toBe(true);
    });
  });
  describe("token/target firewall", () => {
    it("blocks a destination on the deny list", () => {
      const guard = new SpendGuard({
        firewall: { denyDestinations: ["0xBADACTOR"] }
      });
      const result = guard.check(makeTx({ destination: "0xbadactor", valueUsd: 10 }));
      expect(result.allowed).toBe(false);
      expect(result.code).toBe("FIREWALL_DENY_DEST");
    });
    it("blocks a token on the deny list (case-insensitive)", () => {
      const guard = new SpendGuard({ firewall: { denyTokens: ["scam"] } });
      const result = guard.check(makeTx({ token: "SCAM", valueUsd: 10 }));
      expect(result.allowed).toBe(false);
      expect(result.code).toBe("FIREWALL_DENY_TOKEN");
    });
    it("blocks an off-allowlist destination in strict mode", () => {
      const guard = new SpendGuard({
        firewall: { allowDestinations: ["0xsafe"], strictMode: true }
      });
      expect(guard.check(makeTx({ destination: "0xSAFE", valueUsd: 10 })).allowed).toBe(true);
      const blocked = guard.check(makeTx({ destination: "0xunknown", valueUsd: 10 }));
      expect(blocked.allowed).toBe(false);
      expect(blocked.code).toBe("FIREWALL_NOT_ALLOWED");
    });
    it("blocks an off-allowlist token in strict mode", () => {
      const guard = new SpendGuard({
        firewall: { allowTokens: ["USDC"], strictMode: true }
      });
      expect(guard.check(makeTx({ token: "usdc", valueUsd: 10 })).allowed).toBe(true);
      expect(guard.check(makeTx({ token: "PEPE", valueUsd: 10 })).allowed).toBe(false);
    });
    it("does not enforce the allowlist when strict mode is off", () => {
      const guard = new SpendGuard({
        firewall: { allowTokens: ["USDC"], strictMode: false }
      });
      expect(guard.check(makeTx({ token: "PEPE", valueUsd: 10 })).allowed).toBe(true);
    });
    it("deny takes precedence over allow", () => {
      const guard = new SpendGuard({
        firewall: { allowTokens: ["USDC"], denyTokens: ["USDC"], strictMode: true }
      });
      const result = guard.check(makeTx({ token: "USDC", valueUsd: 10 }));
      expect(result.allowed).toBe(false);
      expect(result.code).toBe("FIREWALL_DENY_TOKEN");
    });
  });
  describe("custody reconciliation", () => {
    it("flags a breach and latches the agent when on-chain outflow exceeds the ledger", () => {
      const { guard } = makeGuard({ perTxMaxUsd: 1e4 });
      expect(guard.check(makeTx({ valueUsd: 100 })).allowed).toBe(true);
      const recon = guard.reconcile(AGENT, {
        ledgerRecordedUsd: 5e3,
        onChainOutflowUsd: 7500
      });
      expect(recon.breach).toBe(true);
      expect(recon.unrecordedUsd).toBe(2500);
      expect(guard.isTripped(AGENT)).toBe(true);
      const blocked = guard.check(makeTx({ valueUsd: 100 }));
      expect(blocked.allowed).toBe(false);
      expect(blocked.code).toBe("BREACH");
    });
    it("does not flag a breach when the chain matches the ledger within tolerance", () => {
      const { guard } = makeGuard({ breachTolerance: 0.01 });
      const recon = guard.reconcile(AGENT, {
        ledgerRecordedUsd: 5e3,
        onChainOutflowUsd: 5040
        // within 1% tolerance
      });
      expect(recon.breach).toBe(false);
      expect(guard.isTripped(AGENT)).toBe(false);
    });
    it("reconciles via an injected ledger reader", async () => {
      const { guard } = makeGuard({});
      const recon = await guard.reconcileFromLedger(
        AGENT,
        async () => ({ ledgerRecordedUsd: 1e3, onChainOutflowUsd: 3e3 }),
        "user_1"
      );
      expect(recon.breach).toBe(true);
      expect(guard.isTripped(AGENT)).toBe(true);
    });
    it("reset() clears the breach latch", () => {
      const { guard } = makeGuard({});
      guard.reconcile(AGENT, { ledgerRecordedUsd: 0, onChainOutflowUsd: 500 });
      expect(guard.isTripped(AGENT)).toBe(true);
      guard.reset(AGENT);
      expect(guard.isTripped(AGENT)).toBe(false);
      expect(guard.check(makeTx({ valueUsd: 100 })).allowed).toBe(true);
    });
  });
  describe("envelope composition", () => {
    it("allows a tx that satisfies every configured limit", () => {
      const { guard } = makeGuard({
        dailyMaxUsd: 1e4,
        firewall: { allowTokens: ["USDC"], strictMode: true },
        perTxMaxUsd: 1e3,
        reserveFloorUsd: 500,
        rollingMaxUsd: 5e3
      });
      const result = guard.check(
        makeTx({ balanceUsd: 5e3, token: "USDC", valueUsd: 800 })
      );
      expect(result.allowed).toBe(true);
      expect(result.remainingRollingUsd).toBe(4200);
      expect(result.remainingDailyUsd).toBe(9200);
    });
    it("seeds the rolling window from a persisted ledger total", () => {
      const { guard } = makeGuard({ rollingMaxUsd: 1e3 });
      guard.syncSpendFromLedger(AGENT, 950);
      expect(guard.check(makeTx({ valueUsd: 100 })).allowed).toBe(false);
      expect(guard.windowSpend(AGENT, 24 * 60 * 60 * 1e3)).toBe(950);
    });
  });
});