Skip to content

Add support for operating a Polkadot fork - #17

Closed
csmnprschv wants to merge 25 commits into
mainfrom
cosmin-polkadot-fork
Closed

csmnprschv wants to merge 25 commits into
mainfrom
cosmin-polkadot-fork

Conversation

@csmnprschv

Copy link
Copy Markdown
Collaborator

No description provided.

@csmnprschv csmnprschv self-assigned this Sep 9, 2026
@csmnprschv
csmnprschv requested a review from mordamax as a code owner September 9, 2026 03:41

@mordamax mordamax Sep 9, 2026 •

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i don't think we need to merge this (whole deployment) here, it should either fo to preview-net-v1 or keep unmerged, as deployment details are not something we want to ship here, especially deploy/polkadot-test/vm.env

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I won't merge it. I'm switching it to draft.

@csmnprschv
csmnprschv marked this pull request as draft September 9, 2026 16:53
@csmnprschv
csmnprschv force-pushed the cosmin-polkadot-fork branch 2 times, most recently from 2663b81 to c3b9a4f Compare September 16, 2026 14:42
mordamax and others added 11 commits September 17, 2026 22:36
Two things stand between a bitten fork and a working dotNS, and a fork
of a chain without Sudo can fix neither after the spawn.

The gateway has to be told which contract to dispatch into.
set_dispatcher_address() takes DispatcherAddressManager, which the
runtime binds to RootOrWhitelist in
system-parachains/asset-hubs/asset-hub-polkadot/src/individuality.rs,
and such a fork reaches neither arm: nothing holds Root, and
whitelisting a call needs a referendum. Until it is set, reserve_name()
and register_name() fail DispatcherAddressNotSet, the two calls that
reach the contract through call_dispatcher(). A network with Sudo needs
none of this, since the set-dispatcher-address service makes the same
choice from the fetched manifest and dispatches it after the spawn.
Without Sudo the bite is the only origin-free moment, which is already
how the seeded runtime upgrade gets its authorization.

Seeding an address for contracts that do not exist yet is not circular.
Every dotNS address is CREATE3(factory, keccak of a constant namespace,
label and kind) and the factory is CREATE(deployer, nonce 0), so the
whole set follows from one key and is computable offline.

The contracts are deployed afterwards by an Ethereum wallet, and no
wallet we hold has funds on a fork of a real chain. Unfunded, the deploy
does not fail cleanly: the pipeline is idempotent and resumable by
design, so it stops part way and leaves a half-deployed set for someone
to resume. A secp256k1 wallet owns no AccountId32, so revive spends from
a fallback account, the twenty address bytes followed by twelve 0xEE,
per to_fallback_account_id() in substrate/frame/revive/src/address.rs.
Endowing that at import costs one System::Account entry and saves a
signed transfer that would otherwise have to be repeated on every
rebite.

dotnsDeployer takes a list because the two roles differ, and the
descriptor names the factory key first. That key is single-purpose and
its nonce must be 0, since the factory address is what fixes the rest of
the set; dotns publishes it as FACTORY_DEPLOYER in
.github/workflows/deploy-contracts.yml. The pipeline runs from another
key, which _broadcastDeployUups() in scripts/deploy/BaseDeployer.s.sol
records as the proxy owner. Reproducing another network's ownership as
well as its addresses needs both funded.

One thing about the dispatcher inject is worth knowing before someone
tightens it: verifyInjects() reports it skipped, because DotnsGateway
arrives with the runtime the bite authorizes and the live metadata has
no such pallet, and for the same reason index.pallets.has() is the wrong
guard. The descriptor is.

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.

