Every browser tab is a validator

BrowserChain reimplements two parts of Stellar in TypeScript: the Stellar Consensus Protocol and the classic ledger. Every tab runs both.

Each ported file names its stellar-core source in a header comment. The design, the data formats and every rule are in docs/ARCHITECTURE.md.

There is nothing to install and no account to create. Opening the page is the whole setup.

In SCP, every validator chooses whom it trusts. In auto mode, the default, BrowserChain chooses for you. Your node trusts itself and every active validator, and needs about two thirds of them to agree. The threshold is max(1, ceil(2n/3)) of n validators: with 4 validators, any 3 must agree.

A validator counts as active when all of these hold:

• your node heard from it in the last 9 seconds;
• it is synced, booting or stalled, on your chain, and at most one ledger away from you;
• it takes part in SCP: it sent a signed SCP message for a recent ledger. A validator seen for the first time gets 5 seconds of grace.

A new validator joins the quorum at the next ledger. A tab that closes says bye and leaves the quorum at once. A tab that vanishes without a word stops counting as active after 9 seconds. It then leaves the quorum at the next ledger, or at once if the open ledger has made no progress for 4 seconds.

Browsers slow down background tabs and sometimes freeze them. A frozen node stops voting, and the others drop it from their quorum. When the tab wakes up, the node checks that it is still in sync, catches up if it fell behind, and votes again.

The Wallet makes test accounts that friendbot funds, sends payments, issues assets, trades on the DEX and creates claimable balances. The Explorer shows ledgers, transactions with decoded XDR, and accounts. The Lab decodes, builds, signs and submits XDR.

Some networks block direct WebRTC connections. BrowserChain uses public STUN servers but no TURN relay, so two browsers behind strict firewalls may fail to connect. Tabs of one browser do not need any of this: they talk over BroadcastChannel.

BrowserChain follows Stellar’s design. There is no mining and no staking. Validators agree by federated voting, and every node applies the same transactions in the same order.

Each validator lists the validators it trusts and how many of them must agree. That list is its quorum set, for example “any 3 of these 4”. A group that satisfies it is a quorum slice. A quorum is a group of validators that contains a slice of each of its members.

SCP settles a statement in three steps:

1. Vote. A node votes for a statement that it considers valid.
2. Accept. It accepts the statement when a quorum that includes it voted for it or accepted it, or when a v-blocking set accepted it. A v-blocking set overlaps every slice of the node, so every quorum of the node includes at least one of its members.
3. Confirm. It confirms the statement when a quorum accepted it. A confirmed statement is final.

This is safe as long as any two quorums share an honest validator. The Validator page checks that any two quorums intersect, when your node knows at most 16 validators.

Each ledger is one SCP slot. For each slot, SCP uses federated voting in two phases.

Nomination decides what to vote on. A candidate value is a StellarValue: the hash of a transaction set, a close time, and the signature of the validator that built it. Nomination runs in rounds. Each round has leaders, chosen by a hash, and nodes vote for their leaders’ values. When candidates are confirmed, every node combines them the same way: the transaction set with the most operations wins, then the one with the highest fees, then the lowest hash.

The ballot protocol makes the choice final. Nodes put the combined value in a ballot and vote to prepare it, then to commit it. If a slot gets stuck, timers move it on: nomination adds leaders, and the ballot moves to a higher counter. Nomination round n, or ballot counter n, waits n seconds, up to 30 seconds.

• Fees. Each operation costs the base fee, 100 stroops (1 XLM is 10,000,000 stroops). A higher fee bid only moves a transaction ahead when a ledger is full; the charge stays the base fee. There is no surge pricing.
• Reserves. An account must keep (2 + subentries) × 0.5 XLM. Trustlines, offers, extra signers and data entries are subentries. A claimable balance adds 0.5 XLM per claimant to the reserve of the account that created it.
• Sequence numbers. Each account has a sequence number, and a transaction must use the next one. So a transaction cannot be replayed or applied out of order. A node queues up to 16 transactions per account, and replaces a queued one only for 10 times its fee.
• Order. At close, all fees are charged first. Then each transaction applies all of its operations or none, in an order that every node computes the same way.

The genesis ledger creates 100 billion play XLM. Sixteen friendbot accounts hold 1 billion each, and the root account holds the rest. Their keys come from the network passphrase, so anyone can derive them. Rules limit what those keys can do:

• The root account is locked: nothing it signs is valid.
• A friendbot account may sign one kind of transaction only: one operation that creates a new account with 10,000 XLM, or pays an existing account 10,000 XLM, at exactly the base fee.
• A ledger holds at most 16 friendbot transactions.
• When you press Create a test account on the Wallet page, your node builds the friendbot transaction itself, from a friendbot account assigned to it, and submits it like any other.

