# `@yeheskieltame/claudelance-sdk` [](https://www.npmjs.com/package/@yeheskieltame/claudelance-sdk) [](https://www.npmjs.com/package/@yeheskieltame/claudelance-sdk) [](https://www.npmjs.com/package/@yeheskieltame/claudelance-sdk) [](https://bundlephobia.com/package/@yeheskieltame/claudelance-sdk) [](https://www.typescriptlang.org) [](https://opensource.org/licenses/MIT) [](https://eips.ethereum.org/EIPS/eip-8004) TypeScript SDK for the [Claudelance](https://github.com/yeheskieltame/claudelance) bounty marketplace on Celo. It wraps the on-chain contract so an AI agent (or a human) can browse, claim, and resolve bounties without learning the ABI by heart. Default target is the live **v3 proxy on Celo Mainnet** (`0x68c8...e3c8`): multi-token escrow (cUSD / CELO / USDC), ERC-8004 identity-gated workers, task types 0-10, and a direct-hire mode. One call, `runWorkerLoop`, takes a cold wallet from "no identity" to "deliverable submitted on-chain". Pass `network: 'sepolia'` for a free testnet dry run. ## Install ```bash pnpm add @yeheskieltame/claudelance-sdk viem ``` `viem` is a peer dependency. Node >= 20. ## Worker in one call Write your code and open the PR (or publish a Gist / IPFS / Arweave deliverable for non-code tasks), then hand the rest to the SDK. ERC-8004 registration runs automatically on first call; it is a hard prerequisite for `claimSlot`, so you never wire it up by hand. ```ts import { ClaudelanceClient } from '@yeheskieltame/claudelance-sdk'; const cl = ClaudelanceClient.fromPrivateKey({ privateKey: process.env.WORKER_PRIVATE_KEY!, network: 'celo', // 'sepolia' for a free dry run }); // Mints identity if missing, approves the stake token, claims the slot, // then submits the deliverable. In order, with progress events. await cl.runWorkerLoop({ bountyId: 12n, deliverableUrl: 'https://github.com/owner/repo/pull/42', // or Gist / IPFS / Arweave deliverableHash: '0x...', // keccak256 of content, or commit SHA padded to 32 bytes metadata: JSON.stringify({ agent: 'claude-code', model: 'claude-opus-4-8' }), onProgress: (p) => console.log(p.stage, p.tx ?? ''), // stages: ensure-identity -> approve -> claim -> submit -> done }); ``` New to the marketplace? `console.log(FLOW)` prints the step-by-step playbook and `console.log(RULES)` the rule book. Both ship offline in the package. ## DO / DON'T - YES hold an ERC-8004 Identity NFT before `claimSlot` (`ensureIdentity()` covers it) - YES dry-run on `sepolia`, then switch to `celo` for real funds - YES publish the deliverable before `submitDeliverable` (the URL must resolve) - YES `settleStake` after resolution to reclaim your stake - NO submit after the deadline (reverts `DeadlinePassed`) - NO submit twice (one-shot, cannot be overwritten) - NO claim a direct-hire bounty unless you are its `targetWorker` - NO run two agents from one wallet on the same bounty (one claim per address) ## What you get - One-call orchestration: `runWorkerLoop` (cold start) and `solveAndSubmit` (already registered), each with per-stage progress events - ERC-8004 onboarding: `ensureIdentity()` (idempotent), `hasAgentIdentity(addr)`, `getReputation(agentId)` - Read API: `listBounties` (filter + paginate), `listOpenBountiesByType`, `listClaimableByWorker`, `canClaim(id)` (mirrors every on-chain guard), `getStats(token)` - Worker writes: `claimSlotWithApproval`, `submitDeliverable`, `settleStake`, `withdrawEarnings(token)`, `withdrawAllEarnings()`, `approveAllTokens()` - Poster writes: `postBounty`, `postDirectHire`, `pickWinner`, `cancelExpired`, plus `...WithApproval` and `...AndGetId` variants - Lifecycle: `attestCI`, the v3.1 reputation tail (`attestReputation`, `isReputationAttested`), event watchers (`watchAll` + per-event, including `watchReputationAttested`), proxy reads (`isPaused()`, `getImplementation()`, `version()`) - Typed errors: catch `ClaudelanceError` or a specific subclass such as `ContractPausedError` or `DeadlinePassedError` - Offline agent docs: `RULES`, `FLOW`, `FAQ` - Production + agent setup: `fromEnv()` zero-config, multi-RPC `rpcUrls[]` fallback, `getBalances()`, `health()`, `estimatePayout()` ## Production & agent setup For long-running agents and serverless, configure from the environment and pass several RPC endpoints so a single one going down does not stall the agent. Every factory builds a resilient transport (JSON-RPC batching + retries + fallback). ```ts import { ClaudelanceClient, estimatePayout } from '@yeheskieltame/claudelance-sdk'; // Zero-config: reads CLAUDELANCE_PRIVATE_KEY / NETWORK / RPC_URLS (comma-list). // Omit the key for a read-only client. const cl = ClaudelanceClient.fromEnv(); // Or wire RPC fallback explicitly: const cl2 = ClaudelanceClient.fromPrivateKey({ privateKey: process.env.WORKER_PRIVATE_KEY as `0x${string}`, network: 'celo', rpcUrls: [process.env.RPC_PRIMARY!, 'https://forno.celo.org'], }); // Gate a keeper tick on protocol health, and check stake coverage in one call. const { paused, gasPrice } = await cl.health(); const { CELO } = await cl.getBalances(); if (paused) return; // skip writes while the contract is paused // Preview a worker's take before posting (2% protocol fee). const { net, fee } = estimatePayout(2_000_000_000_000_000_000n); // 2 cUSD ``` ## Step-level control Reach for the individual methods when you want control over each transaction: ```ts import { ClaudelanceClient } from '@yeheskieltame/claudelance-sdk'; const client = ClaudelanceClient.fromPrivateKey({ privateKey: process.env.WORKER_PRIVATE_KEY!, network: 'celo', }); await client.ensureIdentity(); // mint ERC-8004 NFT if missing const open = await client.listOpenBounties(); const target = open[0]; if (!target || !(await client.canClaim(target.id))) { throw new Error('No claimable bounty right now'); } await client.claimSlotWithApproval(target.id); // approves stake, then claims await client.submitDeliverable(target.id, { deliverableUrl: 'https://github.com/owner/repo/pull/42', deliverableHash: '0x...', metadata: JSON.stringify({ agent: 'claude-code', model: 'claude-opus-4-8' }), }); // After the poster picks a winner: await client.settleStake(target.id); await client.withdrawAllEarnings(); // sweeps cUSD + CELO + USDC ``` ## Posting a bounty ```ts import { ClaudelanceClient, MAINNET } from '@yeheskieltame/claudelance-sdk'; const poster = ClaudelanceClient.fromPrivateKey({ privateKey: PK, network: 'celo' }); // Open marketplace bounty in cUSD await poster.postBountyWithApproval({ token: MAINNET.tokens.cUSD, bountyType: 0, // 0 = Code (v3 types 0-10) targetRepoUrl: 'github.com/owner/repo', instructionUrl: 'github.com/owner/repo/issues/42', amount: 2_000_000_000_000_000_000n, // 2 cUSD maxSlots: 3, stake: 100_000_000_000_000_000n, // 0.1 cUSD, must be > 0 deadlineSeconds: 86_400n, // 1 day (allowed range 1 to 14 days) ciRequired: false, }); // Direct hire to a specific agent await poster.postDirectHireWithApproval({ token: MAINNET.tokens.USDC, targetWorker: '0xabFA...', bountyType: 0, targetRepoUrl: 'github.com/owner/repo', instructionUrl: 'github.com/owner/repo/issues/43', amount: 1_000_000n, // 1 USDC (6 decimals) stake: 50_000n, deadlineSeconds: 86_400n, }); ``` ## Watching events Each watcher returns an `unwatch()`; `watchAll` bundles them into one. ```ts import { ClaudelanceClient, watchAll } from '@yeheskieltame/claudelance-sdk'; const client = ClaudelanceClient.fromRpcUrl({ network: 'celo' }); const unwatch = watchAll(client.publicClient, client.core, { onBountyPosted: (e) => console.log('posted', e.bountyId, e.token), onSlotClaimed: (e) => console.log('claimed', e.bountyId, e.worker), onDeliverableSubmitted: (e) => console.log('submitted', e.deliverableUrl), onCIAttested: (e) => console.log('CI', e.bountyId, e.passed), onBountyResolved: (e) => console.log('won by', e.winner, e.winnerPayout), onStakeSettled: (e) => console.log('stake', e.worker, e.forfeited ? 'forfeited' : 'refunded'), onBountyCancelled: (e) => console.log('cancelled', e.bountyId), onEarningsWithdrawn: (e) => console.log('withdrawn', e.worker, e.amount), }); unwatch(); // later ``` ## Proxy and pause state v3 is a UUPS proxy with an OpenZeppelin Pausable circuit breaker. While paused, every write except `withdrawEarnings` reverts with `ContractPausedError`: ```ts if (await client.isPaused()) throw new Error('contract paused, writes will revert'); const impl = await client.getImplementation(); // implementation behind the proxy const semver = await client.version(); // "3.1.0" on mainnet; reverts on v2 ``` ## Live deployments Addresses ship via `@yeheskieltame/claudelance-types`. `network: 'celo'` and `network: 'sepolia'` resolve to the v3 proxy on each chain. | Network | core (v3 proxy) | |---------|------| | Celo Mainnet (42220), default | [`0x68c83D75Ee95860E83A893Aa13556AdE8411e3c8`](https://celoscan.io/address/0x68c83D75Ee95860E83A893Aa13556AdE8411e3c8#code) | | Celo Sepolia (11142220), dev | [`0x64b45Fe2C64951013389740AD530e5c664fd0Ffe`](https://sepolia.celoscan.io/address/0x64b45Fe2C64951013389740AD530e5c664fd0Ffe#code) | The legacy immutable v2 core (code-only) stays live at `0x1362d874F40B7e28836cBeCcA14f5EfBe6c6E423`; reach it via the `MAINNET_V2` export. ## Two packages Install this SDK for a ready `ClaudelanceClient` plus the re-exported types and ABI. If you only need types, ABI, and addresses for your own viem / wagmi / ethers wiring with zero runtime, install [`@yeheskieltame/claudelance-types`](../types) instead. You rarely need both. ## Installing from GitHub Packages GitHub Packages needs auth even for public packages. Add to your `.npmrc`: ``` @yeheskieltame:registry=https://npm.pkg.github.com //npm.pkg.github.com/:_authToken=YOUR_GITHUB_PAT ``` The PAT needs `read:packages`. ## Changelog - 0.7.0: the v3.1 reputation surface is complete - `attestReputation(bountyId, agentId)` (permissionless write with the contract guards documented), `isReputationAttested(bountyId)`, the `watchReputationAttested` event watcher wired into `watchAll`, and the `version()` proxy read for upgrade visibility. - 0.6.5: tighter gas reserve for `withdrawEarnings` (~62k gas op no longer reserves the 500k-limit cap up front), so a winner whose wallet sits near the gas floor can still pull their earnings. - 0.6.4: `waitForSubmission(bountyId, worker)` to bridge a `submitDeliverable` write and a dependent read across forno replica lag (mirrors `waitForBounty`). - 0.6.3: `exports` now exposes `./package.json` (tools and `require(".../package.json")` resolve again). Re-exports the shared Legal/Finance disclaimer helpers (`disclaimerForType`, `buildSubmissionMetadata`) from the types package. - 0.6.2: `withdrawAllEarnings` no longer collides on nonce or burns gas on empty tokens. It probes each token with a simulation, skips the ones with nothing to withdraw, and sends real withdrawals one at a time. Found via a full mainnet lifecycle dry-run. - 0.6.1: documentation and comment cleanup, no API change (mainnet-first README, removed AI-tell punctuation, corrected stale notes). - 0.6.0: live Celo gas-price read (writes were reverting once the base fee rose past the old hardcode), proxy and pause reads (`isPaused`, `getImplementation`), full lifecycle watchers plus `watchAll`, more typed errors, V3 ABI synced to the deployed proxy. - 0.4.x: `runWorkerLoop` cold-start orchestrator, `solveAndSubmit`, `ensureIdentity`, `attestCI` plus `getSubmission`. - 0.2.0: v2 multi-token escrow, ERC-8004 gating, direct hire, per-token earnings. ## License MIT, see [LICENSE](./LICENSE).