Unlike the dispatcher and the endowments this inject is type-checkable:
TransactionStorage is on the chain being bitten, so verifyInjects()
decodes it 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>
A Coinage instance wraps one asset as coins, and needs it on both Asset
Hub, its reserve chain, and People, which holds it by cross-chain
location. People is what forces the seed: CreateOrigin for its
by-Location instance is EnsureNever, so no signed origin can register
the foreign representation whatever deposit it offers, and
force_create() takes ForceOrigin, which is Root, which on a fork of
Polkadot is a 28-day referendum. Asset Hub would take a signed
create() against a deposit, so seeding it too is for one mechanism and
no post-spawn step rather than because nothing else could.

Nothing is hand-encoded. The index now carries a map's key type
alongside its value type and hashers, and encodeMapEntry() builds an
entry through the chain's own metadata: an Assets::Asset key is a u32 on
the reserve chain and a Location elsewhere, and only the metadata knows
which. It refuses a map whose hasher does not keep the key, and one with
more than one key.

The seeded state is only what do_force_create() produces: owner, issuer,
admin and freezer the same account, supply, deposit, accounts,
sufficients and approvals zero, status Live. There is deliberately no
balance state here. Minting, the conversion pool and the instance itself
are ordinary signed calls that run afterwards and compute their own;
seeding those instead would mean hand-building state whose parts must
agree, which verifyInjects() checks item by item and cannot catch across
items. It would also skip testing the extrinsics the fork exists to
test.

The descriptor test needs the same scratch PPN_HOME the dotNS checks
already built, so that helper moves up a scope, takes the key to patch
as an argument, and takes its description with it. Nothing else about
those checks changes.

The asset reuses XTRNL's id, decimals and minimum balance from
individuality-community's initial-setup, so a Coinage instance built the
same way behaves the same, and is named CASH. Owner is //Alice: the bite
endows Alice on every chain of a shared relay, and no other key here can
pay to mint. The location matches people_foreign_location() from those
same scripts.

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 rest follows from one fact: both pallets arrive with the runtime the
bite authorizes, so neither is in the metadata of the chain being
bitten. That rules out both obvious designs. Deriving the key from that
metadata resolves to nothing, silently, on exactly the chains this is
for; writing it unconditionally instead puts the key on every chain,
Bulletin included. So the key is hand-built, for the same reason
dotnsDispatcherInject() gives, and 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 one integer in the set is a map key. Assets::Asset is keyed by u32
on Asset Hub, so the seeded asset landed at 502462978 instead of
50000413.

Nothing caught it because verify() re-encoded with toHex() and decoded
from a hex string, so a wrong write agreed with a wrong read.

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>
previewnet and paseo-next-v2 are configured with
individuality-community's initial-setup scripts after a wipe. Those
reach their origins through Sudo.sudo(), which a fork of a public
network has no way to do.

add_chunks() and subscribe_whitelisted() carry pallet::authorize, so
they need no origin at all. dot --unsigned submits them directly, which
is why these scripts need no governance.

The Coinage instance is Sponsored rather than Sufficient.
create_sufficient_instance() takes AdminOrigin, and blessing a sponsored
one to Sufficient takes Root by referendum; create_sponsored_instance()
takes SponsorOrigin, which is EnsureSigned here. The cost is a held
creation deposit and a pot the sponsor keeps funded, and fund_pot() is
permissionless.

The scripts are run by hand, not wired as custom processes: everything
they configure arrives with the runtime upgrade, and zombienet gives
custom processes no ordering, so a wired script would fire at spawn
against a runtime without the pallets. The scripts are idempotent.

Ports come from config/ports.env, and the asset-hub para id and seeded
asset from the network descriptor. setup-common.sh refuses any network
but polkadot: the scripts configure a fork of Polkadot.

dot is already a dependency through scripts/ensure-dot-cli.sh and jq
through the Makefile; bc is new. setup-common.sh checks for all three.

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>
mordamax and others added 10 commits October 6, 2026 15:40
DUB's turn-api minted TURN credentials with nothing to relay them and an
empty server list. This runs eturnal next to DUB and wires the two
together, so p2p clients get working STUN/TURN servers from `POST
/api/v1/turn/issue`.

