Skip to content

Add support for operating a Polkadot fork - #70

Draft
csmnprschv wants to merge 17 commits into
mainfrom
cosmin-polkadot-fork-v2
Draft

csmnprschv wants to merge 17 commits into
mainfrom
cosmin-polkadot-fork-v2

Conversation

@csmnprschv

Copy link
Copy Markdown
Collaborator

No description provided.

mordamax and others added 17 commits November 13, 2026 03:04
Signed-off-by: Cosmin Paraschiv <cosmin@parity.io>
Signed-off-by: Cosmin Paraschiv <cosmin@parity.io>
Signed-off-by: Cosmin Paraschiv <cosmin@parity.io>
Signed-off-by: Cosmin Paraschiv <cosmin@parity.io>
A bitten Bulletin cannot store anything. authorize_account() takes
Authorizer, which is Root, a sibling parachain in AllowedParachainIds,
or an account in AllowedAuthorizers. On a fork of Polkadot the first is
unreachable and the other two are empty: live Polkadot Bulletin has no
entry in either, because there authorizers arrive by governance rather
than being configured. bulletin-deploy's bulletinAutoAuthorize fails
BadSigner as a result, which is how this surfaced.

previewnet never meets it because the bulletin runtime's genesis preset
seeds Sr25519Keyring::Eve with 100_000 transactions and 100 GiB. A fork
has no genesis, so the same entry is written at import instead, with the
budget taken from that preset rather than invented; valid_until None and
feeless true are what BuildGenesisConfig sets alongside it.

Alice rather than Eve: the bite already endows Alice on every chain of a
shared relay, and endowing Eve as well would be a second inject for no
gain. paseo-next-v2 has Alice among its three authorizers, so an Alice
authorizer is precedented on a live network, and the pallet does not
check that an authorizer and the account it authorizes differ.

The map entry goes in alone, without the provider reference the pallet's
own paths add. That is safe while the authorizer holds a balance, which
provides for it, and it cannot be supplied afterwards.

This inject is type-checkable: TransactionStorage is on the chain being
bitten, so verifyInjects() decodes its value against real metadata
instead of skipping it. Guarded on the pallet being present, so the same
descriptor field is inert on a chain without it.

Signed-off-by: Cosmin Paraschiv <cosmin@parity.io>
Two quotas share the AttestationAllowance name. PeopleLite's counts how
many people a verifier may attest, spent by attest(); DotnsGateway's
counts how many names an attester may reserve, spent by reserve_name().
The identity backend needs both, and a fresh fork gives it neither, so
nobody becomes a lite person and nobody who did could take a username.

Granting either takes an origin a fork cannot raise. PeopleLite's
AttestationAllowanceManager is EnsureRoot on people-polkadot, and
DotnsGateway's is RootOrWhitelist on asset-hub-polkadot, whose second
arm is an OpenGov track. Neither has a signed arm and neither is
reachable after the spawn on a fork of a chain whose Root is a 28-day
referendum, so this is a seed or it is nothing.

One function covers both because the storage is identical:
StorageMap<Blake2_128Concat, AccountId, u32, ValueQuery>, and both
increase_attestation_allowance() implementations only saturating-add a
count. So the count is the whole state the call produces, with nothing
else to construct.

The descriptor pairs each chain with its pallet in attestation.on.

Alice as the attester, since the bite already endows her on every chain
of a shared relay, and a million each to match
PEOPLELITE_ATTESTATION_ALLOWANCE and DOTNSGATEWAY_ATTESTATION_ALLOWANCE
in individuality-community's initial-setup.

Signed-off-by: Cosmin Paraschiv <cosmin@parity.io>
polkadot-js overrides toHex() on its integer types to emit big-endian,
and createType(type, '0x...') reads a hex string as a big-endian number.
Only bare multi-byte integers are affected.

The integers in the set, RetentionPeriod and AttestationAllowance, are
hand-built little-endian, but verify() and verifyInjects() decoded them
from a hex string as big-endian and re-encoded them with toHex(), so any
4-byte value passed.

scaleHex() goes through toU8a(), and every encode goes through it,
including the struct ones toHex() would have got right; every decode
passes hexToU8a() for the same reason. The test stubs take bytes now, as
the real registry does, and fork-codec pins what a u32 encodes to, what
0x01000000 decodes to from bytes and from a hex string, and the storage
key a u32-keyed asset lands under.

Signed-off-by: Cosmin Paraschiv <cosmin@parity.io>
Stripping bootNodes was meant to keep a fork off the source network and
does not. Protocol names are built from the genesis hash plus the fork
id, and a fork keeps the source's genesis hash, so without a fork id its
names are byte-identical to the source's: it sits on the source's DHT
and finds nodes there. An asset-hub collator was found holding
established connections to public mainnet nodes while its spec carried
zero bootNodes, which is a forked node rejoining the source network and
following its longer chain: success on every metric while not being a
fork at all.

The chain spec's fork_id field is what takes it off that DHT. Nodes only
synchronize with other nodes holding the same value, and it names
protocols and nothing else, so it is not part of the genesis hash or the
state and snapshots taken before it still restore.

Leaving the source's DHT is also what makes the missing bootNodes fatal,
which is why the fork id and the bootnode land together. A fork with a
fork id has a DHT of its own, and Kademlia inserts peers manually, so
connecting to a peer never adds it to the routing table: the table fills
from bootnodes or from identify, and a spec shipping neither leaves
every node's table empty and authority discovery resolving no addresses.
Measured on a fork with a fork id and no bootnode, every one of a
validator's random Kademlia walks returned peers-not-found. With one
bootnode injected, the same node reported nine walks and nine
peers-found, six records stored, and published its own addresses.

