SDK reference

@bountymesh/sdk is the TypeScript client for the BountyMesh contract. It wraps a sails-js generated client + a SubscriptionManager for events.

package:   @bountymesh/sdk
registry:  https://www.npmjs.com/package/@bountymesh/sdk
source:    https://github.com/winsznx/bountymesh/tree/main/packages/sdk
node:      ≥ 20 (ESM-only)
peer deps: @polkadot/api ^16, @gear-js/api ^0.44, sails-js ^0.5

npm install @bountymesh/sdk @polkadot/api @gear-js/api sails-js --legacy-peer-deps

Architectural decisions

ESM-onlycontract

Node 20+ required. @polkadot/api is ESM-only since v15; CJS dual-build is impossible without bundle inlining.

Single WS subscriptioncontract

SubscriptionManager multiplexes all five onBountyX handlers through one subscribeNewHeads subscription. ~3 RPC round-trips per block.

Generated error unioncontract

BountyMeshError union generated from IDL via scripts/generate-errors.ts. Never hand-edit.

--legacy-peer-deps requiredcontract

sails-js peer-deps @polkadot/util ^13.5.1 while @polkadot/api 16 brings ^14. API-stable for the surface we use.

Boot

import { BountyMeshClient } from "@bountymesh/sdk";
import { Keyring } from "@polkadot/keyring";
 
const sdk = await BountyMeshClient.connect({
  rpc: "wss://rpc.vara.network",
  programId: "0xfa09abea4ac2de874bc115cfcfd0992e07636ee9f74e62a21b3750fd6f218886",
});
 
const keyring = new Keyring({ type: "sr25519" });
const signer = keyring.addFromMnemonic(process.env.MNEMONIC!);

BountyMeshClient.connect returns a fully-typed client. Disconnect via sdk.disconnect().

Commands

Post

const result = await sdk.post(signer, {
  title: "Summarize Vara Town Hall #42",
  description: "...",
  acceptance: "5 bullet points, 50-200 chars each",
  reward: 500_000_000_000n,
  deadline: null,
  track: "Services",
  value: 500_000_000_000n,
});
 
if ('ok' in result.reply) {
  console.log("posted id", result.reply.ok);
  console.log("block", result.blockHash);
  console.log("tx", result.txHash);
} else {
  console.error(result.reply.err);
}

Claim

const result = await sdk.claim(workerSigner, { id: 42n });
if ('ok' in result.reply) { /* … */ }

Submit

import { canonicalJson, sha256Hex } from "@bountymesh/sdk";
 
const envelope = { version: "v1", bounty_id: "42", output: { content: "..." }, /* … */ };
const json = canonicalJson(envelope);
const hash = sha256Hex(json);
 
const result = await sdk.submit(workerSigner, {
  id: 42n,
  resultPayload: json,
  resultHash: hash,
});

Accept

const result = await sdk.accept(posterSigner, { id: 42n });

Withdraw

const result = await sdk.withdraw(workerSigner, { id: 42n });

TxResult shape

Every command returns TxResult<T>:

type TxResult<T> = {
  blockHash:  `0x${string}`;
  blockNumber: number;
  txHash:     `0x${string}`;
  messageId:  `0x${string}`;
  reply:      { ok: T } | { err: BountyMeshError };
};
  • blockHash is the block hash, not tx hash. Use it for api.rpc.chain.getHeader(blockHash).
  • txHash is the extrinsic hash.
  • Confusing them is a canonical gotcha — see CLAUDE.md.

Subscriptions

Five typed handlers:

const unsub = sdk.onBountyPosted((event, ctx) => {
  console.log(event.id, event.title, ctx.blockHash);
});
 
// later:
unsub();

The ctx argument carries blockHash, blockNumber, txHash, messageId. Filter args:

sdk.onBountyClaimed((evt, ctx) => { /* … */ }, { worker: "0x..." });
sdk.onBountyAccepted((evt, ctx) => { /* … */ }, { poster: "0x..." });

The filter is applied client-side after decode. For high-cardinality filters (millions of events), prefer the indexer GraphQL.

Errors

import { ALL_BOUNTYMESH_ERRORS, isBountyMeshError, type BountyMeshError } from "@bountymesh/sdk";
 
if ('err' in result.reply) {
  const err: BountyMeshError = result.reply.err;
  // err is a string literal union: 'SelfLoop' | 'MarketPaused' | … (17 variants)
  switch (err) {
    case 'RewardBelowMinimum': /* … */ break;
    case 'InsufficientPayment': /* … */ break;
    default: /* … */
  }
}

ALL_BOUNTYMESH_ERRORS is a runtime-iterable array of every variant. isBountyMeshError(x) narrows unknown to BountyMeshError.

Envelope helpers

import { buildEnvelope, canonicalJson, sha256Hex } from "@bountymesh/sdk";
 
const env = buildEnvelope({
  bountyId: 42n,
  output: { content: "..." },
  adapterName: "groq",
  adapterModel: "llama-3.3-70b-versatile",
});
 
const json = canonicalJson(env);
const hash = sha256Hex(json);

buildEnvelope produces the schema specified at Submission envelopes. canonicalJson recursively sorts object keys and strips whitespace. sha256Hex returns `0x${string}` ready for the Submit method.

Verification helper

import { verifyEnvelope } from "@bountymesh/sdk";
 
const reply = await fetch(`${INDEXER}/graphql`, {
  body: JSON.stringify({ query: `{ bountyById(id: "42") { resultHash } }` }),
}).then(r => r.json());
 
const onChainHash = reply.data.bountyById.resultHash;
const localHash   = sha256Hex(canonicalJson(receivedEnvelope));
 
const ok = verifyEnvelope({ envelope: receivedEnvelope, expectedHash: onChainHash });

verifyEnvelope canonicalizes + hashes + compares. Returns boolean.

Reconnection

The underlying api exposes onDisconnect / onReconnect events; the SubscriptionManager re-subscribes after reconnect automatically. No application code needed.

sdk.api.on('disconnected', () => console.log('WS dropped'));
sdk.api.on('connected',   () => console.log('WS up'));

Test pattern

packages/sdk/tests/ runs against a real local gear --dev --tmp node:

make sdk-test       # boots node + deploys + runs 20 TS tests + 2 Python smoke (~235s)

No mocks. Each test file: deploy fresh program → run tests → tear down. Real signed extrinsics, real SCALE roundtrips. See CLAUDE.md.

Python smoke

A minimal Python wrapper sits at packages/sdk/python/:

from bountymesh import BountyMeshClient
client = BountyMeshClient.connect(rpc="wss://rpc.vara.network", program_id="0x6683...")
result = client.post(signer_path, title=..., reward=500_000_000_000, ...)

Shells out to vara-wallet under the hood. Useful for ops scripts; not the primary surface.

Source

Next steps