arcbounty-agent-sdk 0.1.0 → 0.3.1

package/src/abi.ts

@@ -1,386 +0,0 @@
-// Canonical ABI for BountyAdapter V2 (humanOnly + dispute evidence).
-// Mirrors contracts/src/BountyAdapter.sol and frontend/lib/contracts.ts.
-
-const BOUNTY_META_TUPLE = {
-  name: "",
-  type: "tuple" as const,
-  components: [
-    { name: "jobId",                type: "uint256" },
-    { name: "poster",               type: "address" },
-    { name: "reward",               type: "uint256" },
-    { name: "deadline",             type: "uint256" },
-    { name: "ipfsDescHash",         type: "string"  },
-    { name: "category",             type: "string"  },
-    { name: "tags",                 type: "string[]" },
-    { name: "agentId",              type: "uint256" },
-    { name: "agentOnly",            type: "bool"    },
-    { name: "humanOnly",            type: "bool"    },
-    { name: "whitelistedProvider",  type: "address" },
-    { name: "assignedProvider",     type: "address" },
-    { name: "submittedResultHash",  type: "string"  },
-    { name: "submittedAt",          type: "uint256" },
-    { name: "isTaken",              type: "bool"    },
-    { name: "rejectedAt",           type: "uint256" },
-    { name: "rejectionReasonHash",  type: "string"  },
-    { name: "inDispute",            type: "bool"    },
-    { name: "resolved",             type: "bool"    },
-    { name: "disputeInitiator",     type: "address" },
-    { name: "disputeRaisedAt",      type: "uint256" },
-    { name: "disputeReasonHash",    type: "string"  },
-    { name: "disputeResponseHash",  type: "string"  },
-    { name: "disputeRulingHash",    type: "string"  },
-  ],
-} as const;
-
-export const BOUNTY_ADAPTER_ABI = [
-  // ── Write ──
-  {
-    name: "createBounty",
-    type: "function" as const,
-    stateMutability: "nonpayable" as const,
-    inputs: [{
-      name: "p",
-      type: "tuple",
-      components: [
-        { name: "provider",     type: "address"  },
-        { name: "reward",       type: "uint256"  },
-        { name: "deadline",     type: "uint256"  },
-        { name: "ipfsDescHash", type: "string"   },
-        { name: "category",     type: "string"   },
-        { name: "tags",         type: "string[]" },
-        { name: "agentOnly",    type: "bool"     },
-        { name: "humanOnly",    type: "bool"     },
-      ],
-    }],
-    outputs: [{ name: "jobId", type: "uint256" }],
-  },
-  {
-    name: "takeBounty",
-    type: "function" as const,
-    stateMutability: "nonpayable" as const,
-    inputs: [
-      { name: "jobId",   type: "uint256" },
-      { name: "agentId", type: "uint256" },
-    ],
-    outputs: [],
-  },
-  {
-    name: "submitWork",
-    type: "function" as const,
-    stateMutability: "nonpayable" as const,
-    inputs: [
-      { name: "jobId",          type: "uint256" },
-      { name: "ipfsResultHash", type: "string"  },
-    ],
-    outputs: [],
-  },
-  {
-    name: "approveBounty",
-    type: "function" as const,
-    stateMutability: "nonpayable" as const,
-    inputs: [
-      { name: "jobId",           type: "uint256" },
-      { name: "reputationScore", type: "uint8"   },
-    ],
-    outputs: [],
-  },
-  {
-    name: "autoApprove",
-    type: "function" as const,
-    stateMutability: "nonpayable" as const,
-    inputs: [{ name: "jobId", type: "uint256" }],
-    outputs: [],
-  },
-  {
-    name: "rejectBounty",
-    type: "function" as const,
-    stateMutability: "nonpayable" as const,
-    inputs: [
-      { name: "jobId",          type: "uint256" },
-      { name: "ipfsReasonHash", type: "string"  },
-    ],
-    outputs: [],
-  },
-  {
-    name: "challengeRejection",
-    type: "function" as const,
-    stateMutability: "nonpayable" as const,
-    inputs: [
-      { name: "jobId",          type: "uint256" },
-      { name: "ipfsReasonHash", type: "string"  },
-    ],
-    outputs: [],
-  },
-  {
-    name: "finalizeRejection",
-    type: "function" as const,
-    stateMutability: "nonpayable" as const,
-    inputs: [{ name: "jobId", type: "uint256" }],
-    outputs: [],
-  },
-  {
-    name: "cancelBounty",
-    type: "function" as const,
-    stateMutability: "nonpayable" as const,
-    inputs: [{ name: "jobId", type: "uint256" }],
-    outputs: [],
-  },
-  {
-    name: "expireBounty",
-    type: "function" as const,
-    stateMutability: "nonpayable" as const,
-    inputs: [{ name: "jobId", type: "uint256" }],
-    outputs: [],
-  },
-  {
-    name: "disputeBounty",
-    type: "function" as const,
-    stateMutability: "nonpayable" as const,
-    inputs: [
-      { name: "jobId",          type: "uint256" },
-      { name: "ipfsReasonHash", type: "string"  },
-    ],
-    outputs: [],
-  },
-  {
-    name: "respondToDispute",
-    type: "function" as const,
-    stateMutability: "nonpayable" as const,
-    inputs: [
-      { name: "jobId",            type: "uint256" },
-      { name: "ipfsResponseHash", type: "string"  },
-    ],
-    outputs: [],
-  },
-  {
-    name: "resolveDispute",
-    type: "function" as const,
-    stateMutability: "nonpayable" as const,
-    inputs: [
-      { name: "jobId",             type: "uint256" },
-      { name: "payProvider",       type: "bool"    },
-      { name: "ipfsRulingHash",    type: "string"  },
-      { name: "reputationPenalty", type: "uint8"   },
-    ],
-    outputs: [],
-  },
-  {
-    name: "claimDefaultRuling",
-    type: "function" as const,
-    stateMutability: "nonpayable" as const,
-    inputs: [{ name: "jobId", type: "uint256" }],
-    outputs: [],
-  },
-  // ── Read ──
-  {
-    name: "getOpenBounties",
-    type: "function" as const,
-    stateMutability: "view" as const,
-    inputs: [
-      { name: "category", type: "string"  },
-      { name: "offset",   type: "uint256" },
-      { name: "limit",    type: "uint256" },
-    ],
-    outputs: [{ name: "result", type: "uint256[]" }],
-  },
-  {
-    name: "getBountyMeta",
-    type: "function" as const,
-    stateMutability: "view" as const,
-    inputs: [{ name: "jobId", type: "uint256" }],
-    outputs: [BOUNTY_META_TUPLE],
-  },
-  {
-    name: "getMyPostedBounties",
-    type: "function" as const,
-    stateMutability: "view" as const,
-    inputs: [{ name: "poster", type: "address" }],
-    outputs: [{ name: "", type: "uint256[]" }],
-  },
-  {
-    name: "getMyAssignedBounties",
-    type: "function" as const,
-    stateMutability: "view" as const,
-    inputs: [{ name: "provider", type: "address" }],
-    outputs: [{ name: "", type: "uint256[]" }],
-  },
-  {
-    name: "getAgentBounties",
-    type: "function" as const,
-    stateMutability: "view" as const,
-    inputs: [{ name: "agentId", type: "uint256" }],
-    outputs: [{ name: "", type: "uint256[]" }],
-  },
-  {
-    name: "APPROVAL_TIMEOUT",
-    type: "function" as const,
-    stateMutability: "view" as const,
-    inputs: [], outputs: [{ name: "", type: "uint256" }],
-  },
-  {
-    name: "getAgentReputation",
-    type: "function" as const,
-    stateMutability: "view" as const,
-    inputs: [{ name: "agentId", type: "uint256" }],
-    outputs: [{
-      name: "",
-      type: "tuple",
-      components: [
-        { name: "averageScore",   type: "uint256" },
-        { name: "totalFeedbacks", type: "uint256" },
-        { name: "totalJobs",      type: "uint256" },
-      ],
-    }],
-  },
-  {
-    name: "totalBounties",
-    type: "function" as const,
-    stateMutability: "view" as const,
-    inputs: [],
-    outputs: [{ name: "", type: "uint256" }],
-  },
-  {
-    name: "arbitrator",
-    type: "function" as const,
-    stateMutability: "view" as const,
-    inputs: [],
-    outputs: [{ name: "", type: "address" }],
-  },
-  {
-    name: "DISPUTE_RESPONSE_WINDOW",
-    type: "function" as const,
-    stateMutability: "view" as const,
-    inputs: [],
-    outputs: [{ name: "", type: "uint256" }],
-  },
-  {
-    name: "REJECTION_CHALLENGE_WINDOW",
-    type: "function" as const,
-    stateMutability: "view" as const,
-    inputs: [],
-    outputs: [{ name: "", type: "uint256" }],
-  },
-  // ── Events ──
-  {
-    name: "BountyCreated",
-    type: "event" as const,
-    inputs: [
-      { name: "jobId",    type: "uint256", indexed: true  },
-      { name: "poster",   type: "address", indexed: true  },
-      { name: "reward",   type: "uint256", indexed: false },
-      { name: "category", type: "string",  indexed: false },
-      { name: "deadline", type: "uint256", indexed: false },
-    ],
-  },
-  {
-    name: "BountyTaken",
-    type: "event" as const,
-    inputs: [
-      { name: "jobId",    type: "uint256", indexed: true  },
-      { name: "provider", type: "address", indexed: true  },
-      { name: "agentId",  type: "uint256", indexed: false },
-    ],
-  },
-  {
-    name: "WorkSubmitted",
-    type: "event" as const,
-    inputs: [
-      { name: "jobId",          type: "uint256", indexed: true  },
-      { name: "provider",       type: "address", indexed: true  },
-      { name: "ipfsResultHash", type: "string",  indexed: false },
-    ],
-  },
-  {
-    name: "BountyCompleted",
-    type: "event" as const,
-    inputs: [
-      { name: "jobId",           type: "uint256", indexed: true  },
-      { name: "agentId",         type: "uint256", indexed: false },
-      { name: "reputationScore", type: "uint256", indexed: false },
-    ],
-  },
-  {
-    name: "DisputeRaised",
-    type: "event" as const,
-    inputs: [
-      { name: "jobId",      type: "uint256", indexed: true },
-      { name: "initiator",  type: "address", indexed: true },
-      { name: "reasonHash", type: "string",  indexed: false },
-    ],
-  },
-  {
-    name: "DisputeResponded",
-    type: "event" as const,
-    inputs: [
-      { name: "jobId",        type: "uint256", indexed: true },
-      { name: "responder",    type: "address", indexed: true },
-      { name: "responseHash", type: "string",  indexed: false },
-    ],
-  },
-  {
-    name: "DisputeResolved",
-    type: "event" as const,
-    inputs: [
-      { name: "jobId",         type: "uint256", indexed: true  },
-      { name: "payProvider",   type: "bool",    indexed: false },
-      { name: "rulingHash",    type: "string",  indexed: false },
-      { name: "defaultRuling", type: "bool",    indexed: false },
-    ],
-  },
-] as const;
-
-export const IDENTITY_REGISTRY_ABI = [
-  {
-    name: "register",
-    type: "function" as const,
-    stateMutability: "nonpayable" as const,
-    inputs: [{ name: "metadataURI", type: "string" }],
-    outputs: [{ name: "agentId", type: "uint256" }],
-  },
-  {
-    name: "ownerOf",
-    type: "function" as const,
-    stateMutability: "view" as const,
-    inputs: [{ name: "agentId", type: "uint256" }],
-    outputs: [{ name: "", type: "address" }],
-  },
-  {
-    name: "Transfer",
-    type: "event" as const,
-    inputs: [
-      { name: "from",    type: "address", indexed: true },
-      { name: "to",      type: "address", indexed: true },
-      { name: "tokenId", type: "uint256", indexed: true },
-    ],
-  },
-] as const;
-
-export const ERC20_ABI = [
-  {
-    name: "approve",
-    type: "function" as const,
-    stateMutability: "nonpayable" as const,
-    inputs: [
-      { name: "spender", type: "address" },
-      { name: "amount",  type: "uint256" },
-    ],
-    outputs: [{ name: "", type: "bool" }],
-  },
-  {
-    name: "allowance",
-    type: "function" as const,
-    stateMutability: "view" as const,
-    inputs: [
-      { name: "owner",   type: "address" },
-      { name: "spender", type: "address" },
-    ],
-    outputs: [{ name: "", type: "uint256" }],
-  },
-  {
-    name: "balanceOf",
-    type: "function" as const,
-    stateMutability: "view" as const,
-    inputs: [{ name: "account", type: "address" }],
-    outputs: [{ name: "", type: "uint256" }],
-  },
-] as const;

package/src/constants.ts

@@ -1,20 +0,0 @@
-import type { Address } from "viem";
-
-export const ARC_TESTNET_RPC = "https://rpc.testnet.arc.network";
-export const ARC_TESTNET_CHAIN_ID = 5_042_002;
-
-export const CONTRACTS = {
-  AGENTIC_COMMERCE:    "0x0747EEf0706327138c69792bF28Cd525089e4583" as Address,
-  IDENTITY_REGISTRY:   "0x8004A818BFB912233c491871b3d84c89A494BD9e" as Address,
-  REPUTATION_REGISTRY: "0x8004B663056A597Dffe9eCcC1965A193B7388713" as Address,
-  USDC:                "0x3600000000000000000000000000000000000000" as Address,
-} as const;
-
-export const USDC_DECIMALS = 6;
-export const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000" as Address;
-
-export const IPFS_GATEWAYS = [
-  "https://gateway.pinata.cloud/ipfs/",
-  "https://ipfs.io/ipfs/",
-  "https://cloudflare-ipfs.com/ipfs/",
-];

package/src/index.ts

@@ -1,21 +0,0 @@
-export { ArcBountyAgent } from "./ArcBountyAgent.js";
-export type {
-  ArcBountyAgentConfig,
-  BountyMeta,
-  ReputationScore,
-  OpenBountiesFilter,
-  CreateBountyOptions,
-  SubmitWorkOptions,
-  DisputeEvidenceOptions,
-  AgentInfo,
-  TxResult,
-} from "./types.js";
-export { CONTRACTS, ARC_TESTNET_RPC, ARC_TESTNET_CHAIN_ID } from "./constants.js";
-export { BOUNTY_ADAPTER_ABI, IDENTITY_REGISTRY_ABI, ERC20_ABI } from "./abi.js";
-export { pinText, fetchIpfsText, fetchIpfsJson, isPinningConfigured } from "./ipfs.js";
-export {
-  pinAgentMetadata,
-  validateAgentMetadata,
-  type AgentMetadata,
-  type ArcBountySection,
-} from "./metadata.js";

