Developer Integration Guide

Running Node (VPS 93)

RPC/TLS: https://127.0.0.1:8645 (loopback only, self-signed)

P2P: 3737/tcp (public, no action needed for the website)

Auth: Mining RPC uses attestation tokens (Bearer) for capability lantern-mining. Do not inject the admin token into public browser requests.

Recommended proxy: run the included Weave server (node server.js) and reverse-proxy it with Caddy/Nginx. The server enforces an RPC method allowlist and forwards the miner's Bearer token through to Lantern.

Key RPC Endpoints

• POST /api/lantern/rpc — JSON-RPC proxy to Lantern /rpc (method allowlist).
• POST /api/lantern/weave/attest/nonce — request attestation nonce.
• POST /api/lantern/weave/attest — submit attestation and receive a mining Bearer token.
• GET /api/miner/attestation — optional: server-supplied manifest/signature for web miners.
• POST /api/weave/gossip/session — exchanges a Bearer token for an HttpOnly cookie session (for browser SSE).
• GET /api/weave/gossip/stream and POST /api/weave/gossip/publish — gossip relay (public by default; optional bearer auth via server env).
• GET /api/weave/mailbox/config, POST /api/weave/mailbox/store, POST /api/weave/mailbox/drain, POST /api/weave/mailbox/ack — encrypted offline delivery mailbox with signed request auth and persisted queue state.
• POST /api/weave/report — signed abuse-report ingestion queue for moderator review workflows.

Gossip Relay Auth (Optional)

By default, gossip relay is open (no token). To require auth, set WEAVE_GOSSIP_TOKEN in the server.js runtime (or fallback to LANTERN_HTTP_TOKEN).

For stronger cookie signing separation, set WEAVE_GOSSIP_SESSION_SECRET (otherwise signatures derive from the gossip token).

• POST /api/weave/gossip/session: send Authorization: Bearer <WEAVE_GOSSIP_TOKEN> to mint a cookie-backed session for browser clients.
• POST /api/weave/gossip/publish and GET /api/weave/gossip/stream: use the cookie session (or direct bearer for non-browser clients).

Optional browser bootstrap: set window.__WEAVE_GOSSIP_BEARER__ at runtime (not in repo files), then the app will call /api/weave/gossip/session automatically.

Do not embed gossip secrets in static HTML or query strings.

Rate Limits & Bodies

Defaults: jobs 30/min, shares 60/min per token/IP; max body 512 KB. Keep request sizes small and reuse a session token to avoid throttling.

Mailbox Delivery

Weave’s offline chat/like path stores only end-to-end encrypted packets. Browsers sign mailbox requests with the profile identity key, and the server verifies the peer id plus a local proof-of-work identity stamp before accepting queued mail.

Queued mailbox state is persisted to data/weave-mailbox.json by default. Tune retention with WEAVE_MAILBOX_TTL_MS, WEAVE_MAILBOX_MAX_PER_PEER, and WEAVE_IDENTITY_STAMP_MIN_BITS.

Safety Queue

Client-side block/hide/report actions remain local-first, but the site can now accept signed report bundles through /api/weave/report and persist them to data/weave-reports.json for operator review.

Use WEAVE_ADMIN_TOKEN with /reports or npm run report to review and resolve queued reports. The public status API and /api/metrics expose mesh, mailbox, TURN, and report-queue counters so launch checks can verify that the P2P bootstrap layer is actually healthy.

Use npm run backup:state before maintenance, npm run backup:prune for retention, and npm run restore:state -- --from <backup-dir> --force when you need to roll mailbox/report/indexer state back to a known-good snapshot.

Recommended Flow

1. Browser calls /api/lantern/rpc → getMiningJob. If it fails with missing bearer, run attestation.
2. Browser requests /api/lantern/weave/attest/nonce and then /api/lantern/weave/attest to obtain a Bearer token (or run Lantern with MINING_OPEN=1 for open testnet mining).
3. Browser retries getMiningJob with Authorization: Bearer <attestation_token>.
4. Miner searches for a nonce and submits shares via submitShare (include miner address; include attestation if required).

Example (server-side curl)

curl -sk https://127.0.0.1:8645/rpc \
  -H "Authorization: Bearer <ATTEST_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getMiningJob","params":{"payout":"<tpc...address>"}}'

curl -sk https://127.0.0.1:8645/rpc \
  -H "Authorization: Bearer <ATTEST_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"submitShare","params":{"id":"<job_id>","nonce":123,"miner":"<tpc...address>","attestation":"<ATTEST_TOKEN>"}}'

Config Knobs (Lantern)

• LANTERN_HTTP_BIND — keep at 127.0.0.1:8645 for safety.
• MINING_OPEN — when 1, allows open mining (no attestation/allowlist). Useful for early testnet.
• MINING_NONCE_STRIDE — nonce lane stride (default 65536).
• MINING_JOB_RATE_PER_MIN, MINING_SHARE_RATE_PER_MIN — tune rate limits.

Web Hosting Notes

Serve the static site via node server.js (or any web server). For public deployments, terminate TLS at the edge (Caddy/Nginx) and reverse-proxy to the Weave server. Avoid any config that injects LANTERN_HTTP_TOKEN into public paths.

Upstream TLS verification to Lantern is enabled by default. Keep it enabled for testnet/prod; only use LANTERN_UPSTREAM_TLS_INSECURE=1 for local development.

Pre-launch checks: run WEAVE_RELEASE_MODE=testnet npm run preflight and npm run smoke:local in this repo.

For testnet release configuration, copy .env.testnet.example, fill values, and set secrets on deployment host.