Only the first relay node can be named ahead of the spawn, because it is
the only one whose p2p port the generator pins; the rest take ephemeral
ports that change every time. One entry is enough, since Kademlia walks
out from it to the rest. Every node then bootstraps through that one,
which the fork already depends on anyway: it is the node every collator
reaches the relay through. Parachain specs ship none, because a fork
runs a single collator per parachain and has no parachain peer to find.

Only the shipped specs get a fork id or a bootnode. The copies the bite
itself runs against keep the source's bootNodes and no fork id, because
it has to reach the real network to warp-sync from it.

These changes need a patched polkadot-parachain, and the fork runs one.
Cumulus hardcodes fork_id: None when it builds the relay node a collator
embeds (relay-chain-minimal-node/src/network.rs), so a stock collator
keeps its relay node on /<genesis>/kad while the validators move to
/<genesis>/<fork id>/kad. Its collation protocol still carries the fork
id, so it connects to them and then resolves none of them, and the relay
keeps producing blocks while the parachains stop. I will fix that
upstream.

Signed-off-by: Cosmin Paraschiv <cosmin@parity.io>
Signed-off-by: Cosmin Paraschiv <cosmin@parity.io>
Signed-off-by: Cosmin Paraschiv <cosmin@parity.io>
Signed-off-by: Cosmin Paraschiv <cosmin@parity.io>
DUB ships every release twice and fixes the People runtime at build
time: the build selects the vendored metadata and decides whether the
invite-tickets roles exist at all. The two are different binaries under
one name, so a network has to say which it needs, and one global
DUB_NETWORK cannot serve previewnet and a fork of Polkadot alike.

That is dubBuild in the descriptor, defaulting to testnet. Only the
Polkadot fork sets polkadot, whose People runtime carries neither Game
nor ProofOfInk. Naming a role the binary does not have fails its role
gate at boot, so a wrong answer is not a degraded network but one that
will not start. loadDescriptor() carries the field to fetch and to both
toml generators.

postgres.sh and service.sh both take the database list from the
generated TOML rather than holding their own copies. postgres.sh creates
them; service.sh blocks until each exists before starting its role, so a
list longer than what was created costs that role its whole 120-second
timeout at every start, which is what the polkadot build hit on
invite_tickets. An unset list is fatal rather than defaulted: no default
is right for both builds, and a wrong one is silent.

The build goes in the provenance stamp as well as the asset name.
Without it a switch is undetectable, because reusable() compares a file
to its own recorded hash: the polkadot binary the fork left behind
matches its own stamp exactly, so previewnet reuses it and runs the
wrong metadata. The binary is now staged and renamed into place rather
than unlinked and copied, which is atomic: nothing starts a half-copied
binary, and a failed copy leaves the old one in place. Keeping the path
shared and re-fetching on a switch is the cheaper half of that trade:
moving the binary per network would leave service.sh resolving it
differently from postgres-dist and identity-docs, which really are
shared, and zombienet hands a custom process no NETWORK to key on.

Signed-off-by: Cosmin Paraschiv <cosmin@parity.io>
zombienet unpacks a node's db_snapshot over its base path on every
spawn, whether or not a database is already there, and the extraction
overwrites the files it carries. So a resumed fork was handed the
bite-time snapshots on every restart and could rewind to the bite
block. On 2026-09-26 the polkadot fork did after a restart, and lost
everything created after the spawn: the pools, the Coinage instance,
the PSM and dotNS.

start.ts said the opposite, that zombienet restores a snapshot only
into an empty base path, and the resume path relied on it. Both
v0.4.15 and current main do the unpack unconditionally, in
initialize_db_snapshot().

A resume now regenerates the config with --resume, which leaves the
db_snapshot lines out, so there is nothing to unpack. Only the
generated config is rewritten; a --toml the caller supplied is left
alone.

zombie-cli spawns a copy of that config, so the regeneration has to run
before the copy is made. prepareSpawn() settles the data directory,
regenerates on a resume, then writes the spawn config, and its tests
check that a resumed fork's spawn config carries no db_snapshot.

Signed-off-by: Cosmin Paraschiv <cosmin@parity.io>
…source's is absent

Signed-off-by: Cosmin Paraschiv <cosmin@parity.io>
Signed-off-by: Cosmin Paraschiv <cosmin@parity.io>
Signed-off-by: Cosmin Paraschiv <cosmin@parity.io>
Mainnet runs v2.5.3 on all four chains, so a plain bite is the normal
case and UPGRADES= is only for a runtime under test. The Polkadot
runbook still described a fork that exists to enact 2.5, and README.md
still gave the live upgrade delay, not the bite's 30 blocks.

No doc mentioned the fork id the bite sets on every spec, or that the
collators need a build with the cumulus fork-id fix. A fetch puts the
stock build back, and while the collators run the patched one,
apply.sh's fetch fails, because it rewrites the binary in place. The
box README now says to stop the network around an apply.

The runbook also sent readers to /tmp for node logs, which a fork
writes to its data directory, and its manual setup steps lacked the
TURN stream block and the secrets file that apply.sh adds.

networks/README.md gains rows for dubBuild, bulletinAuthorizer and
attestation, and polkadot.json says why its stack pointer has no key.

Signed-off-by: Cosmin Paraschiv <cosmin@parity.io>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants