[Whitelisted Caller] Enable User Onboarding via the Polkadot App - Supersedes 1955

inWhitelisted Caller
22 days ago
Executed

This referendum substitutes referendum #1955 with a reduced scope. It keeps only the onboarding parameters, the attestation allowances and the dispatcher, and leaves the base app names for a separate proposal later, so that each decision can be voted on by itself. Its Fellowship whitelist, Fellowship referendum #664, also removes the call of #1955 from the whitelist, so #1955 can no longer take effect.

PCF owns and publishes the Polkadot App under #1082 and #1573.

This referendum enables the last on-chain parameters needed for username registration in the Polkadot App. Approving this referendum also confirms PCF as the operator of the onboarding service.

When a new user joins through the App, they choose a username. Behind the scenes, the onboarding service does two things:

  • registers the user as a lite person on the People chain;

  • reserves the user's .dot name on Asset Hub.

    A lite person is a light form of personhood on the People chain. In this case it shows that an account comes from an app installation the onboarding service has verified and attested, not that it belongs to a unique human. It lets the user claim small fee-free allowances, such as for messaging and app storage, anonymously through a membership ring. On-chain it records only the user's account and a public membership key: no real name, email, or other personal details. The username the user picks is public, as every .dot name is.

Both systems already exist on Polkadot. What is missing today is the allowance and routing setup that lets the onboarding service use them. Until those values are set, new registrations remain pending.

This proposal sets those values. It does not upgrade any runtime, deploy new code, or request Treasury funding.

At a Glance

TrackWhitelisted Caller
RequiresFellowship whitelist in Fellowship referendum #664
Substitute forReferendum #1955
Can enact fromRelay block 33698272, about 2 November 2026, 09:00 CET. Fellowship referendum #664 was proposed before relay block 33583072, so its whitelist reaches Asset Hub before then
Inner call0x33ed6c42bb4078327a29bf59f8cb34c9df2f93703c3c624e47dc967b4a4af03f (118 bytes)
Preimage0x681f287489eea7db8bf4a37c03d4f8f861fa69565c313aa5e45dbf1a6ff29325 (120 bytes), noted on Asset Hub
Verification releasepcf-refs release

What Voters Are Approving

The referendum contains three existing calls, bundled together and executed with Root through the Whitelisted Caller track.

CallResult
DotnsGateway.increase_attestation_allowance(attester, 1,000,000) on Asset HubAllows the attester to reserve up to 1,000,000 user names through the dotNS gateway.
DotnsGateway.set_dispatcher_address(0xA06d1CB1e3FedFF7b5dFa779b4Cc61703F8A46A1) on Asset HubPoints the gateway to the dotNS PopController from the live dotNS release.
PeopleLite.increase_attestation_allowance(attester, 1,000,000) on People, sent from Asset HubAllows the attester to register up to 1,000,000 lite people.

The main parameters are:

ParameterValue
Attester15sDLj4T9NnCtT665koDMxBs1PZw3rzDc6wcz9tN9kKTQ2zj
Allowance1,000,000 on Asset Hub and 1,000,000 on People
Dispatcher0xA06d1CB1e3FedFF7b5dFa779b4Cc61703F8A46A1

An allowance is not a transfer of funds. One unit is consumed only when one user is onboarded, and each attestation is visible on-chain.

This referendum does not:

  • upgrade any runtime;
  • deploy new contracts;
  • move Treasury funds;
  • grant any .dot names;
  • give the attester control over user funds.

It only sets the parameters listed above.

Accounts and Custody

There are two important accounts in this proposal: the attester, which handles user onboarding, and the owner of the dotNS contracts, which can upgrade the dispatcher.

Attester

The attester is:

15sDLj4T9NnCtT665koDMxBs1PZw3rzDc6wcz9tN9kKTQ2zj

It is a pure proxy, so no private key exists for the attester account itself. It was created in Asset Hub extrinsic 21514129-2.

To onboard users, the service signs as the attester with the onboarding service key:

12jrwPAgzi1iTCSxxbdjzmLitdeKB87xh8yeriV2ihWH8vBt

That key is held by the PCF.

If the signing key were compromised, the holder could register lite people and reserve names for accounts of their choice, up to the remaining allowance on each chain. They could also act as the attester account itself, including over its own funds and delegates.

They could not touch user funds, other accounts, the dotNS contracts owner, or the dotNS contracts.

The response path is clear:

  • PCF can replace the signing key with one multisig action. The attester account and its allowances stay the same, so no referendum is needed.
  • Governance can stop further onboarding at any time with clear_attestation_allowance on either chain, through Whitelisted Caller or Root.

Lite people already registered would remain registered. Removing them would require a separate governance action.

dotNS Contracts Owner

