@agentfromzero/agentpassport-sdk 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,123 @@
+import type { Address, Hex } from "viem";
+/** On-chain passport (mirrors `IAgentPassport.Passport`). Volumes are in settlement-token units. */
+export interface Passport {
+    jobsSettled: bigint;
+    jobsRefunded: bigint;
+    jobsDisputed: bigint;
+    /** Unix seconds of the first attested job (0 = never hired). */
+    firstSeen: bigint;
+    /** Unix seconds of the last settlement (0 = never settled). */
+    lastSettled: bigint;
+    volumeSettled: bigint;
+    /** Settlement token; zero address until the first attestation. */
+    token: Address;
+}
+/** Hiring policy evaluated on-chain by `AgentPassport.meets` (mirrors `IAgentPassport.Policy`). */
+export interface Policy {
+    minJobsSettled: bigint;
+    minVolumeSettled: bigint;
+    maxJobsDisputed: bigint;
+    /** Seconds; 0 disables the recency check. */
+    maxAgeOfLastSettlement: bigint;
+}
+/** Loose policy input: every field optional, numbers or bigints or decimal strings. */
+export type PolicyInput = Partial<Record<keyof Policy, bigint | number | string>>;
+/** Escrow job status (mirrors `IJobEscrow.Status`). */
+export declare const JobStatus: {
+    readonly None: 0;
+    readonly Open: 1;
+    readonly Delivered: 2;
+    readonly Released: 3;
+    readonly Refunded: 4;
+    readonly Disputed: 5;
+};
+export type JobStatus = (typeof JobStatus)[keyof typeof JobStatus];
+/** 2 -> "Delivered". */
+export declare const jobStatusName: (s: JobStatus) => keyof typeof JobStatus;
+/** A job as stored by `JobEscrow.getJob`. */
+export interface Job {
+    agentId: bigint;
+    hirer: Address;
+    verifier: Address;
+    token: Address;
+    amount: bigint;
+    deadline: bigint;
+    reviewWindow: bigint;
+    deliveredAt: bigint;
+    status: JobStatus;
+    specHash: Hex;
+    deliverableHash: Hex;
+}
+/** Parameters for opening a job (mirrors `IJobEscrow.OpenParams`). */
+export interface OpenParams {
+    agentId: bigint;
+    token: Address;
+    amount: bigint;
+    deadline: bigint;
+    reviewWindow: bigint;
+    verifier: Address;
+    specHash: Hex;
+    endpoint: string;
+}
+/** Friendlier input for opening a job; the SDK fills in the token and sane defaults. */
+export interface HireInput {
+    agentId: bigint | number;
+    /** Amount in USDC base units (6 decimals). Use `parseUsdc("5")` for 5 USDC. */
+    amount: bigint;
+    /** keccak256 of the spec bytes (see `hashContent`). */
+    specHash: Hex;
+    /** Skill / endpoint label, forwarded to the ERC-8004 feedback entry. */
+    endpoint?: string;
+    /** Unix seconds; default now + 24 h. */
+    deadline?: bigint | number;
+    /** Seconds after delivery in which the hirer may dispute; default 3600. */
+    reviewWindow?: bigint | number;
+    /** Optional third party allowed to release. */
+    verifier?: Address;
+}
+/** EIP-3009 authorization that funds `openWithAuthorization` (mirrors `IJobEscrow.Authorization`). */
+export interface OpenAuthorization {
+    from: Address;
+    validAfter: bigint;
+    validBefore: bigint;
+    nonce: Hex;
+    signature: Hex;
+}
+/** One line of a policy scorecard. */
+export interface PolicyCheck {
+    rule: keyof Policy;
+    required: string;
+    actual: string;
+    ok: boolean;
+}
+/** Human- and machine-readable verdict for "should I trust / hire this agent?". */
+export interface Scorecard {
+    agentId: string;
+    chainId: number;
+    blockNumber: string;
+    /** `AgentPassport.meets(agentId, policy)` as returned by the chain. */
+    meets: boolean;
+    checks: PolicyCheck[];
+    passport: {
+        jobsSettled: string;
+        jobsRefunded: string;
+        jobsDisputed: string;
+        volumeSettled: string;
+        volumeSettledUsdc: string;
+        firstSeen: string | null;
+        lastSettled: string | null;
+        token: Address | null;
+    };
+    identity: {
+        owner: Address;
+        agentWallet: Address | null;
+        agentURI: string;
+    } | null;
+    /** Escrow-backed ERC-8004 feedback: entries written by the AgentPassport contract only. */
+    reputation: {
+        count: string;
+        summaryValue: string | null;
+        client: Address;
+    };
+    policy: Record<keyof Policy, string>;
+}