- New `turn` process: eturnal from eturnal.net on Linux, from the
processone Homebrew tap on macOS
- DUB gets `TURN_SECRET` and `ICE_SERVERS` from the same code that
configures eturnal. A deployment must set its own `TURN_SECRET` (base64
of a printable string)
- `/api/network` and the dashboard list the ICE servers, with a STUN
health probe
- `ppn nginx-conf` emits a TLS stream for `turns:` at a new
`{{GENERATED_STREAMS}}` marker, so the deploy template needs that marker
in its `stream {}` block
- `11-turn.zndsl` checks STUN, credential issuance and an authenticated
Allocate against the relay

Details in `docs/TURN.md`
systemd-logind runs with RemoveIPC=yes, which deletes the POSIX shared memory of a
normal uid when that user's last login session ends. Postgres runs as ubuntu, so an ssh
logout removed the dynamic shared memory segment under a live cluster. Every backend
started after that died with "could not open shared memory segment", while the
postmaster kept listening, because shared_memory_type defaults to mmap and is not an IPC
object. A port check and a process check both reported the database healthy.

Both deployments had been failing silently: previewnet since 2026-08-31, 1,402,419
errors, and the Polkadot fork since 2026-09-11, 285,937 errors. Each broke at the first
logout after its cluster was initialised.

Start the postmaster with dynamic_shared_memory_type=mmap, which puts the segments in
$PGDATA/pg_dynshmem. Files in the data directory are not IPC, so logind never touches
them. Passing it on the command line also covers the clusters already initialised with
posix in postgresql.conf.

Signed-off-by: Cosmin Paraschiv <cosmin@parity.io>
v0.6.0 ships every asset 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.

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.

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 release also removes DOTNS_GATEWAY_ENABLED, making the dotNS lane
unconditional, and requires ASSET_HUB_RPC_URL on the chain writer, which
0.5.0 read optionally. That key moves to the shared env: the writer
aborts at startup without it, and all-in-one alone having it was enough
only while the writer tolerated its absence.

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 and replaces a running one without
ETXTBSY. 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>
Members::OnboardingSize is how many queued keys a ring takes at once, so
on the lite collection it decides how long somebody who has just
registered waits before a ring holds them. people-polkadot creates that
collection at LitePeopleOnboardingSize, which is 3, and live Polkadot
People already carries it, so a fork inherits the 3. At 1 each
registration onboards on its own, which is what a fork used for testing
wants.

set_onboarding_size takes ManagerOrigin, RootOrTechnicalMaintenance on
people-polkadot, whose second arm is an OpenGov track on Asset Hub.
Neither is reachable after the spawn, so this is a seed or it is
nothing.

Unlike the other seeds this one replaces a value rather than supplying a
missing one. The collection exists on the chain being bitten, so Members
is in its metadata and the bite decode-checks the entry against that
runtime, where the attestation allowances can only be reported skipped.

Only the lite collection, which is what was asked for. The people
collection keeps the 10 it inherits.

Signed-off-by: Cosmin Paraschiv <cosmin@parity.io>
The pool opened at 1000 DOT against 4000 of the asset, a 1:4 rate. It
now opens at 10000 against 10000, the depth and the rate that were
asked for.

Coinage converts its fees through this pool, so the rate the pool opens
at is what a fee in the asset costs. Nothing on a fork tracks the
market, so that rate does not have to be the market's.

The liquidity branch runs only on an empty pool, so a fork already
running keeps the pool it has and this lands on the next bite.

Signed-off-by: Cosmin Paraschiv <cosmin@parity.io>
loadDescriptor parsed dubBuild, validated it and then left it out of the
object it returns, so every network read undefined and every consumer
took the testnet fallback. The polkadot fork fetched dub-0.6.0-testnet
rather than the polkadot build, and its generated toml carried the
invite-tickets service, database and environment that the polkadot build
does not have.