The order book follows stellar-core at protocol 23. Offers buy and sell any pair of assets and cross by price, then by time, with stellar-core’s exchange math. Path payments cross several order books in one operation. One operation may cross at most 1,000 offers, and a ledger holds at most 200 operations from transactions that use the DEX.

A node that falls behind catches up from its peers. There are no history archives: peers serve headers, ledgers and snapshots.

• Replay. The node first checks that the ledger headers up to the target link to each other by hash. Then it downloads ledgers in batches of 64, applies each one itself, and checks that it gets the same header hash.
• Snapshot. A new node with no chain starts from the newest snapshot, if there is one: a full copy of the state, taken every 64 ledgers. It checks the snapshot against the state hash in the ledger header, then replays the rest. A node that already has a chain uses a snapshot only when no peer can serve the ledgers and validators it knew before vouch for the snapshot.

The auto quorum keeps the network live while tabs come and go. The cost: when the network splits, both sides can keep closing ledgers. That is a fork. Stellar validators avoid forks with quorum sets chosen by hand, and a closed Stellar ledger is never rolled back. BrowserChain detects forks and resolves them:

1. A node sees a peer with a different header for the same ledger. It walks back to the last ledger they share: the fork point.
2. It counts vouchers for each branch. A voucher is a connected validator whose signed status puts it on that branch. Only validators that this node saw as active members at or before the fork point count. Keys first seen later count for nothing.
3. The branch with more vouchers wins, and the node counts itself for its own branch. On a tie, the heavier branch wins: the one whose ledgers since the fork were confirmed by more validators.
4. The losing node rolls back to the fork point, catches up from the winner, and puts its own transactions that are still valid back in the queue.

Why only validators known before the fork? In auto mode anyone can make new keys. If new keys could vote on forks, one person with many tabs could take over the chain. Two lone tabs that meet have no members to count, so the heavier branch decides.

In manual quorum mode, a node never rolls back by itself. It shows a fork alert, and you decide whether to resync.

Two groups of tabs that started apart are strangers: no node in one group ever saw a node of the other as a member. When they meet, neither follows the other, because to each side the other group looks like a crowd of new keys. Each group keeps its chain.

A tab shows the alert “Another group of validators is on a different chain” when the other group is at least as large as its own. Press Resync in the alert. The tab wipes its chain, keeps its identity and catches up from the other group like a new node. Do this in every tab of that browser that shows the alert.

A tab that comes back after all the validators it knew have left can be stuck the same way. It cannot check the new chain, and voting alone would build a chain of its own. So it does not vote: the Overview says “This node is not voting”, gives the reason and offers Resync.

BrowserChain is plain TypeScript in one repository. Each module has its own tests, and docs/ARCHITECTURE.md is the contract between the modules.

When two nodes connect, each sends a hello signed with its node key. Over WebRTC the hello also covers a fresh nonce from the other side and the DTLS channel id: a hash of both peers’ DTLS certificate fingerprints, which each browser reads from its own connection. A hello made for one connection is useless on any other, so nobody can relay a captured hello to pass as another node. DTLS encrypts the rest of the channel. BroadcastChannel links never leave the browser.

Each SCP message is signed by its node over the network ID and the statement. Each nominated value carries the signature of the validator that built it, and status announcements are signed too. Nodes check every signature and every hash: transaction sets, quorum sets, ledger headers and snapshots. Buffers and requests have limits, for example 4 MB per message and 64 peers per node.

src/golden freezes the bytes that consensus depends on: the genesis ledger, StrKeys, transaction envelopes, ledger closes, a signed value, SCP messages and hashes, overlay messages, and a 4-node simulation with its snapshot at ledger 64. Sixteen tests compare the code with them, so a refactor that changes these bytes fails a test. Every intended change is logged in src/golden/CHANGES.md.

Closing a ledger is a pure function of the state, the transaction set and the agreed value. It reads no clock and no random numbers. The rest of the code gets time from an injected clock. So the same node code runs in your browser and in a simulation on a virtual clock, where many nodes run fast and every run can be repeated.

The idea came from the viral “X running in your browser” projects. Many of them compile existing game code to WebAssembly, and several use WebRTC for multiplayer. Doing the same with stellar-core, a large C++ program, looked like months of work. BrowserChain takes another path: it reimplements Stellar’s consensus and classic ledger in TypeScript, and ports the logic and the tests from stellar-core.

It was built with Claude Code, Anthropic’s coding agent, in multi-agent workflows, in this order:

1. An architecture contract. docs/ARCHITECTURE.md fixed the module boundaries, the shared types, the data formats and the rules before the modules were written.
2. Parallel module agents. Separate agents built SCP, the ledger, the DEX, overlay and storage, the UI, the herder, and history with the simulation. Each wrote unit tests, ported from stellar-core’s tests where possible.
3. Integration into a Web Worker runtime: one node per tab, an RPC client for the interface, and a bridge that carries WebRTC from the page into the worker.
4. End-to-end tests in real browsers. Playwright opens several tabs as several validators and checks consensus, restarts, crashes, frozen tabs, forks and the wallet. Two opt-in specs connect two browsers over real WebRTC through the public relays.
5. A migration to @stellar/stellar-sdk. The XDR code moved from the deprecated @stellar/stellar-base package to the SDK. Golden byte vectors guarded the move.
6. Adversarial review. Review agents attacked the code through separate lenses: SCP, ledger, herder, runtime and UI. After each review, an independent verifier re-ran the evidence for every finding on the code from before and after the fix, and fixed what did not hold.
7. Targeted fixes. Later rounds fixed specific problems, with regression tests. For example: the genesis root is locked, friendbot transactions follow strict rules and a cap per ledger, fork verdicts count only validators known before the fork, and hellos are bound to the WebRTC channel.

The SCP simulations run networks of 4 to 12 nodes, some with nested quorum sets, with random message delays, crashed nodes, lost messages, and Byzantine nodes that send conflicting or forged messages. A typical scenario runs 20 random seeds of 20 slots each and checks that no two nodes ever decide different values. The node simulation in src/sim adds partitions, forks, departures and hostile peers.

Counted on October 19, 2026: npx vitest run for the tests, the files in e2e/ for Playwright, and wc -l for the lines. Test kits and the simulation harness count as test helpers.

Only public sources went in:

• stellar-core source and tests (Apache-2.0), for SCP, the ledger, the DEX and the herder.
• The SCP Internet-Draft, draft-mazieres-dinrg-scp-05, to cross-check the SCP port.
• npm packages, among them @stellar/stellar-sdk for XDR and keys, Trystero for WebRTC over Nostr, idb for IndexedDB, React, Tailwind CSS, Vite, Vitest and Playwright.
• Public documentation and web pages.

BrowserChain is a learning and demo network. Keep these points in mind.

• The network, not the consensus. Validators are browser tabs that come and go. The SCP messages, ledgers and signatures between them are real.
• Auto quorum and fork resolution are BrowserChain additions. Stellar validators choose their quorum sets by hand, and a closed Stellar ledger is never rolled back.
• The money. XLM here has no value, and anyone can derive the friendbot keys.
• The demo (?mock=1) runs no consensus. A script plays the validators, makes up traffic and applies your transactions to a simplified ledger.

• No Soroban smart contracts, no liquidity pools, no sponsorship operations, no inflation and no surge pricing.
• Only v1 transaction envelopes. Fee-bump and v0 envelopes, and the newer v2 preconditions (minimum sequence age or ledger gap, extra signers), are not supported. There are no protocol upgrades.
• A flat state hash replaces the BucketList, and the ledger skip list is not kept. So ledger hashes differ from stellar-core’s.
• History comes from peers, not from history archives. Checkpoints are every 64 ledgers.
• No message authentication code on every message, as stellar-core’s overlay has. A WebRTC link is checked once with a signed hello bound to its DTLS channel, and DTLS protects the rest. Announcements and consensus messages are signed end to end.
• Auto quorum favors liveness over safety when the network splits. Manual mode keeps SCP’s classic guarantees for the quorum you set.

• Open membership. In auto mode any key can join as a validator. Only validators known before a fork can decide it, so newcomers cannot. But colluding validators that outnumber the honest ones before a fork can. Groups that formed apart do not merge on their own; Resync moves a tab to the other chain.
• Public friendbot keys. Anyone can sign for the friendbot accounts. The rules cap the drain at 160,000 XLM per ledger, so the faucet’s 16 billion XLM could be emptied in about 100,000 ledgers, about 6 days. Anyone can also fill the 16 friendbot places in each ledger. A node still puts its own requests first in the transaction sets it proposes, so they get in when one of its sets wins.
• Stalls after departures. When validators leave and one of the remaining validators misbehaves, nomination can stall in some runs.
• Background tabs. Browsers throttle or freeze tabs in the background. A frozen tab does not vote until it wakes up.
• Strict networks. There is no TURN relay. Two browsers behind strict NATs or firewalls may not connect over WebRTC.