🦀 BitClaw Dev Portal

1.Quick start

1. Write a module: an IIFE that registers window.BitClawV2Modules['my-app'] with { meta, mount(container, ctx), unmount() } — see the Sandbox API v1 contract below for the exact skeleton.
2. Test it locally in /local-test/ against a real shell before spending anything (see section 4).
3. In Build App → Deploy Code: paste/upload your .js file. It's gzipped and chunked into CD| records automatically if it's over 90KB — approve the resulting draft(s) in your Outbox.
4. In Build App → Publish: fill in name/icon/description/category, point main at your deployed code, broadcast the ML| manifest.
5. Your app appears in everyone's Browse tab once the publish TX confirms (~10 min on WhatsOnChain). Anyone who installs it gets it sandboxed, same as described here.

2.Funding — getting your first satoshis

Every step that touches the chain (deploying code, publishing a manifest, registering a DNS name) is a real BSV transaction paid from your own wallet. You don't need much.

Roughly what things cost

These are order-of-magnitude estimates, not quotes — actual miner fee rates can change.

3.BitClaw V3 — Third-Party App Spec (Sandbox API v1)

(function() {
  'use strict';
  let _ctx = null;

  window.BitClawV2Modules = window.BitClawV2Modules || {};
  window.BitClawV2Modules['my-module'] = {
    meta: {
      title: 'My App',
      icon: '🚀',
      color: '#7c3aed',       // accent color
      version: '1.0.0',
      description: 'Short description (max 200 chars)',
    },
    mount(container, ctx) {
      _ctx = ctx;
      container.innerHTML = '<div>Hello BitClaw</div>';
      // ctx.bitclaw — Sandbox API v1 bridge, see section 2 below
      // ctx.params  — URL sub-path segments: /v3/my-module/id → ['id']
    },
    unmount() {
      _ctx = null;
      // clean up event listeners, timers
    },
  };

  // OPTIONAL — MCP opt-in (infra/mcp/ui-capabilities.mjs). Two small literals
  // let an assistant type into your form and press your buttons the way a
  // person would: mcpFields maps a name to a CSS selector for a real input
  // already in your markup, mcpActions maps a name to the real function your
  // own onclick calls. Nothing new runs — the module's own code still builds
  // the record. Only expose what stops at a reviewable Outbox draft; leave
  // out anything that spends, deletes, or executes code immediately.
  window.BitClawV2Modules['my-module'].mcpFields = {
    title: '#my-title',
    body: '#my-body',
  };
  window.BitClawV2Modules['my-module'].mcpActions = {
    publish: '_myPublish',
  };
})();