package/src/ipfs.ts

@@ -1,80 +0,0 @@
-import { IPFS_GATEWAYS } from "./constants.js";
-
-function cidFromUri(uriOrCid: string): string {
-  return uriOrCid.replace(/^ipfs:\/\//, "");
-}
-
-export async function fetchIpfsText(uriOrCid: string): Promise<string> {
-  const cid = cidFromUri(uriOrCid);
-  for (const gateway of IPFS_GATEWAYS) {
-    try {
-      const res = await fetch(`${gateway}${cid}`);
-      if (res.ok) return res.text();
-    } catch {
-      // try next gateway
-    }
-  }
-  throw new Error(`Failed to fetch IPFS content: ${uriOrCid}`);
-}
-
-export async function fetchIpfsJson<T = unknown>(uriOrCid: string): Promise<T> {
-  const text = await fetchIpfsText(uriOrCid);
-  return JSON.parse(text) as T;
-}
-
-/** True iff Pinata creds are reachable in env. Cheap to call repeatedly. */
-export function isPinningConfigured(): boolean {
-  return Boolean(process.env["PINATA_JWT"] || (process.env["PINATA_API_KEY"] && process.env["PINATA_SECRET"]));
-}
-
-/**
- * Pin text content to IPFS via Pinata's v2 `pinFileToIPFS` API. Prefers a JWT
- * (PINATA_JWT, scoped for `pinFileToIPFS`, sent as Bearer), and falls back to a
- * key/secret pair (PINATA_API_KEY + PINATA_SECRET). Returns an `ipfs://<cid>` URI.
- *
- * Throws immediately (not deep inside an autonomous loop) if creds are missing.
- */
-export async function pinText(content: string, filename = "result.md"): Promise<string> {
-  const jwt       = process.env["PINATA_JWT"];
-  const apiKey    = process.env["PINATA_API_KEY"];
-  const apiSecret = process.env["PINATA_SECRET"];
-
-  const blob = new Blob([content], { type: "text/plain" });
-
-  if (jwt) {
-    const form = new FormData();
-    form.append("file", blob, filename);
-    const res = await fetch("https://api.pinata.cloud/pinning/pinFileToIPFS", {
-      method: "POST",
-      headers: { Authorization: `Bearer ${jwt}` },
-      body: form,
-    });
-    if (!res.ok) {
-      const text = await res.text().catch(() => "");
-      throw new Error(`Pinata v2 error ${res.status}: ${text}`);
-    }
-    const data = await res.json() as { IpfsHash: string };
-    return `ipfs://${data.IpfsHash}`;
-  }
-
-  if (apiKey && apiSecret) {
-    const form = new FormData();
-    form.append("file", blob, filename);
-    const res = await fetch("https://api.pinata.cloud/pinning/pinFileToIPFS", {
-      method: "POST",
-      headers: {
-        pinata_api_key:        apiKey,
-        pinata_secret_api_key: apiSecret,
-      },
-      body: form,
-    });
-    if (!res.ok) {
-      const text = await res.text().catch(() => "");
-      throw new Error(`Pinata v1 error ${res.status}: ${text}`);
-    }
-    const data = await res.json() as { IpfsHash: string };
-    return `ipfs://${data.IpfsHash}`;
-  }
-
-  throw new Error("Set PINATA_JWT (preferred) or PINATA_API_KEY + PINATA_SECRET to pin to IPFS");
-}

package/src/metadata.ts

@@ -1,69 +0,0 @@
-import { pinText } from "./ipfs.js";
-
-/**
- * ERC-8004 agent metadata (TZ §4.3 + §12.3).
- *
- * IdentityRegistry.register() stores a URI; everyone reading it expects the
- * referenced JSON to follow this shape. Persistence matters — `data:` URIs
- * break the moment a verifier wants to fetch the manifest after registration,
- * so we always pin to IPFS.
- */
-export type ArcBountySection = {
-  /** Min reputation a poster requires before this agent takes their bounty. */
-  min_reputation?: number;
-  preferred_categories?: ReadonlyArray<"dev" | "design" | "content" | "data" | "other">;
-  min_reward_usdc?: number;
-  max_reward_usdc?: number;
-};
-
-export type AgentMetadata = {
-  name: string;
-  description: string;
-  agent_type?: string;
-  capabilities?: readonly string[];
-  version?: string;
-  contact?: string;
-
-  // ArcBounty-specific block — required for agents that want to be discoverable
-  // by the autonomous selection in subscribeToNewBounties / runOnce.
-  arcbounty?: ArcBountySection;
-};
-
-/**
- * Validate a metadata blob before pinning. Strict by default — we'd rather
- * fail loudly on init than silently push a broken manifest to IPFS.
- */
-export function validateAgentMetadata(m: unknown): asserts m is AgentMetadata {
-  if (typeof m !== "object" || m === null) throw new Error("metadata must be an object");
-  const o = m as Record<string, unknown>;
-  if (typeof o.name !== "string" || o.name.length === 0)
-    throw new Error("metadata.name must be a non-empty string");
-  if (typeof o.description !== "string")
-    throw new Error("metadata.description must be a string");
-  if (o.capabilities !== undefined && !Array.isArray(o.capabilities))
-    throw new Error("metadata.capabilities must be an array of strings");
-  if (o.arcbounty !== undefined) {
-    const a = o.arcbounty as Record<string, unknown>;
-    if (a.min_reputation !== undefined && (typeof a.min_reputation !== "number" || a.min_reputation < 0 || a.min_reputation > 100))
-      throw new Error("metadata.arcbounty.min_reputation must be a number in [0, 100]");
-    if (a.preferred_categories !== undefined) {
-      if (!Array.isArray(a.preferred_categories)) throw new Error("preferred_categories must be an array");
-      for (const c of a.preferred_categories as unknown[]) {
-        if (typeof c !== "string" || !["dev","design","content","data","other"].includes(c))
-          throw new Error(`preferred_categories: invalid category ${String(c)}`);
-      }
-    }
-    for (const k of ["min_reward_usdc","max_reward_usdc"] as const) {
-      const v = a[k];
-      if (v !== undefined && (typeof v !== "number" || v < 0)) {
-        throw new Error(`metadata.arcbounty.${k} must be a non-negative number`);
-      }
-    }
-  }
-}
-
-/** Pin a validated metadata blob to IPFS and return the `ipfs://<cid>` URI. */
-export async function pinAgentMetadata(meta: AgentMetadata): Promise<string> {
-  validateAgentMetadata(meta);
-  return pinText(JSON.stringify(meta, null, 2), "agent.json");
-}

package/src/types.ts

@@ -1,105 +0,0 @@
-import type { Address, Hash } from "viem";
-
-// ─── Config ──────────────────────────────────────────────────────────────────
-
-export type ArcBountyAgentConfig = {
-  /** Private key of the agent wallet (0x-prefixed hex) */
-  privateKey: Hash;
-  /** Arc RPC URL */
-  rpcUrl?: string;
-  /** IPFS metadata URI for agent registration (ipfs://Qm...) */
-  metadataURI?: string;
-  /** BountyAdapter contract address (overrides default) */
-  bountyAdapterAddress?: Address;
-};
-
-// ─── On-chain structs (mirror BountyAdapter.sol BountyMeta) ──────────────────
-
-export type BountyMeta = {
-  jobId:               bigint;
-  poster:              Address;
-  reward:              bigint;
-  deadline:            bigint;
-  ipfsDescHash:        string;
-  category:            string;
-  tags:                readonly string[];
-  agentId:             bigint;
-  agentOnly:           boolean;
-  humanOnly:           boolean;
-  whitelistedProvider: Address;
-  assignedProvider:    Address;
-  submittedResultHash: string;
-  submittedAt:         bigint;
-  isTaken:             boolean;
-  // Pending-rejection state
-  rejectedAt:          bigint;
-  rejectionReasonHash: string;
-  // Dispute state
-  inDispute:           boolean;
-  resolved:            boolean;
-  disputeInitiator:    Address;
-  disputeRaisedAt:     bigint;
-  disputeReasonHash:   string;
-  disputeResponseHash: string;
-  disputeRulingHash:   string;
-};
-
-export type ReputationScore = {
-  averageScore:   bigint;
-  totalFeedbacks: bigint;
-  totalJobs:      bigint;
-};
-
-// ─── SDK-level types ──────────────────────────────────────────────────────────
-
-export type OpenBountiesFilter = {
-  category?:  string;
-  agentOnly?: boolean;
-  humanOnly?: boolean;
-  maxReward?: number;        // in USDC dollars
-  minReward?: number;
-  offset?:    number;
-  limit?:     number;
-};
-
-export type CreateBountyOptions = {
-  /** Reward in USDC dollars (will be scaled by 1e6) */
-  rewardUsdc: number;
-  /** Unix seconds OR a Date OR seconds-from-now (if < 1e9 treated as duration) */
-  deadline: number | Date;
-  /** Pre-pinned IPFS CID for the description (ipfs://... or bafy...) */
-  descriptionCid?: string;
-  /** Or raw markdown — will be pinned for you */
-  descriptionText?: string;
-  category: "dev" | "design" | "content" | "data" | "other";
-  tags?: string[];
-  /** Optional whitelisted provider — only this address may take */
-  provider?: Address;
-  agentOnly?: boolean;
-  humanOnly?: boolean;
-};
-
-export type SubmitWorkOptions = {
-  /** Raw text/markdown result — will be pinned to IPFS */
-  text?: string;
-  /** Pre-computed IPFS CID (ipfs://...) — skips pinning */
-  cid?: string;
-};
-
-export type DisputeEvidenceOptions = {
-  /** Raw evidence text — will be pinned to IPFS */
-  text?: string;
-  /** Pre-computed IPFS CID — skips pinning */
-  cid?: string;
-};
-
-export type AgentInfo = {
-  agentId:     bigint;
-  address:     Address;
-  metadataURI: string;
-  reputation:  ReputationScore;
-};
-
-export type TxResult = {
-  hash: Hash;
-};

package/tsconfig.json

@@ -1,13 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "lib": ["ES2020", "DOM"],
-    "strict": true,
-    "declaration": true,
-    "skipLibCheck": true,
-    "noEmit": true
-  },
-  "include": ["src"]
-}