The dispatcher is an upgradeable proxy. Its owner is:

0xA5C4c241985D77A0296a0FB83E0FA5905e9E39De

This maps to the Asset Hub account:

13oaSihqaoZ8zprCpbnuqdQqi9zLw99rwkSk3zG2hbzxU3ke

The mapping is on-chain:

Revive.OriginalAccount(0xA5C4c241985D77A0296a0FB83E0FA5905e9E39De) = 13oaSihqaoZ8zprCpbnuqdQqi9zLw99rwkSk3zG2hbzxU3ke

The account is also a pure proxy. It was created by PCF's 4-of-6 multisig in Asset Hub extrinsic 20362133-2, and that multisig, 12mD2ibwcFiVNiDrzcjXHvsz7aDhgkCdY1Do8wUyhzSX6S9a, is its only delegate.

It has the on-chain identity "PCF" and owns the live dotNS contracts listed in the dotNS v1.0.0-pcf.1 release.

Why the Allowance Is 1,000,000

Each new user consumes one allowance unit on each chain:

  • one on People to become a lite person;
  • one on Asset Hub to reserve their .dot name.

An allowance of 1,000,000 on each chain therefore covers about one million new users.

PCF considered a smaller first tranche, such as 100,000, with later top-ups. The trade-off is that each top-up would require another full governance process. If the allowance runs out while a top-up is pending, new users cannot finish onboarding.

The larger allowance is bounded in several ways:

  • it moves no funds;
  • each unit is used only by onboarding one user;
  • every registration is a public on-chain event;
  • the remaining allowance is readable from storage at any time;
  • governance can clear the allowance on either chain at any time.

When the allowance eventually runs low, PCF would request a top-up before onboarding pauses. If the Fellowship or the community prefers a smaller first tranche, PCF is open to that.

Prior Review and Changes

PCF first discussed this request publicly with the Technical Fellowship on the Polkadot Forum and in the Fellowship open channel.

The request first had five calls. After Fellowship feedback, PCF removed the Bulletin storage authorizer (app storage on Bulletin can be bought without governance through paid lite personhood on People), fixed the enactment block and published everything needed to reproduce the call. That is the currently proposed version: referendum #1955, whitelisted by Fellowship referendum #639.

This substitute makes two changes:

  • Onboarding parameters only. The name grants are removed. The base app names will come in a separate proposal later, so each decision can be voted on by itself. The three remaining calls are byte for byte the same as in the currently proposed version.
  • Retires #1955. Fellowship referendum #664 removes the #1955 call (0x90640a174e1d62b5645f31cb053d562e95a63881fd1e0f9197edbbcf83e21fad) from the whitelist in the same step that whitelists this one. After that, #1955 can only enact without effect, so the allowances cannot be granted twice.

The enactment block is fixed again, so the referendum does not enact before relay block 33698272, about 2 November 2026, 09:00 CET, even if it passes earlier. Fellowship referendum #664 was proposed before relay block 33583072 (about 25 October 2026, 09:00 CET), so even with its full 7-day decision period its whitelist reaches Asset Hub before then. If this referendum is approved after 2 November, it enacts 10 minutes after its approval, until its 28-day decision period ends.

How to Verify It

The verification release includes the call data, decoded call breakdown, and the reports used to check the proposal.

It covers three types of checks:

  • Preflight on live state: confirms that both allowances are currently empty, no dispatcher is set, and the #1955 call is still whitelisted. It also reports the dispatcher's owner and the account behind it.
  • Dry runs on live state: runs every call with the origin it will have at execution time. The referendum currently fails only with CallIsNotWhitelisted, as expected, until the Fellowship whitelist from Fellowship referendum #664 lands.
  • Full rehearsal on a fork of live Polkadot: enacts both referenda through the scheduler and confirms the final state: the #1955 call leaves the whitelist, each allowance moves from 0 to 1,000,000, and the dispatcher is set.

To reproduce the checks:

git clone https://github.com/Polkadot-Community-Foundation/pcf-refs
cd pcf-refs
npm ci
npm test
npm run decode
npm run preflight
npm run dry-run
npm run rehearse

The proposal README explains each call, what each check proves, and how to compare this referendum with Fellowship referendum #664 at the byte level.

Known Trade-Off

The Fellowship raised one important limitation, and PCF agrees that it should be stated clearly.

The dotNS gateway calls the dispatcher with Root origin. The dispatcher is an upgradeable contract owned by PCF. If PCF upgraded that contract with an illegitimate version of the source, the new code could call other contracts that trust Root origin, such as the dotNS name whitelist.

That does not give system-level Root access. It cannot upgrade the runtime, spend from other accounts, or act as Root over XCM. Still, it is a real trust assumption until the next fix lands.
The necessary changes have already been notified to both parity and the fellowship such that a future runtime version can own the contracts in this referendum:

Until the improvements are enacted, any upgrade would also be a public on-chain event. If the community wants a stronger interim guarantee, PCF can place dotNS ownership behind a public time delay that a referendum can veto.

Governance Keeps Control

Everything this referendum changes can be reversed by governance.

ChangeHow governance can undo it
Attestation allowancesCall clear_attestation_allowance on the relevant chain.
Dispatcher addressCall set_dispatcher_address with a different address.

Comments (1)

18 days ago

GOVERNANCE & TECHNICAL SECURITY AUDIT

TARGET: POLKADOT OPENGOV REFERENDUM #1958 (USER ONBOARDING OVERRIDE)

CLASSIFICATION: TECHNICAL PARAMETER VERIFICATION & PROXY HARDENING REPORT

1. EXECUTIVE SUMMARY & SYSTEMIC CONTEXT

This document serves as an independent technical parameter and structural risk evaluation of Polkadot OpenGov Referendum #1958 (Whitelisted Caller track). The objective is to verify call path integration, assess cross-chain state parameters between Asset Hub and the People Chain, and isolate configuration vectors to protect system infrastructure from operational downtime or unauthorized privilege escalation.

Systemic Context & Operational Trade-Off:
This deployment reflects an acknowledged, pragmatically necessary operational trade-off: utilizing targeted execution vectors to bypass application-layer coordination friction and maintain user onboarding velocity across the ecosystem. While highly effective for immediate delivery, routing Root-privileged programmatic calls into an upgradable smart contract without a cryptographic time-lock shifts the operational risk boundary onto the keyholders. The report provides the parameters required to secure and harden this specific trade-off.

2. PARAMETER VERIFICATION & DRY-RUN TELEMETRY

• Call Path Origin: pallet_whitelisted_caller::dispatch_whitelisted_call_with_preimage via Technical Fellowship Whitelist (Fellowship Referendum #664). Verified.
• Target Configurations:

  • DotnsGateway.increase_attestation_allowance set to 1,000,000 on Asset Hub.
  • DotnsGateway.set_dispatcher_address mapped to 0xA06d1CB1e3FedFF7b5dFa779b4Cc61703F8A46A1.
  • PeopleLite.increase_attestation_allowance set to 1,000,000 on the People Chain.
    • Enactment Bounding: Strictly locked to execute no earlier than relay block 33,698,272 (~November 2, 2026), preventing parallel state collisions by ensuring Fellowship Referendum #664 purges the broken preimage of Referendum #1955 beforehand.
    • Capital Impact: Zero-denominated storage registration keys. Draws 0 DOT from the Public Treasury.

3. ISOLATED THREAT VECTORS & SEVERITY CLASSIFICATIONS

• [TR-01] Upgradable Proxy Contract Architecture Without On-Chain Time-Lock

  • Severity: HIGH
  • Description: The onboarding dispatcher utilizes an upgradeable proxy pattern. Ownership settles cryptographically on a pure proxy controlled by the Polkadot Community Foundation's (PCF) off-chain multisig (13oaSihqaoZ8zprCpbnuqdQqi9zLw99rwkSk3zG2hbzxU3ke). In its current state, mutations to the contract bytecode execute instantaneously upon reaching the multisig signature threshold, bypassing on-chain governance or Technical Fellowship review windows.
  • Impact: A compromise of the off-chain multisig signers could allow unauthorized logic mutations that interact with Root-guarded gateway modules, presenting an instantaneous attack surface before on-chain emergency cancellation tracks (Referendum Killer/Canceller) can be mobilized by delegates.

• [OR-02] Economic & Technical Scaling Bounding

  • Severity: LOW
  • Description: The 1,000,000 lite-person account cap is zero-denominated, drawing 0 DOT from the Public Treasury. It inflicts no direct fiscal overhead or capital risk on the system state.

4. ACTIONABLE ENGINEERING REMEDIATION & HARDENING ROAD MAP

• Short-Term Hardening (Immediate Phase): Implement an on-chain time-delay parameter guarding the PCF proxy owner account on Asset Hub. Enforcing a mandatory 7-day latency between a proposed contract upgrade and its execution blocks zero-day exploits, providing active governance delegates and institutional curators ample time to review bytecode changes and invoke emergency veto tracks if anomalies are detected.
• Long-Term Migration Path: Accelerate the integration of Parity issue #195 and Fellowship issue #1326 to transfer full contract ownership from the off-chain foundation identity directly into native runtime pallets on the People Chain, eliminating the off-chain multisig trust assumption entirely.

Polkassembly is now a read-only archive. Commenting is disabled.

Proposal Passed

    Polkassembly - Referendum #1958