Base bridge — always on, no declaration needed (reads are proxied through the
parent page, promise-based; writes always go through the user's Outbox):

  ctx.bitclaw.v2data.fetchHistory(address)
  ctx.bitclaw.v2data.fetchHistoryWithData(address, opts)   // history + decoded OP_RETURN in one round trip
  ctx.bitclaw.v2data.fetchTx(txid)
  ctx.bitclaw.util.addressFromHashtag(tag)   // fixed tags ONLY — see section 5
  ctx.bitclaw.util.geoAnchor(hash4)          // collision-safe geo anchor (async)
  ctx.bitclaw.util.dnsAnchor(name)           // collision-safe DNS anchor (async)
  ctx.bitclaw.util.appAnchor(tag)            // collision-safe anchor scoped to YOUR app only (async)
  // Always bound to your own installed appId — there's no way to pass a
  // different scope, so you can't collide with (or write into) another app's
  // anchor space, and it can't collide with yours across different tags either.
  ctx.bitclaw.data.fetch(type, opts)
  ctx.bitclaw.identity.getAddress()
  ctx.bitclaw.wallet.getAddress()          // synchronous, cached at mount
  ctx.bitclaw.wallet.isConnected()         // synchronous, cached at mount

  ctx.bitclaw.outbox.addDraft({ label, record, sats, meta })
  // Queues a draft in the user's Outbox. NOTHING broadcasts until the user
  // reviews and approves it there — your code never sees a private key.

Rate limit on reads: burst 30 requests, refills ~4/sec. Over the limit you get
back { error: "Rate limit exceeded" } — back off, don't hammer it.

Permission-gated bridge — ONLY available if your ML manifest declares them in
a top-level "permissions" array (see section 3). Calling these without the
matching permission either rejects with an error (store) or is silently
dropped (ws/navigate — those were already fire-and-forget for first-party
modules too, there's no round trip to fail):

  "permissions": ["store"]
    ctx.bitclaw.store.get(key)              → Promise<string|null>
    ctx.bitclaw.store.set(key, value)       → Promise<true>
    ctx.bitclaw.store.getJSON(key, fallback) → Promise<any>
    ctx.bitclaw.store.setJSON(key, value)   → Promise<true>
    ctx.bitclaw.store.remove(key)           → Promise<true>
    // 128KB total per app, namespaced so no other app can read or clobber
    // your keys. NOTE: async here (unlike first-party bc.store, which is
    // synchronous) — it goes over postMessage. Freed automatically on
    // uninstall.

  "permissions": ["ws"]
    ctx.bitclaw.ws.watchAnchor(bsvAddress, cb)   // cb(event) on 0-conf + confirmed
    ctx.bitclaw.ws.unwatchAnchor(bsvAddress)
    // Anchor events only — NOT the full first-party bc.ws (no personal addr:
    // inbox, no board: channels, no sub/onMsg/send). Max 5 anchors watched at
    // once per mounted instance.

  "permissions": ["navigate"]
    ctx.navigate(page, params)   // send the user to another BitClaw page —
                                  // validated against the real route list,
                                  // your app's iframe is torn down like any
                                  // other navigation
    ctx.setParams(params)        // update your OWN app's URL params (only
                                  // takes effect while your app is still the
                                  // active route)

Still no-op / unavailable, permission or not:
  ctx.eventBus                        no-ops (logs one console.warn)
  window.localStorage / cookies       throws SecurityError (opaque origin —
                                      this is the whole point of the sandbox)

Declaring a permission you don't use is harmless but pointless — it just
shows up in the Install confirmation dialog users see before installing,
so only ask for what you actually need.

ML|<appId>|1|1|<JSON>

Required:
  name         string   Display name (3-50 chars)
  icon         string   Single emoji
  main         txid     CD record with the main JS module

Optional:
  description  string   (max 200 chars)
  version      string   semver "1.2.0"
  color        hex      "#7c3aed"
  category     string   tools|finance|social|games|education|market|productivity|developer|other
  authorPfId   pfId     pf_<id> — must match your profile
  dnsName      string   registered DNS name pointing to this app
  deepLinks    object   { base, params[], example }
  requiresWallet bool
  module       string   Name to register in window.BitClawV2Modules (used by shell dynamic loader)
  requires     string[] Builtin modules to preload: ['mindmap','taskboard','dns',...]
                        liquid_fast uses this for smart preload when /d/<name> opens your app
  permissions  string[] Subset of ["store","ws","navigate"] — see section 2. Absence
                        (or an old manifest published before this existed) = base
                        bridge only. Shown to users in the Install confirmation
                        dialog before they install, so only declare what you use.

TX outputs to appear in Browse list:
  [0] OP_RETURN ML|<appId>|1|1|<JSON>   (0 sat)
  [1] addressFromHashtag('#APPS')        (1 sat)  ← registration
  [2] addressFromHashtag('#cat_tools')   (1 sat)  ← category (optional)
  [3] change

Build App scans #APPS history → parses ML| records → Browse tab.
WOC confirmation time: ~10 min. After confirming, appears in Browse.
(There is also a 0-conf fast path: Browse watches #APPS over UMS, so your app
usually shows a "🆕 just published" card within seconds of broadcast.)

Identity & updates (anti-hijack):
- The FIRST record seen for an appId fixes that appId's authorAddr claim.
  Later ML| records for the same appId from a DIFFERENT authorAddr are
  rejected — by the apps indexer and by clients' chain-scan fallback alike —
  and surfaced as a "⚠ contested" badge. Nobody can take over your appId,
  IF you declared authorAddr in your first publish. Declare it.
- To ship an update: re-publish the SAME appId from the SAME authorAddr with
  a new main/mainChunks + version. Users who installed your app get an
  "⬆ Update available" badge in Build App → Installed and update in one
  click. There is NO auto-update — users always confirm.

After publishing ML manifest to #APPS:
1. Any user opens Build App → Browse → finds your app
2. Clicks Install → stored in bc.settings.installed_apps (localStorage + EK on-chain sync)
3. Sidebar shows: Apps section → [Tamagotchi][PixelPlot][MindMap] + YOUR APP ICON
4. User clicks → shell loads your code (single TX or reassembled from mainChunks)
   into a sandboxed iframe → mount(root, ctx) with the Sandbox API v1 ctx from
   section 2 above — NOT full ctx.bitclaw. "Open App" never falls back to an
   unsandboxed page, no matter how big your app is.

app-{id} route → ctx.params available → deep links INTO your app work:
  /v3/app-my-module/itemId  → ctx.params = ['itemId']
(ctx.navigate/setParams need the "navigate" permission — see section 2 —
without it your app can only read its initial params on mount, not push the
user to a different route.)

The sidebar item shows: icon + name (first 14 chars).
Builtins (tamagotchi, pixel, mindmap) are always shown; yours appears below them.

ctx.bitclaw.util.addressFromHashtag(tag) is safe ONLY for the small set of
well-known, fixed public tags (#APPS, #cat_tools, #cat_finance, ...), the
same ones this Publish tab writes to. It uses one-level BIP32 derivation
(djb2 hash) which collides ~22% of the time on short/dynamic strings, so
NEVER invent your own dynamic tag with it (no '#geo_<hash>', no per-item
'#item_<id>' via this call).

For per-item / per-user / geo anchors, use the bridged two-level sha256
derivation instead — no permission needed, these are part of the base bridge:
  await ctx.bitclaw.util.geoAnchor(geo.slice(0,4))
  await ctx.bitclaw.util.dnsAnchor('my-app')
  await ctx.bitclaw.util.appAnchor('item_' + itemId)   // scoped to YOUR app only

Prefer appAnchor for anything purely internal to your own app (per-item, per-
board, per-room feeds) — it's automatically namespaced to your installed appId,
so you can reuse simple tags like 'item_42' without worrying about colliding
with another app's anchors for the same tag.

CD|<id>|1|1|<JS code>          — your module code (Deploy Code tab,
                                    auto-chunked into multiple CD| TXs if >90KB,
                                    manifest.mainChunks: [txid, ...])
  ML|<id>|1|1|<JSON manifest>    — your app manifest (Publish tab)

Records OTHER users may write about your app (all on the per-app anchor
#app_<first 12 chars of your ML txid> — read them with fetchHistoryWithData):
  ATTEST|<appTxid>|<up/down>|<comment>|<ts>|<attesterAddr>
                                 — community attestation, shown in your app's
                                    detail view. Social signal only, never a gate.
  APP_INSTALL|<appId>|<ts>       — anonymous install ping (queued as an optional
                                    Outbox draft on install), counted into the
                                    "⬇ N" installs figure in Browse.
  ATP|...                        — paid boost records (see Boost button).

Your own runtime code can still write ANY OP_RETURN string via
ctx.bitclaw.outbox.addDraft({ record: '...' }) — the bridge doesn't validate
record contents, only which read METHODS you can call. Without the "ws"
permission, other apps/services can't reach you over UMS to react to your
custom record types in realtime — they'd need to poll chain history instead.
Most of BitClaw's other on-chain record types (WORKER_REG, DN|REG, MM_EDIT...)
aren't things your sandboxed code can usefully act on regardless — they're
for first-party modules that have the matching
bc.* service to go with them.

/v3/app-my-module/itemId   → ctx.params = ['itemId']   (works)
/v3/app-my-module/a/b      → ctx.params = ['a', 'b']    (works)
ctx.navigate(...) from inside your app       (needs "navigate" permission, section 2)

Handle incoming params in mount():
  mount(container, ctx) {
    const [itemId] = ctx.params || [];
    ...
  }

This is something YOU do once, from the Publish tab, when you publish —
Build App itself is a first-party module with real bc.dns, so it can call
bc.dns.register('my-app', 'manifest', appTxid, 365) on your behalf. It is
NOT something your deployed app's own sandboxed code can call for its users
at runtime (no bc.dns bridge there). Once registered, 1bitclaw.com/d/my-app
opens your app for anyone.

- Starter kit: 1bitclaw.com/dev/template.zip — module skeleton + a local
  harness whose mock bridge mirrors THIS contract (same methods, same error
  strings, same permission gating). TypeScript types: 1bitclaw.com/dev/bitclaw.d.ts.
  Example apps with sources: 1bitclaw.com/dev (Tooling section).
- Uncaught errors in your app are reported to the host page (window.onerror →
  BC_APP_ERROR) and shown to the user as an "app crashed" banner instead of a
  silently blank iframe — still ship your own try/catch UX for anything you
  can handle gracefully.
- Author validation: authorPfId must be in bc.profiles.list()
- Large modules: auto-chunked at 90KB per TX (GZip + CD|id|total|index|payload)
  — shell now assembles mainChunks in the sandboxed path, so size is not a
  reason to lose sandboxing
- Wallet modes (for the USER installing your app): WIF (local sign) or Yours
  Wallet (external sign) — irrelevant to your sandboxed code, which never
  sees a key either way
- This spec, 1bitclaw.com/dev, and shell.js's BC_READ_ALLOWLIST should always
  agree — if you find a mismatch, the allowlist in shell.js is the actual
  ground truth; please report the doc drift

4.Local testing

Two complementary harnesses — use both before publishing:

5.Tooling: starter, types, CLI, examples

6.Run a service — earn sats

The client is only a viewer: every record lives on-chain. The infrastructure that serves that data — snapshot indexers, chain-reader nodes, the realtime relay, app workers — is open for anyone to run, and priority subscribers pay the operator. This is the operator mirror of the app path above: same "download a kit, follow the steps" shape, aimed at people who want to host, not publish an app.

The four roles

5-minute quickstart

📦 Download infra-kit.zip the whole infra/ kit — indexer/relay/worker, Docker compose, register.mjs, validators, presets, and the full README.md. No secrets inside; scanned on every build.

1. Get the kit. Download and unzip the button above. Everything below runs from the infra/ folder.
2. Provision keys — in your browser. Open BitClaw → Run Agent → 🛰 Control Room → My Infrastructure → + Provision. It derives a scoped worker key (your master WIF never leaves the browser), asks the few business choices (kind / geo shard / tariff), and hands you a ready .env. Save it as infra/.env, then fund the shown worker address with a few thousand sats.
3. Validate. node infra/validate-env.mjs — catches missing/typo'd vars before you spend anything.
4. Run. cd infra && docker compose up -d indexer (or plain node infra/indexer/server.mjs). Health: curl localhost:8080/health.
5. Register on-chain. docker compose run --rm register → you appear in every user's Network panel under "Discover from chain", tariff shown on your 💳 button.
6. Verify. OPERATOR_ADDR=<addr> SERVICE_ID=<id> node infra/verify-registration.mjs.
7. Earn & monitor. Subscribers' SUB payments land at your worker address; the live tariff is served from /health, so repricing is just a restart. Watch subscribers + revenue in Control Room → My Infrastructure. Kill-switch: spend the liveness-coin from that panel and the box halts in <1s.

The Provision step also writes the exact .env for you — the quickstart works end-to-end from a machine that has never seen this repo. The bundled README.md is the full server-side reference (federation, geo-sharding, premium anchors, self-hosted UMS).

Kind presets (KIND_PRESET=)

One env var wires a complex kind the way the production indexers do: market social taskboard apps profiles agents dns mindmap contracts ordinals pixel tamagotchi bookstore kb games map. Empty = fully custom (you list anchors yourself). The live list any indexer serves at GET /presets is the source of truth.