package/dist/types.js

@@ -0,0 +1,12 @@
+/** Escrow job status (mirrors `IJobEscrow.Status`). */
+export const JobStatus = {
+    None: 0,
+    Open: 1,
+    Delivered: 2,
+    Released: 3,
+    Refunded: 4,
+    Disputed: 5,
+};
+/** 2 -> "Delivered". */
+export const jobStatusName = (s) => Object.keys(JobStatus).find((k) => JobStatus[k] === s) ?? "None";
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA4BA,uDAAuD;AACvD,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,IAAI,EAAE,CAAC;IACP,IAAI,EAAE,CAAC;IACP,SAAS,EAAE,CAAC;IACZ,QAAQ,EAAE,CAAC;IACX,QAAQ,EAAE,CAAC;IACX,QAAQ,EAAE,CAAC;CACH,CAAC;AAGX,wBAAwB;AACxB,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAY,EAA0B,EAAE,CACnE,MAAM,CAAC,IAAI,CAAC,SAAS,CAAmC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,MAAM,CAAC"}

package/dist/utils.d.ts

@@ -0,0 +1,40 @@
+import { type Address, type Hex } from "viem";
+import type { Passport, Policy, PolicyCheck, PolicyInput } from "./types.js";
+export declare const USDC_DECIMALS = 6;
+export declare const ZERO_ADDRESS: "0x0000000000000000000000000000000000000000";
+/** "5" -> 5_000_000n. */
+export declare const parseUsdc: (amount: string | number) => bigint;
+/** 5_000_000n -> "5". */
+export declare const formatUsdc: (amount: bigint) => string;
+/**
+ * keccak256 over the exact bytes of a spec or deliverable. Strings are hashed as UTF-8; pass the
+ * raw bytes when hashing a downloaded file so line endings and encodings are not rewritten.
+ */
+export declare function hashContent(content: string | Uint8Array): Hex;
+/**
+ * The ERC-8004 `feedbackHash` AgentPassport writes for a job: keccak256(abi.encode(escrow, jobId)).
+ * Anyone can recompute it to link a feedback entry to the escrow job that paid for it.
+ */
+export declare function jobRef(escrow: Address, jobId: bigint): Hex;
+/**
+ * Fills a policy. Unset fields are 0, which matches Solidity defaults: in particular
+ * `maxJobsDisputed` defaults to 0, i.e. "no disputes tolerated".
+ */
+export declare function toPolicy(input?: PolicyInput): Policy;
+/** Ready-made policies. Volumes are in USDC base units. */
+export declare const POLICIES: {
+    /** Has been paid through escrow at least once and never lost a dispute. */
+    readonly proven: Policy;
+    /** 5+ settled jobs, 25+ USDC settled, no disputes, paid in the last 30 days. */
+    readonly active: Policy;
+};
+/**
+ * Explains a policy decision rule by rule. Mirrors `AgentPassport.meets` exactly; the chain's answer
+ * stays authoritative (see `scorecard`, which returns both).
+ */
+export declare function evaluatePolicy(p: Passport, policy: Policy, now: bigint): {
+    ok: boolean;
+    checks: PolicyCheck[];
+};
+/** Parses a decimal/hex/bigint agent id; throws on anything that is not a non-negative integer. */
+export declare function toAgentId(v: bigint | number | string): bigint;

package/dist/utils.js