The gap read as working because the fallback is what every other network
wants, and because the polkadot path was only ever exercised by hand,
with the binary copied in and the roles named on the command line.

Signed-off-by: Cosmin Paraschiv <cosmin@parity.io>
The fork was asked to hold depth on both chains, 20000 on People and
5000000 on Asset Hub, evenly split. setup-coinage.sh does the People
half, as a side effect of what Coinage needs a pool for, and nothing
did the other.

Asset Hub is the reserve chain, so its Assets pallet keys the asset by
id while People keys it by location. AssetConversion names it by
location on both, and stores each pool under the pair with DOT first,
so a query naming them the other way round finds nothing.

The asset side is minted rather than bridged, the same as on People:
the bite seeds the registration with no supply and makes Alice the
issuer.

Run by hand after the upgrade like its siblings, and idempotent: it
creates no pool that exists and adds liquidity only to an empty one.

Signed-off-by: Cosmin Paraschiv <cosmin@parity.io>
csmnprschv and others added 3 commits October 6, 2026 16:36
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.

Signed-off-by: Cosmin Paraschiv <cosmin@parity.io>
The fork seeded its own asset: 50000413, named CASH, with min_balance
1. Referendum 1944 creates dotUSD as asset 7873, with min_balance
10000, and registers a conversion rate for it on People. Without that
rate, People cannot take fees in the asset, so a user holding only
dotUSD cannot move it in either direction. Creating the rate takes
Root, so the bite now seeds it with the registration.

setup-people-backing.sh mints People's supply to People's sovereign
account on Asset Hub. The setup mints People's side directly, so
without the backing a reserve withdraw to Asset Hub fails.

Drop the seed once the referendum is enacted, or the bite overwrites
the real asset.

Signed-off-by: Cosmin Paraschiv <cosmin@parity.io>
polkadot-test.substrate.dev can publish a Trinity stack descriptor, so a
host imports the Polkadot fork from
https://polkadot-test.substrate.dev/.well-known/trinity-stack.json

- Brings main into the fork branch: the descriptor and light specs, DUB
v0.8.0 and the TURN relay as merged there. The polkadot fork still picks
its DUB build from `dubBuild` in its network file, not main's global
`DUB_NETWORK`
- The descriptor names the fork as a copy of PCF's Polkadot descriptor
(https://stack.api.pcf.network/.well-known/trinity-stack.json), with
each chain's source block at the bite
- A bundle bitten before bite hashes were recorded gets them from the
source chains, so the bundle running now needs no re-bite
- When the source's dotNS registry has no code on the fork, the registry
comes from Asset Hub's `DotnsGateway::DispatcherAddress`. PCF deployed
dotNS after the bite, so the descriptor lists the dotNS the fork
actually runs and leaves out keys with no contract here
- `ppn start` now rejects a secrets file without `PPN_PROFILE`, so
`apply.sh` adds `PPN_PROFILE=local` to the existing one

Merging this fast-forwards the branch of
#17

---------

Signed-off-by: Cosmin Paraschiv <cosmin@parity.io>
Co-authored-by: Andrzej Sulkowski <developer@andrzej-sulkowski.com>
Co-authored-by: Cosmin Paraschiv <cosmin@parity.io>
Co-authored-by: Michał Gil <michal.gil@parity.io>
Co-authored-by: HadiKhai <35467011+HadiKhai@users.noreply.github.com>
Co-authored-by: RafalMirowski1 <107439038+RafalMirowski1@users.noreply.github.com>
Co-authored-by: Giuseppe Re <giuseppe.re@parity.io>
@csmnprschv

Copy link
Copy Markdown
Collaborator Author

Superseded by #70.

@csmnprschv csmnprschv closed this Nov 13, 2026
@csmnprschv
csmnprschv deleted the cosmin-polkadot-fork branch November 13, 2026 01:32
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