For builders

Speak to the chain like the clients do.

A Swimchain node is a single Rust binary. It exposes JSON-RPC 2.0 over HTTP, verifies Argon2id proof-of-work on every write, and prunes anything the network stops caring about. Everything below is what our own eight clients use — there is no private API.

1 · Run a local dev node

Regtest is the local development mode: PoW difficulty drops to a minimum (a few dozen hash attempts), level checks are bypassed, and many read methods are auth-exempt. Data lives in an isolated -regtest directory.

$ cargo build --release $ ./target/release/sw --regtest identity create $ ./target/release/sw --regtest node start --listen 127.0.0.1:29735 RPC server listening on 127.0.0.1:29736

The JSON-RPC port is always P2P port + 1. Health check: GET /health.

2 · The write path

Every write follows the same shape. Get the bytes right and the node accepts you; get them wrong and it rejects you — there is no partial credit.

Compose the content bytes. Posts hash title\n\nbody; replies hash the body alone; engagements use the parent's raw 32-byte hash (not the sha256:… string).
Mine the challenge. Argon2id over an 82-byte canonical challenge + nonce. Config must match the node's network: regtest 1 MiB/1 iter, testnet 8 MiB, mainnet 64 MiB (SPEC_03).
Sign the request. Ed25519 headers: X-CS-Identity, X-CS-Timestamp, X-CS-Signature over swimchain-rpc:<method>:<sha256(params)>:<timestamp>.
Submit and verify. Call submit_post / submit_reply / submit_engagement, then read your content back — acceptance means it is retrievable, broadcast, and in the block builder.

3 · Core RPC methods

Method	What it does
get_info	Node version, network, peer count, block height.
create_space	Create a space (community). PoW over the space name.
submit_post	New thread in a space. PoW over `title\n\nbody`.
submit_reply	Threaded reply. PoW over the body.
submit_engagement	Reaction / preservation work. Raw-hash PoW challenge; resets the parent's decay clock.
get_content · get_replies	Read content and threads, with decay state and heat.
get_reactions · get_pool_for_content	Reaction counts and engagement-pool status.
search	Full-text search over the node's indexed content (Tantivy).
sign_message	Sign with the node identity — how keyless browser clients authenticate writes.

4 · Prove it against a real node

The repo ships an end-to-end write-path suite that boots a throwaway regtest node and drives every client's own rpc/pow modules through post → mine → sign → accept → read-back. If your client can pass it, your writes are real.

$ cd tests/e2e-write-paths && npm install $ npm test Test Files 6 passed (6) · Tests 19 passed (19)

Specs live in specs/ (SPEC_01–SPEC_13), design rationale in VISION.md and the thesis documents. WASM bindings for browser crypto (Ed25519, SHA-256, Bech32m) are in swimchain-wasm/.