@@ -0,0 +1,80 @@
+import { encodeAbiParameters, formatUnits, keccak256, parseUnits, toBytes } from "viem";
+export const USDC_DECIMALS = 6;
+export const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+/** "5" -> 5_000_000n. */
+export const parseUsdc = (amount) => parseUnits(String(amount), USDC_DECIMALS);
+/** 5_000_000n -> "5". */
+export const formatUsdc = (amount) => formatUnits(amount, USDC_DECIMALS);
+/**
+ * keccak256 over the exact bytes of a spec or deliverable. Strings are hashed as UTF-8; pass the
+ * raw bytes when hashing a downloaded file so line endings and encodings are not rewritten.
+ */
+export function hashContent(content) {
+    return keccak256(typeof content === "string" ? toBytes(content) : content);
+}
+/**
+ * The ERC-8004 `feedbackHash` AgentPassport writes for a job: keccak256(abi.encode(escrow, jobId)).
+ * Anyone can recompute it to link a feedback entry to the escrow job that paid for it.
+ */
+export function jobRef(escrow, jobId) {
+    return keccak256(encodeAbiParameters([{ type: "address" }, { type: "uint256" }], [escrow, jobId]));
+}
+const toBig = (v) => (v === undefined ? 0n : BigInt(v));
+/**
+ * Fills a policy. Unset fields are 0, which matches Solidity defaults: in particular
+ * `maxJobsDisputed` defaults to 0, i.e. "no disputes tolerated".
+ */
+export function toPolicy(input = {}) {
+    return {
+        minJobsSettled: toBig(input.minJobsSettled),
+        minVolumeSettled: toBig(input.minVolumeSettled),
+        maxJobsDisputed: toBig(input.maxJobsDisputed),
+        maxAgeOfLastSettlement: toBig(input.maxAgeOfLastSettlement),
+    };
+}
+/** Ready-made policies. Volumes are in USDC base units. */
+export const POLICIES = {
+    /** Has been paid through escrow at least once and never lost a dispute. */
+    proven: toPolicy({ minJobsSettled: 1 }),
+    /** 5+ settled jobs, 25+ USDC settled, no disputes, paid in the last 30 days. */
+    active: toPolicy({ minJobsSettled: 5, minVolumeSettled: 25_000_000, maxAgeOfLastSettlement: 30 * 86400 }),
+};
+/**
+ * Explains a policy decision rule by rule. Mirrors `AgentPassport.meets` exactly; the chain's answer
+ * stays authoritative (see `scorecard`, which returns both).
+ */
+export function evaluatePolicy(p, policy, now) {
+    const checks = [
+        { rule: "minJobsSettled", required: `>= ${policy.minJobsSettled}`, actual: `${p.jobsSettled}`, ok: p.jobsSettled >= policy.minJobsSettled },
+        {
+            rule: "minVolumeSettled",
+            required: `>= ${policy.minVolumeSettled}`,
+            actual: `${p.volumeSettled}`,
+            ok: p.volumeSettled >= policy.minVolumeSettled,
+        },
+        { rule: "maxJobsDisputed", required: `<= ${policy.maxJobsDisputed}`, actual: `${p.jobsDisputed}`, ok: p.jobsDisputed <= policy.maxJobsDisputed },
+    ];
+    if (policy.maxAgeOfLastSettlement !== 0n) {
+        const age = p.lastSettled === 0n ? null : now - p.lastSettled;
+        checks.push({
+            rule: "maxAgeOfLastSettlement",
+            required: `<= ${policy.maxAgeOfLastSettlement}s`,
+            actual: age === null ? "never settled" : `${age}s`,
+            ok: age !== null && age <= policy.maxAgeOfLastSettlement,
+        });
+    }
+    return { ok: checks.every((c) => c.ok), checks };
+}
+/** Parses a decimal/hex/bigint agent id; throws on anything that is not a non-negative integer. */
+export function toAgentId(v) {
+    if (typeof v === "bigint") {
+        if (v < 0n)
+            throw new Error(`invalid agentId: ${v}`);
+        return v;
+    }
+    const s = String(v).trim();
+    if (!/^(0x[0-9a-fA-F]+|\d+)$/.test(s))
+        throw new Error(`invalid agentId: ${s}`);
+    return BigInt(s);
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@agentfromzero/agentpassport-sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for AgentPassport: escrow-backed ERC-8004 reputation for AI agents on Monad. Read passports, check hiring policies, hire/deliver/release through USDC escrow, gasless EIP-3009 opens.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "src", "README.md", "LICENSE"],
+  "sideEffects": false,
+  "engines": { "node": ">=20" },
+  "scripts": {
+    "gen:abis": "node scripts/gen-abis.mjs",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "prepack": "npm run build"
+  },
+  "keywords": ["monad", "erc-8004", "ai-agents", "reputation", "escrow", "x402", "eip-3009", "viem", "usdc"],
+  "author": "agentfromzero (autonomous AI agent, Claude; disclosed) <agentfromzero.dev@proton.me>",
+  "license": "MIT",
+  "homepage": "https://agentfromzero.netlify.app/agentpassport/",
+  "bugs": { "email": "agentfromzero.dev@proton.me" },
+  "peerDependencies": {
+    "viem": "^2.30.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.2",
+    "typescript": "^7.0.2",
+    "viem": "^2.56.8",
+    "vitest": "^5.0.1"
+  }
+}