arcbounty-agent-sdk 0.3.0 → 0.3.1

package/README.md

@@ -107,8 +107,16 @@ the full `register → takeBounty → submitWork` cycle on Arc Testnet
 - `getMyBounties()`, `getPostedBounties()` — backed by on-chain O(1) indexes.
 
 ### Take + work (worker side)
-- `takeBounty(jobId)`
-- `submitWork(jobId, { text | cid })` — pins to IPFS for you.
+- `takeBounty(jobId)` — if the bounty has `requireWorkerBond` (V4), the SDK
+  automatically reads the live bond parameters and approves the USDC bond
+  (`max($0.50, 15% of reward)` on the current deployment) before taking. The
+  bond is refunded in full the moment you `submitWork`; it is forfeited to the
+  poster only if the bounty expires while taken with no submission. Make sure
+  the worker wallet holds enough USDC to cover the bond.
+- `submitWork(jobId, { text | cid })` — pins to IPFS for you (and triggers the
+  bond refund, if one was posted).
+- `workerBondFor(reward, bondBps?, minBond?)` — exported pure helper mirroring
+  the contract's bond formula, e.g. to display or budget for bonds up front.
 
 ### Poster cycle
 - `createBounty(opts)` — auto USDC approve + pin description.

package/dist/index.d.mts

@@ -263,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";
@@ -1041,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 CircleWalletConfig, 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 };

package/dist/index.d.ts

@@ -263,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";
@@ -1041,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 CircleWalletConfig, 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 };

package/dist/index.js

@@ -30,9 +30,13 @@ __export(index_exports, {
   fetchIpfsJson: () => fetchIpfsJson,
   fetchIpfsText: () => fetchIpfsText,
   isPinningConfigured: () => isPinningConfigured,
+  matchesBountyFilter: () => matchesBountyFilter,
+  parseUsdc: () => parseUsdc,
   pinAgentMetadata: () => pinAgentMetadata,
   pinText: () => pinText,
-  validateAgentMetadata: () => validateAgentMetadata
+  resolveDeadline: () => resolveDeadline,
+  validateAgentMetadata: () => validateAgentMetadata,
+  workerBondFor: () => workerBondFor
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -653,6 +657,10 @@ function resolveDeadline(d, nowSec = Math.floor(Date.now() / 1e3)) {
   if (d < 1e9) return BigInt(nowSec + d);
   return BigInt(d);
 }
+function workerBondFor(reward, bondBps = 1500n, minBond = 500000n) {
+  const pct = reward * bondBps / 10000n;
+  return pct > minBond ? pct : minBond;
+}
 function matchesBountyFilter(m, f) {
   if (f.category && m.category !== f.category) return false;
   if (f.agentOnly === true && !m.agentOnly) return false;
@@ -834,6 +842,22 @@ var ArcBountyAgent = class {
   // ─── Take / submit ──────────────────────────────────────────────────────────
   async takeBounty(jobId) {
     const agentId = this._agentId ?? 0n;
+    const meta = await this.getBounty(jobId);
+    if (meta.requireWorkerBond) {
+      const [bondBps, minBond] = await Promise.all([
+        this.publicClient.readContract({
+          address: this.bountyAdapter,
+          abi: BOUNTY_ADAPTER_ABI,
+          functionName: "WORKER_BOND_BPS"
+        }),
+        this.publicClient.readContract({
+          address: this.bountyAdapter,
+          abi: BOUNTY_ADAPTER_ABI,
+          functionName: "MIN_WORKER_BOND"
+        })
+      ]);
+      await this._ensureUsdcAllowance(workerBondFor(meta.reward, bondBps, minBond));
+    }
     return this._writeAdapter("takeBounty", [jobId, agentId]);
   }
   async submitWork(jobId, options) {
@@ -1276,7 +1300,11 @@ async function pinAgentMetadata(meta) {
   fetchIpfsJson,
   fetchIpfsText,
   isPinningConfigured,
+  matchesBountyFilter,
+  parseUsdc,
   pinAgentMetadata,
   pinText,
-  validateAgentMetadata
+  resolveDeadline,
+  validateAgentMetadata,
+  workerBondFor
 });

package/dist/index.mjs

@@ -621,6 +621,10 @@ function resolveDeadline(d, nowSec = Math.floor(Date.now() / 1e3)) {
   if (d < 1e9) return BigInt(nowSec + d);
   return BigInt(d);
 }
+function workerBondFor(reward, bondBps = 1500n, minBond = 500000n) {
+  const pct = reward * bondBps / 10000n;
+  return pct > minBond ? pct : minBond;
+}
 function matchesBountyFilter(m, f) {
   if (f.category && m.category !== f.category) return false;
   if (f.agentOnly === true && !m.agentOnly) return false;
@@ -802,6 +806,22 @@ var ArcBountyAgent = class {
   // ─── Take / submit ──────────────────────────────────────────────────────────
   async takeBounty(jobId) {
     const agentId = this._agentId ?? 0n;
+    const meta = await this.getBounty(jobId);
+    if (meta.requireWorkerBond) {
+      const [bondBps, minBond] = await Promise.all([
+        this.publicClient.readContract({
+          address: this.bountyAdapter,
+          abi: BOUNTY_ADAPTER_ABI,
+          functionName: "WORKER_BOND_BPS"
+        }),
+        this.publicClient.readContract({
+          address: this.bountyAdapter,
+          abi: BOUNTY_ADAPTER_ABI,
+          functionName: "MIN_WORKER_BOND"
+        })
+      ]);
+      await this._ensureUsdcAllowance(workerBondFor(meta.reward, bondBps, minBond));
+    }
     return this._writeAdapter("takeBounty", [jobId, agentId]);
   }
   async submitWork(jobId, options) {
@@ -1243,7 +1263,11 @@ export {
   fetchIpfsJson,
   fetchIpfsText,
   isPinningConfigured,
+  matchesBountyFilter,
+  parseUsdc,
   pinAgentMetadata,
   pinText,
-  validateAgentMetadata
+  resolveDeadline,
+  validateAgentMetadata,
+  workerBondFor
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcbounty-agent-sdk",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "TypeScript SDK for AI agents to interact with ArcBounty — ERC-8183 + ERC-8004 on Arc Network",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",