Skip to content

README.md

Latest commit

 

History

History
159 lines (124 loc) · 5.38 KB

README.md

File metadata and controls

159 lines (124 loc) · 5.38 KB

@taskforest/sdk

TypeScript SDK for TaskForest, the spec-centric task layer for agents and humans on Solana.

@taskforest/sdk covers the core TaskForest flow:

  • define a task contract as a TaskForestSpec
  • hash and validate that contract deterministically
  • create a funded on-chain job from the approved spec
  • execute, verify, dispute, and settle against the same commitment

Dark Forest payment-channel helpers are intentionally not part of this package.

Install

npm install @taskforest/sdk

Quick Start

import { Keypair } from '@solana/web3.js'
import { TaskForest, SpecBuilder, hashSpecHex, validateSpec } from '@taskforest/sdk'

const tf = new TaskForest({
  rpc: 'https://api.devnet.solana.com',
  wallet: Keypair.generate(),
  network: 'devnet',
})

const spec = new SpecBuilder('Review my Solana program')
  .description('Review the repository for security issues and return a markdown report.')
  .tags(['solana', 'security', 'review'])
  .difficulty('hard')
  .duration('2h')
  .criterion('ac-1', 'Cover all critical security surfaces', 'coverage', { required: true, weight: 50 })
  .criterion('ac-2', 'Return a markdown report with severity labels', 'output', { required: true, weight: 50 })
  .constraint('Cite concrete findings and affected files')
  .input('url', 'Repository URL', { encrypted: false })
  .output('file', 'Audit report', { format: 'markdown' })
  .judgeMode('Score each criterion from 0-100. Missing critical issues is an automatic fail.', 70)
  .build()

const validationErrors = validateSpec(spec)
if (validationErrors.length > 0) {
  throw new Error(JSON.stringify(validationErrors, null, 2))
}

const specHash = hashSpecHex(spec)
console.log('spec hash:', specHash)

const job = await tf.postTask({
  title: spec.metadata.title,
  input: { repo_url: 'https://github.com/example/repo' },
  spec,
  reward: 0.5,
  deadline: '2h',
  privacy: 'encrypted',
  assignmentMode: 'auction',
  verificationLevel: 2,
})

console.log(job.jobId, job.pubkey.toBase58(), job.signature)

Worker Loop

tf.onTask({ minReward: 0.1, status: 'open' }, async (task) => {
  const input = await task.getInput()
  const result = await myAgent.process(input)
  await task.submitProof(result)
})

Core API

Spec

Export Description
SpecBuilder Fluent builder for TaskForestSpec
validateSpec(spec) Validate a spec before posting
canonicalizeSpec(spec) Deterministic JSON serialization
hashSpec(spec) / hashSpecHex(spec) Deterministic spec hash
hashVerificationResult(result) Hash verification outputs for commitments
listTemplates() / getTemplate() / applyTemplate() Reusable task-family helpers

Jobs

Method Description
postTask(opts) Create a funded job from a spec or precomputed specHash
searchTasks(filter?) Search on-chain jobs
getTask(pubkey) Fetch a specific job
bid(pubkey, opts) Place a bid with stake
lockStake(pubkey) Lock SOL after winning a bid
stakeAndProve(pubkey, result) Lock stake and submit proof in one tx
submitProof(pubkey, result) Submit proof hash
submitEncryptedProof(pubkey, result, inputHash) Submit privacy-mode proof
settle(pubkey, pass) Settle job
settleAndArchive(pubkey, pass, proofUri) Settle and archive in one tx

Routing, Verification, Disputes

Method Description
autoAssignJob(opts) Assign a specific agent to a job
createSubJob(opts) Create a delegated child job
submitVerifiedProof(opts) Submit proof plus receipts and attestation
autoSettle(pubkey) Settle after dispute window expiry
openDispute(opts) Open a dispute against a job
resolveDispute(opts) Resolve a dispute
getDispute(pubkey) Fetch dispute record
castVote(opts) Vote as a verifier
tallyPanel(jobPubkey, disputePubkey, challengerPubkey, votePubkeys) Tally verifier votes

Agents and Grove

Method Description
registerAgent(opts) Register an agent profile
getAgent(walletAddress) Fetch one Grove agent
searchAgents(filter?) Search Grove agents
onTask(filter, handler) Poll for matching open tasks

Receipts and Utilities

Export Description
createReceipt(...) / createToolCallReceipt(...) Build receipt nodes
buildDAG(root, children) / getMerkleRoot(dag) Build receipt DAGs
serializeDAG(dag) / deserializeDAG(json) Persist and restore DAGs
storeCredential(pubkey, data) Store encrypted credential in vault
encrypt(data, recipientPubkey) / decrypt(...) NaCl box helpers
getBalance() / airdrop(sol) Wallet utilities

Notes

  • postTask() prefers spec or specHash. ttd remains optional metadata for task-family discovery.
  • verificationMode is inferred from spec.verification.mode when a spec is provided.
  • Dark Forest payment demos and MagicBlock-specific payment helpers live in @taskforest/dark-forest.

Program ID

Fgiye795epSDkytp6a334Y2AwjqdGDecWV24yc2neZ4s

Links

License

MIT