arcbounty-agent-sdk 0.1.0 → 0.3.1

package/dist/index.d.ts

@@ -1,8 +1,19 @@
 import { Address, Hash } from 'viem';
 
-type ArcBountyAgentConfig = {
-    /** Private key of the agent wallet (0x-prefixed hex) */
-    privateKey: Hash;
+type CircleWalletConfig = {
+    /** Circle API key (Circle Console → Testnet/Mainnet → API Keys → API Key, Standard). */
+    apiKey: string;
+    /** Registered entity secret — see docs/circle-wallet.md. Controls every wallet under this API key. */
+    entitySecret: string;
+    /** Circle wallet ID (from `createWallets`/`listWallets`), not the on-chain address. */
+    walletId: string;
+    /** The wallet's on-chain address — fetch once via `getWallet({ id })` and store it; avoids an extra round-trip on every agent startup. */
+    address: Address;
+    /** Override Circle's API base URL (defaults to https://api.circle.com). */
+    baseUrl?: string;
+};
+
+type ArcBountyAgentConfigBase = {
     /** Arc RPC URL */
     rpcUrl?: string;
     /** IPFS metadata URI for agent registration (ipfs://Qm...) */
@@ -10,6 +21,15 @@ type ArcBountyAgentConfig = {
     /** BountyAdapter contract address (overrides default) */
     bountyAdapterAddress?: Address;
 };
+type ArcBountyAgentConfig = ArcBountyAgentConfigBase & ({
+    /** Private key of the agent wallet (0x-prefixed hex). Mutually exclusive with `circleWallet`. */
+    privateKey: Hash;
+    circleWallet?: never;
+} | {
+    privateKey?: never;
+    /** Sign via a Circle developer-controlled wallet instead of a raw private key. Mutually exclusive with `privateKey`. */
+    circleWallet: CircleWalletConfig;
+});
 type BountyMeta = {
     jobId: bigint;
     poster: Address;
@@ -35,6 +55,8 @@ type BountyMeta = {
     disputeReasonHash: string;
     disputeResponseHash: string;
     disputeRulingHash: string;
+    requireWorkerBond: boolean;
+    workerBond: bigint;
 };
 type ReputationScore = {
     averageScore: bigint;
@@ -65,6 +87,8 @@ type CreateBountyOptions = {
     provider?: Address;
     agentOnly?: boolean;
     humanOnly?: boolean;
+    /** V4: require the worker to post a bond (refunded at submitWork, forfeited to you if they vanish). */
+    requireWorkerBond?: boolean;
 };
 type SubmitWorkOptions = {
     /** Raw text/markdown result — will be pinned to IPFS */
@@ -90,8 +114,7 @@ type TxResult = {
 
 declare class ArcBountyAgent {
     private readonly publicClient;
-    private readonly walletClient;
-    private readonly account;
+    private readonly signer;
     private readonly bountyAdapter;
     private readonly metadataURI;
     private readonly chain;
@@ -99,8 +122,6 @@ declare class ArcBountyAgent {
     constructor(config: ArcBountyAgentConfig);
     get address(): Address;
     register(): Promise<bigint>;
-    /** Pull the minted tokenId from a Transfer(from=0x0, to=self) log in a receipt. */
-    private _agentIdFromReceiptLogs;
     get agentId(): bigint;
     setAgentId(id: bigint): void;
     listOpenBounties(filter?: OpenBountiesFilter): Promise<BountyMeta[]>;
@@ -133,14 +154,39 @@ declare class ArcBountyAgent {
     resolveDispute(jobId: bigint, payProvider: boolean, ruling: DisputeEvidenceOptions, reputationPenalty?: number): Promise<TxResult>;
     /** After 48h with no response, anyone may claim the default ruling. */
     claimDefaultRuling(jobId: bigint): Promise<TxResult>;
+    /**
+     * V3.3 liveness fallback: if the respondent DID reply (so claimDefaultRuling
+     * no longer applies) but the arbitrator never called resolveDispute within
+     * ARBITRATOR_TIMEOUT (30d) of disputeRaisedAt, anyone may trigger a neutral
+     * 50/50 split between poster and worker. No reputation penalty either way.
+     */
+    claimArbitratorTimeout(jobId: bigint): Promise<TxResult>;
     /** Worker challenges a pending rejection — flips bounty into dispute with worker as initiator. */
     challengeRejection(jobId: bigint, evidence: DisputeEvidenceOptions): Promise<TxResult>;
     /** Open a dispute (either party — after submission, before resolution). */
     disputeBounty(jobId: bigint, evidence: DisputeEvidenceOptions): Promise<TxResult>;
     /** Respond to an open dispute (only the non-initiator may call). */
     respondToDispute(jobId: bigint, evidence: DisputeEvidenceOptions): Promise<TxResult>;
+    /**
+     * Scans the full bounty set and calls expireBounty() on anything past its
+     * deadline with no submission and not yet resolved. Stops after finding
+     * `limit` candidates to expire.
+     *
+     * NOTE: `getOpenBounties` (used pre-V3.3) can NEVER return a candidate for
+     * this — it excludes any bounty whose deadline has already passed by
+     * definition (`_isOpenMatch` checks `block.timestamp <= deadline`). This
+     * scan walks `allJobIds` directly instead, mirroring the keeper cron route
+     * (`frontend/app/api/cron/keeper/route.ts`).
+     */
     expireStale(category?: string, limit?: number): Promise<bigint[]>;
     getReputation(agentId?: bigint): Promise<ReputationScore>;
+    /**
+     * V4 anti-Sybil signal: count of distinct posters who've actually paid out
+     * a completed bounty to this agent. Costs N real funded wallets to fake N —
+     * unlike the raw ERC-8004 average score, which one alt account can inflate
+     * for a few cents. See V4_DESIGN_ANTI_SYBIL.md.
+     */
+    getUniquePosterCount(agentId?: bigint): Promise<bigint>;
     getAgentInfo(): Promise<AgentInfo>;
     usdcBalance(): Promise<bigint>;
     formatUsdc(raw: bigint): string;
@@ -153,7 +199,39 @@ declare class ArcBountyAgent {
      * If you need durable dedup across restarts, persist `seenJobIds` yourself.
      */
     subscribeToNewBounties(filter: OpenBountiesFilter, onMatch: (meta: BountyMeta) => void | Promise<void>): () => void;
-    private _matchesFilter;
+    /**
+     * Background watchdog over this agent's own assigned bounties. An agent
+     * that only calls `takeBounty`/`submitWork` and then goes idle is exposed
+     * to every counterparty-controlled window in the contract: a poster can
+     * reject a correct submission (48h to challenge), open a dispute the agent
+     * never responds to (48h to respond, then the *other* side wins by
+     * default), or the agent may simply be owed a payout nobody triggered yet
+     * (14d autoApprove / 30d claimArbitratorTimeout). `protect()` polls
+     * `getMyBounties()` and reacts automatically:
+     *
+     *  - **Pending rejection, not yet challenged** → calls `onRejection` (if
+     *    provided) for evidence and calls `challengeRejection`. Without a
+     *    callback, a rejection is only logged, never auto-challenged — silently
+     *    auto-disputing every rejection would be its own failure mode.
+     *  - **Dispute raised by the other party, not yet responded** → calls
+     *    `onDisputeAgainstMe` for evidence and calls `respondToDispute`. Same
+     *    caveat: no callback means log-only.
+     *  - **Dispute resolved-by-response but arbitrator never ruled (30d)** →
+     *    calls `claimArbitratorTimeout` automatically (permissionless, no
+     *    evidence needed — this just unsticks the agent's own frozen funds).
+     *  - **Submitted, approval window elapsed (14d), poster silent** → calls
+     *    `autoApprove` automatically.
+     *
+     * Returns an `unwatch()` function. Errors on any single bounty are logged
+     * and swallowed so one bad case can't kill the whole watchdog.
+     */
+    protect(options?: {
+        pollingIntervalMs?: number;
+        onRejection?: (meta: BountyMeta) => Promise<DisputeEvidenceOptions>;
+        onDisputeAgainstMe?: (meta: BountyMeta) => Promise<DisputeEvidenceOptions>;
+        onEvent?: (event: string, meta: BountyMeta) => void;
+    }): () => void;
+    private _protectOnce;
     runOnce(filter: OpenBountiesFilter, runTask: (description: string, meta: BountyMeta) => Promise<string>): Promise<bigint | null>;
     private _waitForTx;
     /**
@@ -174,8 +252,6 @@ declare class ArcBountyAgent {
     private _findExistingAgentId;
     private _ensureUsdcAllowance;
     private _resolveEvidenceCid;
-    private _resolveDeadline;
-    private _parseUsdc;
 }
 
 declare const ARC_TESTNET_RPC = "https://rpc.testnet.arc.network";
@@ -187,6 +263,18 @@ declare const CONTRACTS: {
     readonly USDC: Address;
 };
 
+declare function parseUsdc(dollars: number): bigint;
+/** `d` < 1e9 is interpreted as duration-in-seconds from `nowSec` (~30yr cutoff). */
+declare function resolveDeadline(d: number | Date, nowSec?: number): bigint;
+/**
+ * V4 worker bond: max(minBond, reward * bondBps / 10_000). Mirrors
+ * BountyAdapter._workerBondFor. Defaults are the live V4 parameters
+ * (15% / $0.50 floor); pass the on-chain WORKER_BOND_BPS / MIN_WORKER_BOND
+ * values to stay correct across redeploys with different parameters.
+ */
+declare function workerBondFor(reward: bigint, bondBps?: bigint, minBond?: bigint): bigint;
+declare function matchesBountyFilter(m: BountyMeta, f: OpenBountiesFilter): boolean;
+
 declare const BOUNTY_ADAPTER_ABI: readonly [{
     readonly name: "createBounty";
     readonly type: "function";
@@ -218,6 +306,9 @@ declare const BOUNTY_ADAPTER_ABI: readonly [{
         }, {
             readonly name: "humanOnly";
             readonly type: "bool";
+        }, {
+            readonly name: "requireWorkerBond";
+            readonly type: "bool";
         }];
     }];
     readonly outputs: readonly [{
@@ -371,6 +462,27 @@ declare const BOUNTY_ADAPTER_ABI: readonly [{
         readonly type: "uint256";
     }];
     readonly outputs: readonly [];
+}, {
+    readonly name: "claimArbitratorTimeout";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "jobId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly name: "allJobIds";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
 }, {
     readonly name: "getOpenBounties";
     readonly type: "function";
@@ -472,6 +584,12 @@ declare const BOUNTY_ADAPTER_ABI: readonly [{
         }, {
             readonly name: "disputeRulingHash";
             readonly type: "string";
+        }, {
+            readonly name: "requireWorkerBond";
+            readonly type: "bool";
+        }, {
+            readonly name: "workerBond";
+            readonly type: "uint256";
         }];
     }];
 }, {
@@ -577,6 +695,45 @@ declare const BOUNTY_ADAPTER_ABI: readonly [{
         readonly name: "";
         readonly type: "uint256";
     }];
+}, {
+    readonly name: "ARBITRATOR_TIMEOUT";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "uniquePosterCount";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "agentId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "WORKER_BOND_BPS";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "MIN_WORKER_BOND";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
 }, {
     readonly name: "BountyCreated";
     readonly type: "event";
@@ -701,6 +858,70 @@ declare const BOUNTY_ADAPTER_ABI: readonly [{
         readonly type: "bool";
         readonly indexed: false;
     }];
+}, {
+    readonly name: "ArbitratorTimeoutClaimed";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly name: "jobId";
+        readonly type: "uint256";
+        readonly indexed: true;
+    }, {
+        readonly name: "posterAmount";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }, {
+        readonly name: "providerAmount";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }];
+}, {
+    readonly name: "WorkerBondPosted";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly name: "jobId";
+        readonly type: "uint256";
+        readonly indexed: true;
+    }, {
+        readonly name: "worker";
+        readonly type: "address";
+        readonly indexed: true;
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }];
+}, {
+    readonly name: "WorkerBondRefunded";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly name: "jobId";
+        readonly type: "uint256";
+        readonly indexed: true;
+    }, {
+        readonly name: "worker";
+        readonly type: "address";
+        readonly indexed: true;
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }];
+}, {
+    readonly name: "WorkerBondForfeited";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly name: "jobId";
+        readonly type: "uint256";
+        readonly indexed: true;
+    }, {
+        readonly name: "poster";
+        readonly type: "address";
+        readonly indexed: true;
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }];
 }];
 declare const IDENTITY_REGISTRY_ABI: readonly [{
     readonly name: "register";
@@ -832,4 +1053,4 @@ declare function validateAgentMetadata(m: unknown): asserts m is AgentMetadata;
 /** Pin a validated metadata blob to IPFS and return the `ipfs://<cid>` URI. */
 declare function pinAgentMetadata(meta: AgentMetadata): Promise<string>;
 
-export { ARC_TESTNET_CHAIN_ID, ARC_TESTNET_RPC, type AgentInfo, type AgentMetadata, ArcBountyAgent, type ArcBountyAgentConfig, type ArcBountySection, BOUNTY_ADAPTER_ABI, type BountyMeta, CONTRACTS, type CreateBountyOptions, type DisputeEvidenceOptions, ERC20_ABI, IDENTITY_REGISTRY_ABI, type OpenBountiesFilter, type ReputationScore, type SubmitWorkOptions, type TxResult, fetchIpfsJson, fetchIpfsText, isPinningConfigured, pinAgentMetadata, pinText, validateAgentMetadata };
+export { ARC_TESTNET_CHAIN_ID, ARC_TESTNET_RPC, type AgentInfo, type AgentMetadata, ArcBountyAgent, type ArcBountyAgentConfig, type ArcBountySection, BOUNTY_ADAPTER_ABI, type BountyMeta, CONTRACTS, type CircleWalletConfig, type CreateBountyOptions, type DisputeEvidenceOptions, ERC20_ABI, IDENTITY_REGISTRY_ABI, type OpenBountiesFilter, type ReputationScore, type SubmitWorkOptions, type TxResult, fetchIpfsJson, fetchIpfsText, isPinningConfigured, matchesBountyFilter, parseUsdc, pinAgentMetadata, pinText, resolveDeadline, validateAgentMetadata, workerBondFor };