Midstate is a post-quantum blockchain. It signs with hash-based one-time keys (WOTS) instead of elliptic curves, and that single decision shapes everything about how you write code against it.

Here is the rule that matters more than anything else in this guide:

A signing key on Midstate is a consumable. Use it twice and you lose the coins.

Not “lose privacy”. Not “get a warning”. The node ships a Key Reuse Punishment Burn Protocol that lets any observer burn funds sitting at a WOTS key that signed twice. The SDK is built so you cannot trip that by accident, which is why some of its API looks unusual at first.

This guide starts with code you can run offline in about two minutes, then works up to sending real money.

Part 1: Play offline first (no network, no coins, no risk)

The fun parts of this SDK run with zero network access. Start here.

mkdir midstate-play && cd midstate-play
npm init -y
npm pkg set type=module
npm install midstate-sdk

Now make play.mjs:

import { fileURLToPath } from 'node:url';
import { readFile } from 'node:fs/promises';

// 1. Load the WASM core. Nothing works before this.
const wasmPath = fileURLToPath(
  import.meta.resolve('midstate-sdk/pkg/wasm_wallet_bg.wasm')
);
const wasmBytes = await readFile(wasmPath);

const wasm = await import('midstate-sdk/pkg/wasm_wallet.js');
await wasm.default({ module_or_path: wasmBytes });

// 2. Compile a contract.
const { compile } = await import('midstate-sdk/compiler');
const { execute } = await import('midstate-sdk/vm');

const src=/__u/ciphernom.substack.com/%60%7B var a = 2 + 3; assert(a == 5); } true;`;
const c = compile(src);
console.log('bytecode:', c.bytecode);
console.log('size:', c.sizeBytes, 'bytes | sigops:', c.sigops);

// 3. Run it.
console.log(execute(c.asm, {}));
// { ok: true, stack: [ '01' ], steps: 7, error: null, trace: [] }

Run it:

node play.mjs

That is a real Midstate contract, compiled to real bytecode, executed on a real (headless) VM. No node, no wallet, no waiting.

Worth knowing early. The subpath imports (midstate-sdk/compiler, /vm, /pump, /launcher, /bincode) never touch the network layer. Importing the package root pulls in libp2p and its whole transport stack. For contract or curve work, use the subpaths and keep it light.

Curve math, also offline

const L = await import('midstate-sdk/launcher');

// Linear bonding curve: price equals current supply.
L.curveBuyCost(0n, 5n);     // 10n  (0+1+2+3+4)
L.curveSellRefund(5n, 5n);  // 10n  (exact mirror, so a round trip is lossless)

// Constant-product AMM with the 0.3% fee.
L.getAmountOut(1000n, 1000n, 100n);  // 90n

Everything is BigInt. No floats anywhere in the money path, on purpose. The on-chain contract asserts in integers, and a quote computed in floating point lands one unit on the wrong side of that assert and gets rejected after you have already paid for a commit.

Part 2: The WASM init gotcha

This is the number one first-run failure, so it gets its own section.

new Wallet(...) builds a WASM-backed object in its constructor. If the runtime is not initialised you get an opaque binding error, not a helpful message.

import { Wallet } from 'midstate-sdk';

// ALWAYS do this first.
await Wallet.init(wasmBytes);               // Node: a Buffer
await Wallet.init('/wasm_wallet_bg.wasm');  // Browser: a URL

Wallet.init() is a thin wrapper. If you manage the WASM instance yourself (bundler-injected, streaming-compiled, shared across workers), import initWasm or initWasmSync from the package root instead.

Part 3: Wallets and storage

A wallet is a 24-word phrase plus a storage provider.

import { Wallet, Storage } from 'midstate-sdk';

const store = new Storage.NodeFSStorage('./wallet-data');

const wallet = await Wallet.create(store);
console.log(wallet.phrase);   // 24 words. Back this up. Only recovery path.

// Later, same machine:
const wallet = await Wallet.restore(store);

// Or open an existing seed:
const wallet = await Wallet.create(store, 'word word word ...');

Three providers ship in the box:

To store elsewhere, subclass StorageProvider and implement four methods: saveMetadata, loadMetadata, saveMssTree, loadMssTree.

The split matters. Metadata is a JSON blob. Merkle signature trees are binary and can run to megabytes, which is why the browser provider puts metadata in localStorage and trees in IndexedDB.

Do not stub out saveMssTree. Next section explains why.

Part 4: Addresses, or “how to not lose money”

Two address types. Picking wrong is the mistake that costs users funds.

WOTS: single use, instant

const addr = await wallet.getNewAddress();

A Winternitz one-time address. Spend from it once and the key is public forever. Generate a fresh one per incoming payment. Think of it as a Bitcoin invoice address that self-destructs after use.

Derivation is instant, so there is no reason to ever reuse one.

MSS: reusable, but on a budget

const addr = await wallet.getNewReusableAddress(10, (done, total) => {
  process.stdout.write(`\rgenerating ${done}/${total}`);
});

An MSS address is a Merkle tree over 2^height one-time keys. “Reusable” means each spend consumes a different leaf. It is a finite signature budget, not an unlimited key.

Height 10 gives you 1,024 signatures. Ever. Then the address is spent out.

Two things to design around:

1. Generation cost is exponential. Height 10 is about 1,024 keypairs and takes a moment. Height 20 is about a million and is the slowest thing the wallet does. That is why the progress callback is in the public API rather than hidden. Put a spinner on it.

2. The tree must be persisted or the address is receive-only. It cannot be cheaply regenerated. The SDK writes the tree to storage before recording the address as usable, so a crash mid-generation cannot leave you with an address that accepts funds and can never spend them. A storage provider that silently drops saveMssTree builds exactly that trap.

Rule of thumb: MSS for anything published or long-lived (donation address, mining payout, contract counterparty). WOTS for everything else.

Units are binary, not decimal

import { MidstateUtils } from 'midstate-sdk';

MidstateUtils.formatMDS(2048);  // { value: '2',   prefix: 'kMDS' }
MidstateUtils.formatMDS(500);   // { value: '500', prefix: 'MDS'  }

1 kMDS is 1024 MDS, not 1000. Then mMDS at 1048576 and gMDS at 1073741824. Use the formatter instead of dividing by 1000 and wondering why the numbers drift.

Balances are BigInt:

wallet.getBalance();        // spendable
wallet.getLockedBalance();  // real, yours, but pinned by reuse risk (Part 8)

Part 5: Connecting to the network

One client class, two transports. The constructor picks based on what you hand it.

import { MidstateClient } from 'midstate-sdk';

// HTTP: simplest, works everywhere.
const client = new MidstateClient('https://rpc.cypherpunk.gold');

// P2P: TCP under Node, WebRTC in the browser.
const client = new MidstateClient(['/dns4/some-node/tcp/4001/p2p/12D3KooW...']);
await client.connect();

Anything containing /p2p/, or any array, is treated as multiaddrs. Everything else is an HTTP base URL. Every read method works identically on both, so you can build against HTTP and switch later without touching call sites.

const state = await client.getState();
// { height, block_reward, required_pow, header_hash, ... }

await client.getBlock(height);
await client.getMempool();
await client.checkCoin(coinIdHex);
await client.checkCommitment(commitmentHex);

Push events are P2P only

client.onPushEvent(evt => {
  if (evt.NewBlockTip) console.log('new tip', evt.NewBlockTip.height);
  if (evt.ChatMessage) console.log('chat', evt.ChatMessage);
});
client.onStatusChange(s => console.log('link:', s));

Call onPushEvent on an HTTP client and you get a console warning and nothing else. If your app needs live tip notifications (a miner, a wallet reacting to reorgs, a live order book), you need P2P.

The P2P client reconnects on its own, up to 5 attempts with a growing backoff, and discovers extra peers from the first one it reaches.

Part 6: Syncing

Midstate wallets scan with compact block filters. Fetch one filter per block, test it locally against your watched addresses, download only the blocks that match.

const result = await wallet.sync(client, {
  gapLimit: 20,
  onProgress: p => console.log(`${p.height}/${p.chainHeight}`),
  onReorg: r => console.warn('reorg healed', r),
});

// { height, found, balance, lockedBalance, utxos, reorg,
//   wotsDerived, highestUsedWots, gapPasses, filterCacheHits, fullScan }

Leave the pacing defaults alone unless you have measured a reason. filterIntervalMs defaults to 550ms and batchSize to 1000. The node budgets expensive requests (filters and block templates share one allowance) at roughly 120 per minute for a fresh peer, and 20 violations earns a 500-second ban. The defaults sit inside that.

About gapLimit. It defaults to 0, meaning no gap scanning: only addresses you already generated get detected. Restoring from seed needs a gap limit, and the SDK refuses a partial scan it cannot trust:

await wallet.sync(client, { gapLimit: 20 });
// Throws if the wallet has never scanned from genesis:
// "indices used below that height are invisible and the walk can stop
//  early with a too-small balance."

That error is doing you a favour. A confidently wrong, too-small balance is the worst possible failure, because nothing signals that anything was missed.

Gap scanning is adaptive. It widens the address window, re-scans, widens again, and repeats until a pass finds nothing new (capped by maxGapPasses, default 12). Filters are cached between passes, so this is far cheaper than it sounds.

Part 7: Sending money

This is the part that looks strangest and matters most.

Every spend is split in two:

1. Commit. Publish H(input_coin_ids || output_hashes || salt): one 32-byte hash, with a client-mined proof-of-work of 24 leading zero bits, rising as the commit pool fills. It says nothing about which coins you are spending or where they are going.

2. Reveal. Publish the real inputs, outputs and witnesses. The node recomputes the commitment from them and rejects the transaction unless that exact commitment is already registered.

In the node’s own words, the commit “blinds the inputs being spent behind a commitment hash, preventing front-running”. Concretely, that buys two things.

Witness secrets are useless to onlookers. Midstate’s HTLC and limit-order covenants are authorised by a hashlock rather than a signature: the claim path lets anyone spend the coin provided they present the preimage. A reveal that claims one therefore publishes the secret. Without phase 1, an observer could lift that secret from your mempool transaction and broadcast their own claim at a higher fee. With it, the winner was already fixed before the secret was visible, because your commitment was registered and theirs was not.

Outputs cannot be substituted. The commitment covers inputs and outputs. A competing transaction spending your coins to a different destination hashes to a different commitment, which is not in the commitment set, so the node rejects it outright. The mempool does support replace-by-fee, but a replacement still needs its own registered commitment.

What the two phases are not for

It is tempting to assume phase 1 exists because publishing a hash-based signature is itself dangerous. It is not, and the distinction matters.

A Winternitz signature reveals hash-chain intermediates at depths set by the message digits. Forging a different message requires every digit to be greater than or equal to the one you observed. Raising a message digit lowers the checksum, and the checksum chains only run forwards, so one signature is not forgeable. Grinding five million candidate messages against a single signature produces zero forgeries; remove the checksum and they start appearing.

What is fatal is two signatures from one key over two different commitments. The node merges them, keeping the shallowest revealed depth in each chain, and that composite can be ground into a working forgery. That is exactly what the Key Reuse Punishment Burn Protocol does, automatically, the moment it sees the second signature.

So the danger is reuse, not disclosure. Publishing a signature is fine. Publishing a second one from the same key is what costs you the coins.

One call drives the whole dance:

const resp = await wallet.send(client, recipientAddrHex, 1000n);
// { ok: true, body: null }   or   { ok: false, body: '<reason>' }

Note the return shape. It is { ok, body }, not a transaction id.

You can also burn data onto the chain in the same transaction:

await wallet.send(client, addr, 1000n, '48656c6c6f', 0n);
//                                     ^ hex payload  ^ MDS burned alongside

Budget for the latency

Under the hood, send() builds the spend, mines the anti-spam PoW at the current required_pow, submits the commit, then polls checkCommitment every 10 seconds for up to 120 tries. That is a 20-minute ceiling.

Consensus actually permits a Commit and its Reveal in the same block. The SDK waits anyway, because a light client cannot make a miner include both, and a reveal whose commitment never lands is simply rejected.

A Midstate send is not a sub-second operation. A progress bar stuck on “sending...” for ten minutes reads as a hang, so tell your users what is happening.

Failure modes are unusually well behaved

Knowing these lets you write better handling than a blind retry.

Commit never mined. Nothing is at risk. Commits neither lock nor modify UTXOs, the reveal was never built, no signing key was touched. You lost the PoW effort. Retry freely, and the SDK’s error message says so explicitly.

Reveal broadcast, then orphaned. This is the dangerous one, though not for the reason people assume. The SDK keeps the signed reveal and re-broadcasts the exact same bytes.

Signing again is not itself the problem. WOTS signing is a pure function of key and message, so signing the same commitment twice yields byte-identical output, and the burn protocol’s trigger is wots_pk matching while commitment differs. Same key over the same commitment is not reuse and never was.

The problem is that rebuilding a transaction almost never reproduces the same commitment. A fresh salt, a different fee, a different input ordering or a new change output all change H(input_coin_ids || output_hashes || salt), and now you have two signatures from one key over two commitments, which is exactly what gets merged into a forgery. Storing the bytes removes the chance to drift.

Other spend shapes

// Sweep every coin at one address into one output (needs 2+ coins, max 8192).
await wallet.consolidate(client, sourceAddr, destAddr);

// Sweep scattered coins across many addresses into one destination.
await wallet.defrag(client, destAddr, 50);

// Fund many addresses in one commit/reveal round trip.
await wallet.fundMany(client, [{ address: a, amount: 100n }]);

Part 8: Surviving reorgs

Because a burned key cannot be un-burned, reorg handling here is safety-critical rather than housekeeping. Wire it up once at startup:

const stop = wallet.autoReconcile(client, {
  onReorg:   r => console.warn('rolled back to', r.fork),
  onRecover: r => console.log('re-broadcast:', r.status),
  onChat:    m => renderChat(m),
  onTip:     t => updateUI(t),
  onError:   e => report(e),
});

stop();  // unsubscribe

This needs a P2P client, since it feeds on push events. It subscribes, detects forks, rolls back, and finishes any re-send a rollback armed.

The bounds are exported so you can reason about them:

import { REORG_DEPTH, COMMITMENT_TTL } from 'midstate-sdk';
// REORG_DEPTH    = 200   blocks of history retained for precise healing
// COMMITMENT_TTL = 1000  blocks a commitment survives (about 16.7 hours)

When a spend gets orphaned, the SDK resolves it one of three ways:

• Signed reveal still held, still within TTL: re-broadcast the identical signature. Safe and automatic.

• The original commitment can no longer be replayed (expired from chain state, or an input coin is gone): the coins come back reuse-locked. Moving them would now require a new commitment signed by an already-published key, which is the fatal case. They appear in getLockedBalance(), never in getBalance(), coin selection cannot reach them, and you get an alert explaining why.

• MSS inputs: no per-key cliff, since each spend used a distinct leaf. Restored normally.

One more startup call worth making

await wallet.reconcileMssLeaves(client);

Your local MSS leaf counter is a guess at how much of a tree has been consumed. It can fall behind if the same seed ran on another device, or if you restored an older backup. When it does, you sign with a leaf the chain has already seen.

That failure is nasty because it is invisible at submission and permanent afterwards. The mempool accepts the transaction, then every new block evicts it, forever. From your side it just never confirms, and retrying never helps, because each attempt signs with the same exhausted leaf.

One call, one lookup per address, counters only ever move forward.

Part 9: Contracts

Midstate has a stack-based contract VM. The workflow is fixed and the order is not negotiable.

import { compile, simulateContract } from 'midstate-sdk';
// lighter: 'midstate-sdk/compiler' and 'midstate-sdk/vm'

const { bytecode, asm, sizeBytes, sigops } = compile(source);

// SIMULATE BEFORE YOU FUND ANYTHING.
const result = simulateContract(compile, source, ctx);

Note simulate takes the compile function as its first argument.

A contract address is BLAKE3(bytecode). Fund an address whose script can never be satisfied and the coins are gone. No admin key, no upgrade path, no recovery. Simulation turns “I think this covenant unlocks” into “I ran it and it unlocked”.

Limits to design within:

• MAX_SCRIPT_SIZE is 1024 bytes

• MAX_SIGOPS_PER_SCRIPT is 3

• the compiler caps simulated stack depth at 64

• state threads activate at height 65,000

• OP_SUM_INPUT_VALUE activates at height 300,000

Two traps that will bite you

Trap 1: CHECKSIG in the simulator is fake. It compares strings. The real VM verifies a WOTS or MSS signature. A contract that “passes” simulation on signature checks has proved nothing about authorisation. Use the simulator to prove arithmetic and state, which is where bonding-curve and AMM bugs actually live.

Trap 2: Confidential outputs are not confidential. The name is vestigial. An earlier design had zk-STARK confidential transactions, those were removed, and state threads inherited the variant. Its value is known to be zero, not hidden. It carries a 32-byte data commitment: data, not money.

This has already caused an incorrect fix in the node and there is a regression test guarding it. If you are checking value conservation, count state-thread outputs as zero. The simulator will reject a state output that also carries value, because consensus does too.

Endianness will get you

Three different byte orders live in this SDK, and mixing them fails silently rather than loudly:

Get it backwards in contract state and a balance of 10 reads as an astronomically large number, so a conservation assert passes or fails for reasons that look nothing like the actual bug. Use encodeState and decodeState rather than packing bytes by hand.

Part 9b: Midscript, the contract language

Contracts are written in Midscript. It looks like C, and that is a trap: it is a stack machine wearing C syntax. Get that one thing straight and the rest follows quickly.

Bare expressions push

A statement that is just a value pushes it. This is the single most important difference from every language the syntax reminds you of:

10; 20; add();          // push 10, push 20, add -> [30]
pick(8);                // copy the item 8 deep to the top
assert(pop_int() == 3);

var does not pop. It claims a stack slot and remembers where it is, and the compiler emits PICK to reach it later. That is convenient right up to the moment it is not: your own pump contract carries the warning that the stack discipline for CHECKSIGVERIFY is fragile “because var claims stack slots without popping, so the signature has to be the top of stack at exactly the right moment.”

Declarations

let is a compile-time constant, substituted at every use and costing nothing at runtime. var is a stack local.

let TREASURY = "aa00...aa";    // constant, inlined
var supply = pop_int();        // stack local
supply = supply + 1;           // reassignment is fine
var supply = 2;                // ERROR: shadowing is forbidden

state declares a byte layout over the contract’s input state. Field access compiles to READ_INPUT_STATE plus a SLICE, and fields of 8 bytes or under come back as integers:

state Curve { supply: 8, padding: 24 }

assert(Curve.supply == 10);    // reads bytes 0..8 of input state

struct is the same declaration for layouts that are not the input state.

Control flow

if / else if / else work as expected. repeat(n) is an unrolled loop and n must be a literal, since the bytecode has no jumps to loop with:

repeat(3) { merkle_step(); }   // fine
var n = 3; repeat(n) { }       // Syntax Error: Expected NUM

route is the one to learn. It dispatches on the value already on top of the stack, which is how the witness selects a spending path:

route {
  case 0: { require_sig(OWNER_PK); }
  case 1: { require_time(500000); require_sig(HEIR_PK); }
  default: { fail(); }
}

switch (expr) { ... } is the same thing with an explicit subject. Always give a route a default, and make it fail() unless you mean otherwise.

Builtins

About thirty, in four groups.

Stack: dup, drop, swap, over, rot, pick(n), peek, size, slice, concat, pop_int, pop_hex.

Note that bare pop() is a deliberate compile error telling you to pick a typed one. Untyped popping is how you end up comparing a length against a hash.

Math: add, sub, mul, div, plus infix + - * / % and comparisons == < > <= >= and && ||.

There is no !=. The lexer does not know ! at all, and you get Unknown char '!'. Invert with if/else or restructure the assertion.

Guards (these VERIFY and abort on failure): require_sig, require_preimage, require_time, require_transfer, require_length, require_timelock, require_signed_by, require_funds_transferred, verify_gte, fail. Plus check_sig, which pushes 0 or 1 instead of aborting, so you can count signatures.

Chain intrinsics: this_address, input_value, sum_input_value, sum_to_addr(addr), read_input_state, read_output_state(i), output_address(i), hash.

The standard library is already there

min, max, require_signed_by, require_length, require_timelock, require_funds_transferred, merkle_step and merkle_update_step are prepended to every compile. No import.

merkle_update_step is the interesting one: it verifies an old root and computes the new root in a single pass over the proof. That is the whole trick behind the pump ledger in Part 12, and it costs you nothing to use.

Your own macros work the same way. They inline, their arguments become stack locals, and those locals are dropped afterwards:

macro get_new_supply() { read_output_state(0); 0; 8; slice(); 0; add(); }

Read that as six stack operations, not as an expression. Macros are stack transformers, which is why calling one in expression position (var a = min(7, 3);) does not do what the syntax suggests.

Four contracts worth reading

Each of these compiles and runs today. Sizes are against the 1024-byte limit.

2-of-3 multisig (122 bytes, 3 sigops, the maximum). check_sig returns 0 or 1, so you sum them:

check_sig(PK_A);
swap(); check_sig(PK_B); add();
swap(); check_sig(PK_C); add();
assert(pop_int() >= 2);
true;

HTLC (146 bytes, 2 sigops). The atomic-swap primitive, and the thing Part 7’s commit phase protects:

route {
  case 1: {                      // claim: [sig, preimage, 01]
    require_preimage("5fbf08af2b116ab8f7f3c14b8ec01a46ce23d290e2ebc7a752d0982d54c054f2");
    require_sig(ALICE_PK);
  }
  case 0: {                      // refund: [sig, 00]
    require_time(600000);
    require_sig(BOB_PK);
  }
  default: { fail(); }
}
true;

Dead man’s switch (91 bytes). Three paths, and note the third asserts where the money went, not just who signed:

route {
  case 0: { require_sig(OWNER_PK); }
  case 1: { require_time(500000); require_sig(HEIR_PK);
            assert(sum_to_addr(HEIR_ADDR) == 1000000); }
  case 2: { require_sig(ORACLE_PK);
            assert(sum_to_addr(HEIR_ADDR) == 1000000); }
  default: { fail(); }
}
true;

Linear bonding curve (98 bytes, 0 sigops). The smallest complete stateful contract, and the ancestor of Part 12:

let TREASURY = "aa00...aa";
state Curve { supply: 8, padding: 24 }
macro get_new_supply() { read_output_state(0); 0; 8; slice(); 0; add(); }

assert(sum_to_addr(TREASURY) == Curve.supply);   // paid the right price
assert(get_new_supply() == Curve.supply + 1);    // updated state honestly
true;

Two assertions and there is no other way to spend the coin. That is the shape most useful Midstate contracts take: constrain where the money goes and what the next state says, then stop.

Budgeting 1024 bytes

MAX_SCRIPT_SIZE is 1024 and MAX_SIGOPS_PER_SCRIPT is 3, which sounds tight until you see the numbers. A 2-of-3 multisig is 122 bytes and already at the sigop ceiling. The full pump curve with a 512-slot Merkle ledger is 966. Signature checks, not logic, are the scarce resource.

Useful rules of thumb, all measured:

• each pump Merkle tree level costs exactly 60 bytes

• repeat(n) multiplies its body by n, because it unrolls

• let is free, var costs a stack slot and a PICK per use

• the compiler also caps simulated stack depth at 64

When you run out of room, the answer is usually to move work into the witness and verify it rather than compute it. Checking a Merkle proof is cheap; rebuilding a tree is not.

Part 10: Mining

Mining on Midstate is a Verifiable Delay Function, not a hashrate race. create_extension hashes a midstate || nonce seed and then iterates BLAKE3 one million times sequentially. One nonce costs about 130ms of unavoidable serial work, and no amount of batching changes that.

The only lever is parallelism, and the search is embarrassingly parallel because every nonce is independent.

How much parallelism you get per core depends on where the code runs. The node dispatches on CPU features at startup:

• x86_64 with AVX2: 8 lanes

• aarch64 NEON, dual-issue: 8 lanes

• aarch64 NEON, single-issue: 4 lanes

• wasm32 with simd128: 4 lanes

• scalar fallback: 1

The SDK miner is the WASM path, so it gets 4 lanes, which works out to roughly 15 to 30 nonces per second per worker. A natively-built node on AVX2 hardware gets twice the lanes per core. If you are mining seriously rather than integrating, that gap is the reason to run the node binary.

Only the search uses SIMD. Verification is always scalar, and the 8-way path is bit-identical to two consecutive 4-way calls.

Solo mining

import { Miner } from 'midstate-sdk/miner';

const miner = new Miner(wallet, client, {
  payoutMssAddress: myMssAddress,   // reusable address, for the reasons in Part 4
});

miner.on('template', t => console.log('template at', t.height, 'fees', t.fees));
miner.on('progress', s => console.log(`${s.rate.toFixed(1)} nonces/sec`));
miner.on('found',    f => console.log('hit!', f.nonce));
miner.on('accepted', b => console.log('accepted, reward', b.reward));  // BigInt
miner.on('rejected', b => console.log('rejected:', b.reason));
miner.on('share',    s => console.log('share', s.accepted));           // pool mode
miner.on('error',    e => console.error(e));

await miner.start();
// miner.stop();
// miner.getStats();

Seven events: template, progress, found, accepted, rejected, share, error.

payoutMssAddress is worth setting. Without it the miner consumes a fresh WOTS index per block. Note that a rejected block burns no key material: coinbase addresses are reserved, not committed, until a block is actually accepted.

Use all your cores

import { MinerPool } from 'midstate-sdk/miner-pool';

const pool = new MinerPool({ workers: 8 });   // defaults to cores minus 1
await pool.start();

const miner = new Miner(wallet, client, { searchFn: pool.searchFn });
await miner.start();

MinerPool is Node-only (it uses worker_threads), which is why it is a separate import. Workers take disjoint strides: worker k of n tests base + k*4, base + (k+n)*4, and so on, so the four SIMD lanes inside one call stay contiguous while no two workers ever test the same nonce. Session bases are random, so two independent miners on the same template do not retrace each other either.

searchFn is a deliberate seam. The node ships a full wgpu/WGSL GPU backend that spreads the search across thousands of threads, checkpointing each nonce’s chaining state across dispatches so it never trips the OS GPU watchdog. The SDK does not ship a GPU backend, but searchFn is where one plugs in, and the same seam takes a remote searcher or a test double.

Pool mining

Pool support is built into Miner, not bolted on beside it:

import { PoolClient, libp2pPoolTransport, verifyPoolProof } from 'midstate-sdk/pool';

const pool = new PoolClient(libp2pPoolTransport(p2p));
await pool.connect(poolMultiaddr);

const miner = new Miner(wallet, client, {
  pool,
  poolAddress: myPayoutAddress,
  workerName: 'rig-01',
});
await miner.start();

The behavioural difference matters. A share is not a block. Finding one leaves mining_midstate unchanged, so the template is still valid and the search must continue from the next nonce. Halting is correct solo behaviour, where a hit means the tip moved, but in pool mode it would leave the miner idle until the next network block. Miner flips to continue-on-found automatically when you pass a pool.

verifyPoolProof(addressHex, score, index, proof, rootHex) checks the pool actually has you in its payout Merkle tree rather than taking its word for it.

Why naive miners fail silently

Three properties of the template, all of which the browser wallet got wrong in ways that produce found-then-rejected blocks:

1. Grind on mining_midstate, never post_tx_midstate. The node’s own comment calls grinding the wrong one “the bug that silently rejected every block the web wallet ever mined over WebRTC”. verify_extension recomputes from the header hash on receipt, so a nonce found against anything else simply does not validate.

2. Templates expire and the timestamp is locked inside the hash. finish_template locks the timestamp into the header before computing mining_midstate, precisely so it cannot be bumped post-grind. But validate_timestamp requires a new block to beat the median of the last 11 blocks, and at a 60-second target that median trails the tip by about five blocks. A template older than roughly five minutes yields a block rejected on arrival, and there is no fix except abandoning it. The SDK refreshes on every tip change and at a hard TEMPLATE_MAX_AGE_MS of 120 seconds.

3. Coinbase total must equal block_reward + total_fees exactly. Anything else is a CoinbaseTotalMismatch. Fees are only knowable from a template, and a template needs a coinbase, so the first request of a session is a guess. The SDK carries expected_total forward between templates, so it guesses right after the first block instead of eating a round trip every time.

Part 11: The chat bus

Calling this “chat” undersells it. It is a dictionary-bound P2P message bus, it is not on chain, and human conversation is the smallest thing it carries.

Messages gossip as Message::ChatV2 frames between peers. They never enter a block, never touch the UTXO set, and are not replayable from history. Anti-spam is a small client-side PoW, about a million hashes, under 50ms on a Pi-class core.

import { MidstateUtils, CHAT_DICTIONARY } from 'midstate-sdk';

CHAT_DICTIONARY.length;   // 256

const words = MidstateUtils.textToIndices('gm mate');   // [ 160, 168 ]
MidstateUtils.indicesToWords(words);                    // 'gm mate'

await client.sendChat(words);

Limits: 10 words per message, 4 attachments.

The dictionary is a security boundary

Every token is a u8 index into a fixed 256-entry table. That is not a quirk of a toy chat feature, it is the mechanism behind the property the whole subsystem is built around, which the source states as an invariant:

NoArbitraryText. No field in any chat message admits user-controllable String or variable-length Vec<u8> carrying textual data.

The only string that crosses the wire is sender, and it is validated as a base58 libp2p PeerId or a 64-char hex MSS pubkey. Everything else is a fixed-width byte payload or a bounded enumeration the receiver controls.

The payoff is that a peer cannot be made to relay arbitrary bytes. A gossip network that accepts free text is a gossip network that can be used to distribute whatever someone wants every node to carry. Here that is not a policy that has to be enforced, it is a shape the wire format cannot express.

The cardinality is load-bearing too: 256 entries means a u8 index can never fall outside the table. And because index 42 must mean the same word on every peer, changing the dictionary is a protocol break. New tokens can only be appended, and only if every node upgrades at once.

Attachments are the real payload

Each message can carry up to four typed attachments, and this is where the bus earns its name. All but two are a bare 32 bytes:

• address and coin_id: prove an airdrop or a payment

• mix_id: coordinate a CoinJoin session

• commitment and block_hash: reference a spend or a block

• midstate: debug a consensus fork

• data_hash: reference external data

• license_challenge: a commitment, a height and a salt, for MMR gossip challenges and uptime scoring of pruning licenses

• signature: up to 1536 bytes, for Q-Bolt payment channel gossip

That last one is the interesting one. It allows the ephemeral chat protocol act as a Lightning-style gossip overlay: Layer 2 channel updates ride the same bus as gm.

The anti-graffiti check

is_graffiti() rejects any 32-byte attachment whose bytes happen to be valid UTF-8, on the reasoning that a real hash almost never is and a human trying to smuggle text almost always is.

The comment is candid that this will misfire on roughly one in four billion legitimate hashes, and that this is an acceptable price. That is how seriously NoArbitraryText is taken: it would rather drop a valid license advertisement than relay one message of graffiti.

Practical notes

textToIndices silently drops anything not in the dictionary. 'gm mate wagmi' works. 'good morning friend' returns an empty array, because none of those three words exist in it. Validate before sending if a half-empty message would confuse your users.

Two wire versions exist. v1 (Chat) is receive-only on current nodes, which never emit it. v2 adds attachment coverage to the PoW and is domain-separated from v1, so a v1 nonce cannot be replayed as v2.

sendChat versus submitChat. sendChat asks the node to mine the PoW and broadcast under its own peer id. submitChat carries a nonce you mined yourself with mine_chat_pow_v2_wasm, so the message goes out under a sender you name, which is how a wallet identity originates chat without borrowing the node’s.

And yes, the dictionary contains wagmi, ngmi, ser, anon, based, rug, and moon, alongside wots, mss, utxo, and mempool. It was built for the people actually running nodes.

Part 12: Launch a token, offline, in one file

Time to put it together. This launches a pump.fun-style bonding curve with an unforgeable holder ledger, runs three users through it, and proves the security model by trying to cheat. It touches no network and costs nothing.

Save as pump-demo.mjs in the project from Part 1, then node pump-demo.mjs.

// pump-demo.mjs: a bonding-curve token launcher, running entirely offline.
import { fileURLToPath } from 'node:url';
import { readFile } from 'node:fs/promises';

const wasm = await import('midstate-sdk/pkg/wasm_wallet.js');
await wasm.default({
  module_or_path: await readFile(
    fileURLToPath(import.meta.resolve('midstate-sdk/pkg/wasm_wallet_bg.wasm')),
  ),
});

const { compile } = await import('midstate-sdk/compiler');
const { execute } = await import('midstate-sdk/vm');
const P = await import('midstate-sdk/pump');

const DEPTH  = 4;          // 16 holder slots. Small is fast. Max is P.MAX_DEPTH (9).
const HEIGHT = 310_000n;   // Comfortably past the state-thread activation height.

// The simulator's CHECKSIG compares strings, so pk === sig "signs" successfully.
// On a real chain these would be a genuine pubkey and a genuine MSS signature.
const USERS = {
  alice: { pk: 'aa'.repeat(32), sig: 'aa'.repeat(32) },
  bob:   { pk: 'bb'.repeat(32), sig: 'bb'.repeat(32) },
  carol: { pk: 'cc'.repeat(32), sig: 'cc'.repeat(32) },
};

// The contract is generated per launch, because tree depth is baked into it.
const compiled = compile(P.pumpContractSource(DEPTH));
const address  = wasm.blake3_hash_hex(compiled.bytecode);

const curve = { ledger: new P.PumpLedger(DEPTH), supply: 0n, reserve: 0n };

console.log('Deployed pump curve');
console.log('  address:', address.slice(0, 32) + '...');
console.log(`  script : ${compiled.sizeBytes}/1024 bytes, ${compiled.sigops} sigops`);
console.log(`  slots  : ${curve.ledger.size} (depth ${DEPTH}, max ${P.MAX_DEPTH})`);

function show(label) {
  const holders = curve.ledger.balances.filter(b => b > 0n).length;
  console.log(`\n-- ${label} --`);
  console.log(`   supply ${curve.supply}  reserve ${curve.reserve}  holders ${holders}/${curve.ledger.size}`);
  console.log(`   root   ${curve.ledger.root.slice(0, 16)}...`);
}

function trade(user, slot, amount, side) {
  const who = USERS[user];
  try {
    // An empty slot is free for anyone to claim. Stage the owner locally first.
    if (side === 'buy' && curve.ledger.balances[slot] === 0n) {
      curve.ledger.claim(slot, P.ownerFromPubkey(who.pk));
    }

    // 1. The SDK builds the witness, the Merkle proof and the expected outputs.
    const plan = P.buildTrade({
      ledger: curve.ledger, slot, amount: BigInt(amount), side,
      supply: curve.supply, reserve: curve.reserve,
      pubkey: who.pk, sig: who.sig,
    });

    // 2. Run the REAL contract against that plan before committing anything.
    const res = execute(compiled.asm, {
      witness:     plan.witness,
      inputState:  P.encodePumpState(curve.supply, curve.ledger.root),
      inputValue:  0n,
      thisAddress: address,
      height:      HEIGHT,
      outputs: [
        { address, value: 0n, state: plan.newState },   // state thread, always index 0
        { address, value: Number(plan.newReserve) },    // reserve coin, always index 1
      ],
    });

    if (!res.ok) {
      console.log(`  x ${user} ${side} ${amount}: contract rejected (${res.error})`);
      return;
    }

    // 3. Only now advance local state.
    curve.ledger.owners[slot] = plan.owner;
    curve.ledger.set(slot, plan.newBalance);
    curve.supply  = plan.newSupply;
    curve.reserve = plan.newReserve;
    console.log(`  + ${user} ${side}s ${amount} for ${plan.amountMds} MDS  (${res.steps} VM steps)`);
  } catch (e) {
    console.log(`  x ${user} ${side} ${amount}: SDK rejected (${e.message})`);
  }
}

trade('alice', 0, 5,  'buy');   show('alice buys 5');
trade('bob',   1, 10, 'buy');   show('bob buys 10');
trade('carol', 2, 3,  'buy');   show('carol buys 3');
trade('alice', 0, 2,  'sell');  show('alice sells 2');

console.log('\nNow the things that should fail:');
trade('bob',   1, 999, 'sell');   // more than the slot holds
trade('carol', 1, 1,   'sell');   // carol raiding bob's slot
show('final');

Output:

Deployed pump curve
  address: 1300bdccda1b7d00a1af6b6d999e5fe8...
  script : 666/1024 bytes, 2 sigops
  slots  : 16 (depth 4, max 9)
  + alice buys 5 for 10 MDS  (429 VM steps)

-- alice buys 5 --
   supply 5  reserve 10  holders 1/16
   root   913d7e1f546d969a...
  + bob buys 10 for 95 MDS  (429 VM steps)
...
Now the things that should fail:
  x bob sell 999: SDK rejected (pump: slot holds 10, cannot sell 999)
  x carol sell 1: SDK rejected (pump: pubkey hashes to c38d8bbe1254... but the
                  contract requires 883b0c0354d9... for this spend.)

What just happened

There are no token coins. Balances live as leaves in a Merkle tree whose root sits in the curve’s own state. That is not a stylistic choice, it is forced. A script only runs when its own coin is spent, so a token coin and the curve coin can never verify each other’s deltas. Worse, creating an output at an address does not run that address’s script, so anyone could fabricate a coin claiming any balance and sell it to drain the reserve. A balance that was never bought has no valid Merkle path, so there is nothing to fabricate.

The reserve is never stored. The contract asserts sum_to_addr(this_address()) == (s*s - s) / 2. Since every buy adds exactly the curve cost and every sell removes its exact mirror, the MDS held at the address is always implied by the supply. The state literally cannot lie about money it claims to hold.

Both failures are caught, for different reasons. Overselling is arithmetic and the SDK catches it before you spend anything. Carol raiding Bob’s slot is caught by the signature: the owner field is a commitment to a key, not a password, so knowing it buys you nothing. An earlier version of this contract had the Merkle proof but no signature check, which meant anyone who read a ledger burn could drain the slot it described.

Depth is a hard ceiling. Each tree level costs exactly 60 bytes of script. Depth 9 compiles to 966 of the 1024 consensus limit, so depth 10 would be 1026 bytes: two bytes too many. That is why MAX_DEPTH is 9 and 512 holders per launch. It is a per-launch limit, not a global one, since each token is its own contract.

Change DEPTH to 9, add more users, or feed a bad Merkle root in and watch the contract catch it. Nothing here can lose money, which makes it the right place to build intuition before you point any of it at a real node.

Quick reference: things that will save you an afternoon

Keys and wallets. These are the ones that lose money.

Spending, contracts and network.

Where to go next

The offline modules are the best playground, because nothing can go wrong:

• midstate-sdk/compiler and /vm: write a contract, run it, break it

• midstate-sdk/launcher: AMM and bonding-curve math, exact-integer throughout

• midstate-sdk/pump: a pump.fun-style launcher with an unforgeable Merkle holder ledger

• midstate-sdk/dex: on-chain order announcements and limit-order covenants

• midstate-sdk/bincode: the raw P2P wire codec, pure functions over bytes

Part 12 is the fastest way in: change DEPTH, add users, break the ledger on purpose. When the offline behaviour stops surprising you, point the same code at a real node.

midstate-sdk is on npm and licensed under the GPL.

I did not arrange that listing or apply for it. SafeTrade reached out. They said they liked what Midstate was doing and listed it themselves, describing it publicly as an innovative post-quantum blockchain.

They expected it to be hard. Post-quantum signatures and the two-phase transaction model made it, on paper, one of the more difficult integrations they had taken on, so they started with some precautions; no mining straight to the exchange, no high-frequency deposits or withdrawals. Then they built it, and it went smoother than they thought. Their words, once it was live: it wasn’t as hard as they initially expected, and it has run smoothly since.

Most projects never get any of the three, let alone all of them.

With the basics working, this seems like a good time to write down where the project stands and what comes next, including the parts that aren’t finished, since that’s where most of the remaining work is.

The Pi axe

That is a Raspberry Pi 5 mining Midstate. Not a rack. Not a rented GPU. A single board computer in one hand.

It matters because of the hardware gap. On Midstate the fastest miner is a GPU. A Pi running the 8-way NEON SIMD path does roughly 100 nonces per second. An RTX 4090 farm does tens of thousands. The gap between the hobbyist and the industrial rig is about 1 to 5,000.

That sounds bad until you compare it to Bitcoin. A hobbyist on a Bitaxe hashes at 500 Gigahashes per second against a 600 Exahash network. That gap is 1 to 1.2 billion. Midstate traps the hardware advantage in the commodity silicon band. A cheap, low-power machine you already own is genuinely in the game. Almost no coin with real hashrate can say that.

I looked at pushing it further, past GPUs, down to the Pi specifically. I had a design. I built it and I tested it. The honest answer is you cannot make a Pi beat a desktop at hashing. There is no resource a Pi has more of. You can make GPUs less dominant, but every version of that ends up favouring cheap cloud ARM and botnets, which is worse. A botnet of compromised phones is not decentralisation.

So the proof-of-work stays. It is simple, it verifies against one scalar implementation, and it works. GPUs dominate on purpose: they cost capital, space, and power, which prices out the IoT-refrigerator swarms a CPU coin invites. The Pi axe mines it. 1 to 5,000 is a gap a hobbyist can live with.

There is also a pool, so a small miner is not stuck mining solo against 1-to-5,000 odds and waiting months for a block. Point a Pi at the pool and it earns steadily, in proportion to the shares it submits.

The pool is provably fair. Normally a pool miner has to trust the operator to count their shares honestly. This one does not require that. It commits a Merkle tree of every miner’s score into the coinbase of each block, and a miner can pull a proof from the pool’s audit API that their exact score was included before they start hashing. If the operator lies or leaves someone out, the miner’s client sees the mismatch and disconnects. Payouts are proportional and every past split can be re-checked against the commitment it was paid from.

If you want a Midstate Pi5 Axe, I will sell it to you all set up to mine for 1000gMDS. Ready to run and fully synced.

Next: Layer 2

The next real work is Q-Bolt, the Layer 2 system. It exists and it works. But there is an honest gap between what it is now and what it needs to be, and this is the section where I say exactly what that gap is.

What Q-Bolt is today

Q-Bolt is Spilman channels. Two parties fund a 2-of-2 multisig UTXO. One side is the sender, one is the receiver. The sender signs balance states and hands them over; the receiver stores them and signs nothing until the channel closes. Only two transactions ever touch the chain: the open and the close.

This design is deliberately simple, and it buys a strong safety property for free. The sender never holds the receiver’s signature, so the sender cannot broadcast any balance state at all. Their only unilateral exit is a time-locked refund after the channel expires. The receiver’s balance can only ratchet up: an old state pays them less, and they just reject it. So there is no need for revocation, no penalty transactions, no “punish the cheater” machinery. The attack those mechanisms defend against is structurally impossible here, because the money only flows one way.

The routing, HTLCs, and swaps are already built on top of this. Payments cross multiple channels locked by a single preimage. Hubs forward for a flat 50 sats, which is what their two one-time keys cost them. Covenant HTLCs claim with no signature at all — the script forces the coin to the right place, so the redeemer only reveals the preimage. On a chain where every signature is a 576-byte one-time key, a claim path that spends zero keys is worth having. There is even just-in-time channel opening, so a hub can pay a destination it has no channel to yet.

A worked example: the cross-chain DEX

The clearest way to see why Layer 2 matters is the cross-chain DEX, which is live and works today, on-chain, both directions but is currently hidden in the wallet.

Say you are selling MDS for ETH on Base. Under the hood it is a hash-time-locked swap:

1. You lock your MDS in a covenant on Midstate. The lock has a hashlock — H = BLAKE3(secret) — and an absolute refund height. Only someone with the secret can claim it before that height; after it, you get it back.

2. The buyer sees your lock, verifies it, and locks their ETH in the swap contract on Base with the same H and a shorter refund delay.

3. You claim the ETH by revealing the secret on Base. The contract publishes it.

4. The buyer reads the secret from Base and uses it to claim your MDS on Midstate.

Nobody can be cheated. Either both legs complete or both refund. The whole thing is trustless and needs no intermediary.

It is worth heading off the obvious worry: doesn't publishing the secret let anyone steal the coins? No, and the reason is the whole trick of the design. The secret is not a key to the money — it is one of two conditions on each lock. The other condition is a fixed recipient, baked in when the lock was made: the MDS lock pays the buyer, the ETH lock pays you, and that is true no matter who reveals the secret. So the secret only lets someone trigger a payment that was already addressed to someone else. If a bot reads the secret off Base and races to claim first, all it does is pay gas to send you your own ETH. Revealing the secret is not a leak; it is how the swap settles.

But look at where the time goes. Every leg is an on-chain Midstate transaction, and a Midstate transaction is two phases — commit then reveal — separated by block confirmations, at roughly one block a minute. Locking the covenant confirms on-chain. Claiming it confirms on-chain. A single swap can take many minutes end to end, and every partial fill is another round of the same. It is correct, but it is slow, and slow kills a DEX.

This is exactly the problem Layer 2 solves, and here is the part worth being precise about: the fix is already partly built. The hashlock in that swap is the same primitive Q-Bolt uses for routing. A submarine swap is the bridge — it links the on-chain HTLC to an off-chain channel payment under one preimage, so the Midstate leg settles instantly in a channel while the ETH leg settles on Base, and the same secret unlocks both. Flip the MDS side from an on-chain covenant to a channel HTLC and the lock-and-claim — minutes of block confirmations — collapses into an instant channel update.

That submarine path exists in Q-Bolt today. When a taker locks their ETH, the maker’s node can intercept and add the matching HTLC to a

n open channel instead of going on-chain. Both sides of that plumbing are written. Two things stop it being the everyday experience. First, it is currently disabled in the interface — the DEX defaults to the slower on-chain settlement while the fast path is finished and tested. Second, and more fundamentally, it only works when a channel already happens to exist in the right direction with enough balance. Because today’s channels are one-directional and disposable, that channel often is not there, and the swap falls back on-chain.

So the DEX is not blocked on inventing Layer 2. It is blocked on finishing it: turning the submarine path on, making it the default, and making channels persistent and routable enough that the fast path is available every time instead of only when liquidity was pre-positioned. That is the shape of the whole plan. Anything slow because it waits for Midstate blocks — DEX fills, token trades, ordinary payments — gets fast the moment it settles in a channel, and the machinery to do it is already partly in the code.

What it needs to become

The end goal is the only thing that matters here: instant transactions, high throughput, low fees. A real Layer 2. Whether the channels end up one-directional, bidirectional, or something else is an implementation detail I will solve in code. The target is fixed; the shape is not.

Q-Bolt has the hard parts already — funded channels, HTLCs, routing across hubs, swaps — and they work. What is left is turning that from a set of working parts into a network that moves payments instantly and cheaply at scale. That is engineering, not research: it needs no new cryptographic assumption and no script feature the chain does not already have. The primitives are in the VM. The work is making them into a payment network.

Alongside the channel work, three supporting pieces:

• Watchtowers, so your channels are safe while you are offline. Midstate already has a gossip layer and peer reputation to build them on.

• Refill and splicing, so a drained channel is topped up instead of closed and reopened on-chain.

• Pathfinding and invoices, so payments route across many hubs with liquidity awareness.

The measure of success is simple. A payment confirms instantly, costs almost nothing, and the network can carry a lot of them at once. Everything in this section is in service of that and nothing else.

Then, on top of it

Once the channel layer is a real network, the rest follows:

• Submarine swaps. Move value between Layer 2 and the main chain trustlessly, in either direction, unlocked by one preimage on both sides so there is no cross-chain theft.

• The DEX, brought back on top of those swaps.

• A token on-chain. Not because the world needs another memecoin, but because it proves the chain carries tokens other than MDS.

• A Uniswap-style AMM, so those tokens trade against MDS.

All of it works on the main chain today. It is slow. On Layer 2 it is instant. That is the whole reason for doing it there. But the instant part is real only once the channels are bidirectional and the network can route. That is the work.

A GUI wallet

Right now there are two ways to hold Midstate: the command-line wallet, and the browser wallet. The CLI is for people who live in a terminal. The browser wallet is genuinely a light node — it scans the chain with compact block filters over WebRTC, verifies what it finds, and never trusts a server to tell it its own balance. But it is a browser tab.

What is missing is a desktop application. A GUI full-node wallet for Windows and macOS that a normal person can download, run, and understand. Send, receive, channels, history, backup — without a command line and without a browser.

The harder, better version has mining built in. The node already has an 8-way NEON SIMD miner and a GPU miner that treats the graphics card as an untrusted oracle and re-verifies every chain on the CPU before broadcasting. Wrapping that in a desktop wallet means one download that syncs, holds your coins, and mines them. That is the thing that makes a Pi axe or a desktop a first-class citizen instead of a config file.

It is not a small job. It is a large amount of non-core code to write and, worse, to support. Support is the part people underestimate. It needs more hands than mine.

So there is a bounty: 1000 gMDS (1,073,741,824,000 MDS or 1000 block rewards) for a working GUI full-node wallet, Windows and macOS. Wallet first; mining can follow. If that is a thing you would build, say so. Judged by me and the community. I’m working something up in the meantime to be part of the Core codebase - as moving to layer2 natively is one of the next challenges that would be more user friendly in a GUI vs the CLI.

The actual problem

Here is the honest part.

People use Midstate. They mine it, swap it, trade it. Almost nobody builds on it.

That is what holds the project back. Not the protocol. The protocol is further along than the community realises. What is missing is other people making things: contracts, tokens, tools, apps. Right now that is mostly one socially awkward person, and one person is not a development community.

I want to fix that directly, and the first piece is already live.

There is an IDE at https://midstate.cash/ide. You do not hand-write stack opcodes. It has a real language built for Midstate — let and var, if, repeat, switch, user-defined macros, named struct and state field layouts so you address a coin’s committed state by name instead of slicing bytes, and the usual infix operators. It ships with a standard library of the primitives covenants actually need: require_signed_by, require_timelock, require_funds_transferred, Merkle-proof verification.

That compiles down to the low-level script the VM runs, you can still drop to raw opcodes anywhere you want, and the debugger steps through the compiled bytecode against a live stack so you watch exactly what your code does. There are HTLC and covenant templates to start from, an emulator where you set the block height and inputs, and wallet connect, so you can go from a blank editor to a deployed script without leaving the page. A novel script language is hard to start cold. This removes most of that.

On top of the IDE:

• The 1000 gMDS GUI wallet bounty above.

• Competitions, ideally run on-chain themselves. The prize money does not need to sit in my wallet on trust. For a bounty with an objective test — a contract that has to satisfy a given spec, pass a given input, or unlock a test coin — a covenant can escrow the prize and release it automatically to whoever first meets the condition. No judge, no trust. For a judged competition, where "best" is a human call, the same escrow releases on a governance vote instead. Either way the funds are locked on-chain and the rules are visible, which is itself the kind of contract the competition is asking people to write.

• A foundation — possibly a DAO written in Midstate script. Midstate covenants are stateful: a script reads the state committed on the coin it spends and the state on the coin it creates, and enforces the relation between them, so state threads forward from one transaction to the next. That is enough for a real on-chain state machine — a running vote tally, a staking pool, a treasury — not just a one-shot check. It is not hypothetical: the IDE ships a staking-and-governance contract that compiles to bytecode today and enforces exactly this state continuity, with named state fields, stake-weighted voting, thresholds, and enforced treasury payments. It stays within a deliberately non-Turing-complete VM — a stateful treasury with token-weighted rules, not arbitrary contract logic — and it would be the project governing itself on its own chain, which is the strongest demonstration there is that Midstate carries real applications, not just MDS.

• There is a JavaScript SDK on npm, but it is behind the protocol: it does not handle reorgs, misses consolidate outputs, and its Layer 2 support is a stub. Updating it is exactly the kind of contribution the project needs.

The chain works, it trades, and it is cheap to experiment on. If Midstate grows, it grows because more people build on it than just me. That is not a complaint. It is the one thing I cannot do alone.

Near term

Over the next few days I will write something longer and put a proper roadmap on the site.

Short version: finish Layer 2, bring back the DEX on submarine swaps, add tokens and an AMM, a GUI wallet probably by bounty, and push hard on getting people building instead of only using.

The hard parts are done. The rest is a question of hands.

midstate.cash

I wrote Midstate to solve specific, tangible failures in current UTXO-based protocols. The design abandons several industry darlings:

• Turing-complete scripting,

• ECDSA, memory-hard PoW, and

• arbitrary data payloads.

Instead, we opted in favour of simplicity:

• rigid state machines,

• single-primitive post-quantum cryptography, and

• thermodynamic limits.

Here is exactly how Midstate works, why the code is written the way it is, and the game theory holding it together.

WOTS, MSS, and Enforced One-Time Use

ECDSA and Schnorr are dead to Shor’s algorithm. Hash-based cryptography is the only defense that avoids unproven lattice assumptions. Midstate uses Winternitz One-Time Signatures (WOTS) and the Merkle Signature Scheme (MSS). We use w=16. A signature is 18 BLAKE3 hash chains. It takes 576 bytes. It is extremely fast to verify.

The fatal flaw of WOTS is key reuse. Reusing a private key exposes overlapping preimages and allows instant forgery. Wallet warnings are useless. Users will ignore them and lose their funds.

Midstate enforces one-time use at consensus. The V4 hard fork introduced burned_wots. This is a dedicated Sparse Merkle Tree tracking every spent key. The root of this burn tree is mathematically bound into the block’s state_root. If an address has ever been spent, the network physically cannot converge on a state root that allows it to be spent again.

To make this usable, wallet::select_coins uses deterministic snowball grouping. If you receive five UTXOs to the same address and try to spend one, the wallet forces you to spend all five. One signature. One commitment. Key reuse is structurally impossible.

Mining: The Physical Impossibility of a BLAKE3 ASIC

Memory-hard algorithms like RandomX try to stop ASICs by tying hashing to RAM bandwidth. They fail. They just hand network consensus over to botnets.

Midstate uses thermodynamic limits. The PoW requires exactly 1,000,000 sequential BLAKE3 compressions per nonce:

x = hash_concat(midstate, nonce);
for _ in 0..1_000_000 {
  x = hash(x);
}

This is a strict dependency chain. Iteration 2 requires the output of iteration 1. You cannot parallelize a single chain. To build an ASIC that beats a CPU on one nonce, you must unroll the loop in silicon. That requires 1,000,000 ALUs in sequence. The required die area is so massive that signal propagation latency hits the speed of light limit. An ASIC for this is physically impossible.

GPUs dominate Midstate mining. This is intentional. A CPU core finishes a single chain faster, but a modern GPU can grind 24,000 independent nonces concurrently. If you build a CPU-only coin, compromised IoT refrigerators take over. GPUs require capital, physical space, and power. They price out the botnets.

The hardware gap is strictly bounded. A Raspberry Pi running our 8-way NEON SIMD path calculates roughly 100 nonces per second. A dedicated RTX 4090 farm calculates tens of thousands. The gap between a hobbyist node and an industrial rig is roughly 1 to 5,000.

Compare this to Bitcoin. A hobbyist running a dedicated ASIC Bitaxe hashes at 500 Gigahashes per second against a 600 Exahash network. The gap is 1 to 1.2 billion. Midstate permanently traps the hardware advantage in the commodity silicon band.

Running a million-step loop on a GPU introduces a practical problem. The OS watchdog timer assumes the graphics card is frozen and brutally kills the process. We solve this in core/gpu_mining.rs with micro-dispatch checkpointing. The GPU allocates a VRAM buffer, runs 2,000 steps, saves the chaining state, and yields to the host. The OS stays responsive. The node can instantly abort the batch if a new block arrives.

GPU drivers are usually untrustworthy garbage. They apply aggressive, undocumented compiler optimizations that break cryptographic math. If a shader hallucinates a hash, your node broadcasts an invalid block and forks itself off the network.

To account for this, in the canonical implementation of the GPU miner, we treat the GPU as an untrusted oracle. It is only permitted to surface candidate nonces. The CPU ruthlessly re-verifies every 1,000,000-iteration chain using the canonical scalar implementation before broadcasting anything.

The Commit-Reveal-Consolidate Protocol

Mempool front-running and CPFP pinning attacks are structural failures. Midstate prevents them by making unconfirmed transaction chaining impossible.

Transactions take two phases. First is the Commit. This binds inputs, outputs, and a salt to a hash. It requires Proof-of-Work but pays zero fees. Second is the Reveal. This opens the commitment, provides the signatures, and pays the fee. You cannot chain unconfirmed transactions because the output UTXO does not exist until the Reveal is mined.

Commits require PoW to prevent spam. Originally, attackers could pre-compute valid nonces months in advance. The V3 hard fork fixed this. The hashing algorithm is now BLAKE3(anchor_hash || commitment || actual_nonce). The miner must pull a recent block hash from the chain’s Merkle Mountain Range. The PoW is temporally anchored. You cannot hoard commits. The work decays.

WOTS signatures are huge. Sweeping 1,000 dust UTXOs would require 576 kilobytes of signatures. We added Transaction::Consolidate to fix this. It takes N inputs sharing the same address and validates them against a single signature.

Finally, there is the Free-Rider problem. Commits pay no fees. If miners ignore them, the network halts. Starting at COMMIT_WEIGHT_ACTIVATION_HEIGHT, every Commit included in a block adds exactly 16,777,216 base work to the block’s total depth. If two miners find a block at the same height, the block with more Commits is mathematically heavier. It wins the tie-breaker. Miners are economically forced to pack their blocks with Commits to minimise their orphan rate.

Storage: Inode Exhaustion and the SMT

Writing one flat file per block bricks embedded nodes. At one block per minute, you generate 525,000 files a year. An ext4 filesystem on a Raspberry Pi SD card will suffer Inode Exhaustion in 18 months. The disk will report it is full even with 100GB of free space.

Midstate stores the entire chain in a single Redb database. Redb uses Copy-On-Write B-Trees. We get ACID compliance and eliminate brittle temporary file renaming during chain reorgs.

The UTXO set is a Sparse Merkle Tree with a depth of 256. A naive SMT stores every interior node and blows up RAM. We cache the top 16 levels and bucket the bottom 240 levels on the fly. RAM usage is strictly bounded. A billion UTXOs never exceeds 131,071 cache entries.

If your node OOMs a Raspberry Pi Zero, your code is broken. We explicitly bound the sync prefetch buffer to 64 MiB.

Bayesian P2P Reputation and Eclipse Defenses

P2P networks are dark forests. You cannot trust any peer.

Midstate tracks peer reputation using a Beta distribution. Every peer starts with a uniform prior. Valid transactions or blocks increment alpha. Invalid PoW, bad signatures, or timeouts add a massive penalty to beta.

The Expected Value of the peer is alpha divided by alpha plus beta. This dictates their dynamic rate limit. An honest peer gets up to 500 requests per minute. If a peer’s EV drops below 10 percent, their rate limit hits the floor or they are purged from the routing table entirely.

To prevent Eclipse attacks, we extract the IPv4 or IPv6 subnet from inbound connections. We strictly cap the number of peers allowed per subnet. Rotating Peer IDs does not save an attacker. They have to burn real IP space.

WebRTC and Browser Hostility

Serving browser wallets directly requires WebRTC. Browsers are hostile environments. If you expose a public listener, you must assume every incoming connection is a reverse-Slowloris attack attempting to exhaust your file descriptors.

Midstate isolates light clients into a strict stream multiplexer. We hard-cap WebRTC peers at 500. If a client stalls while reading a response, we do not wait. A strict 5-second timeout severs the connection and frees the socket.

Nodes running behind reverse proxies are vulnerable to spoofed IP headers. Attackers inject fake X-Forwarded-For headers to bypass LAN-only firewalls and access internal hardware endpoints. Midstate parses the entire proxy chain. If a single public IP appears anywhere in the chain, the request is physically blocked.

Cap-and-Trade Pruning Licenses

Nobody stores historical blocks for free. Altruism is not an economic model.

Midstate uses Pruning Licenses. These are Confidential UTXOs. To mint one, you perform Proof-of-Archival-Work. You salt historical block payloads with your Issuer ID and grind nonces to build a Merkle root of the proofs.

Licenses trade on-chain. We abandoned percentage-based royalties because users trivially evade them via out-of-band settlement. Instead, the covenant enforces a Fixed Transfer Tax. On transfer, the script evaluates OP_THIS_ADDRESS 0 OP_OUTPUT_ADDRESS OP_EQUALVERIFY to force the license to remain in the covenant. It then evaluates <issuer> OP_SUM_TO_ADDR <fixed_fee> OP_GREATER_OR_EQUAL. The UTXO physically cannot move unless the exact fee is routed to the creator.

Archivers are audited via MMR Gossip Challenges. Nodes ping Archivers over the chat layer with a block height and a salt. The Archiver responds with BLAKE3(salt || block_payload). We do not grant reputation immediately. That allows lazy Archivers to reply with random bytes. We store the response. When the challenging node eventually syncs that block, it validates the hash cryptographically. Only then is reputation granted or slashed.

Chat: The No Arbitrary Text Rule

If you allow variable-length strings in P2P messages, your chain will eventually host illegal content, malware payloads, and base64-encoded garbage.

Midstate’s chat is restricted to a hardcoded 256-word dictionary. A message’s words array is just a Vec<u8>. Index 42 is the word send. Index 103 is the word in. You literally cannot transmit arbitrary text.

For passing data, we use fixed-shape attachments. Addresses and CoinIDs are strictly validated as 32-byte arrays. If an attachment’s payload deserializes as valid UTF-8, it is flagged as graffiti and the node drops it.

Chat messages require V2 PoW. V2 domain-separates from V1 by injecting a 4-byte attachment count. This enforces that a peer cannot strip or reorder your attachments while gossiping your message, because doing so invalidates your PoW.

Conclusion

Midstate set out to fix a short list of concrete failures, and most of those fixes hold.

• The entire system is reliant on a single quantum safe primitive: BLAKE3

  • Key reuse is prevented by consensus, not by wallet warnings.

• Front-running and pinning are structurally impossible, because you cannot chain a UTXO that does not exist yet.

• The proof-of-work traps mining hardware in the commodity band instead of pretending ASICs won’t be built. And

• a full node runs for years on a Raspberry Pi without exhausting its RAM, its inodes, or its SD card.

None of that required a virtual machine, a new cryptographic assumption, or trusting anyone.

It was not free.

Honest accounting:

• Post-quantum signatures are heavy and stateful. Every spend carries 576 bytes of signature, and one-time keys push complexity into the wallet. Snowball grouping means you spend every coin at an address or none of them, and a wallet restored from a stale backup is a footgun the protocol can only partially protect you from.

• Commit-reveal doubles the moving parts. Two phases, two mempool queues, and timeout windows where funds sit in limbo. The state machine is simple. Operating it is not.

• Verification has a floor. A Bitcoin node checks a block’s proof with one hash. A Midstate node must replay the winning nonce’s entire million-step chain, because a sequential construction has no shortcut: that is the whole point of it. The mining-to-verification ratio is unchanged: a block takes millions of chains to find and one to check. But the absolute cost of that one check moved from nanoseconds to roughly a tenth of a second of serial compute, and no hardware buys you out of it.

• A single chain runs no faster on an RTX 4090 than on a phone core. Multiply by history: at the Pi’s own hundred chains per second, a year of one-minute blocks is about ninety minutes of pure proof-replay during initial sync, assuming chains for different blocks are verified in parallel batches. Pools pay the same tax on every share a miner submits. The sequentiality that makes the ASIC impossible cuts both ways. Nobody skips the loop, including the honest.

• The protocol is young and has already needed surgery. V3 anchored commit PoW because hoarding was possible. V4 added the burn tree because wallet-level discipline wasn’t enough.

• There is one implementation, written mostly by one socially awkward person. More oversights are in there. They just haven’t surfaced yet.

• And the economics assume a scale that doesn’t exist yet. While the network is small, rented GPU hashrate could out-mine it. The incentive design shapes behaviour at a size Midstate hasn’t reached, and the pruning-license market is designed, deployed, and essentially untested.

The successes and the flaws come from the same decision: keep every mechanism small enough to prove what it does. Heavier signatures bought quantum safety. Slower transactions bought a mempool that can’t be gamed. Expensive verification bought mining that stays on commodity hardware.

Those are the terms.

Well, at least they’re written down now.

github.com/ciphernom/midstate

In the annals of human ambition, few endeavors match our reach toward artificial minds that might exceed our own. We stand now at a peculiar crossroads, where mathematics meets mythology - where differential equations trace the arc of Icarus, and game theory maps the paths of ancient gods.

This post presents a formal mathematical framework for understand…

Read more

The Problem

Current approaches to metacognition in AI typically rely on explicitly programmed hierarchical architectures…

Read more

Read more

While the search for extraterrestrial intelligence focuses skyward, compelling evidence suggests we might be looking in the wrong direction. Recent archaeological discoveries, evolutionary biology research, and advances in theoretical physics all point to an extraordinary possibility - one that challenges our understanding of both ancient mythology and …

Read more

…

Read more

We present BitQuill, a protocol for providing some reasonable evidence of the human-incremental creation of digital documents through a novel application of proof-of-work and temporal hash chains. The system creates an unforgeable record of document evolution by requiring computational work for each edit operation, making it prohibitively expens…

Read more

In the chaotic world of 'cryptocurrencies', one truth stands unchallenged: Bitcoin is the only digital asset that truly matters. The rest are mere distractions—shitcoins masquerading as innovation while introducing fragility and centralization into a space that was meant to be decentralized and secure.

Ethereum, in particular, has long been t…

Read more

Introduction

The Momentum-Halving Model is a tool for analyzing Bitcoin's USD exchange rate (from now on “rate”) dynamics. It combines four key factors:

1. Momentum: …

Read more

Read more

Read more

What's Grokking?

Imagine training a model way past the point where conventional wisdom says "stop!" Instead of becoming less accurate, these models sometimes have an "aha!" moment. They suddenly "get" (…

Read more

Have you ever wondered why attempts to ban or regulate Bitcoin often seem to backfire, leading to even greater interest and adoption? The answer lies in a fascinating phenomenon known as the Streisand Effect, and today, we're going to dive deep into how it applies to the world of Bitcoin.

What is the Streisand Effect? Named after a 2003 incident involvin…

Read more

Read more

This report investigates the adequacy and appropriateness of using a log-log regression model to predict Bitcoin (BTC) prices. The popular and so called “time power law” model for Bitcoin price is recreated using the RANSAC (RANdom SAmple Consensus) method is employed to fit the regression model, and the Ramsey RESET test is applied to detect mo…

Read more

This is not a re-hash of the model though, if you need more information on it hav…

Read more

It’s Friday night. The place is PACKED. The dishes are piling up, a waitress just quit because some dirty old customer pinched her bum and you are on your own in the kitchen.

“Order Up!” yo…

Read more