diff --git a/config/ports.env b/config/ports.env index b445948..f2375b2 100644 --- a/config/ports.env +++ b/config/ports.env @@ -124,11 +124,14 @@ PPN_PUBLIC_URL= # PPN_STACK_WEB_GATEWAY_URL: the dotNS web gateway serving this instance's names, listed as a # `web-gateway` service as written, such as https://testnet.li/?network=previewnet: the path # ends in `/`, and a query may follow. Only the instance the gateway resolves against sets it. +# PPN_STACK_CONTRACTS: Asset Hub contracts deployed on this instance, published as `contracts`, +# as name=address pairs separated by commas, such as accountDataStore=0x18b7…e044. # PPN_STACK_EXPIRES_AT: Unix seconds when the network is torn down, for spawner instances. # PPN_STACK_VALID_FOR: seconds a reader may use a copy before fetching it again. # PPN_STACK_REFRESH_SECONDS: how often the files are rewritten; default 6 hours. PPN_STACK_FAUCET_URL= PPN_STACK_WEB_GATEWAY_URL= +PPN_STACK_CONTRACTS= PPN_STACK_EXPIRES_AT= PPN_STACK_VALID_FOR= PPN_STACK_REFRESH_SECONDS= diff --git a/docs/TRINITY-STACK.md b/docs/TRINITY-STACK.md index 3e05103..aac1772 100644 --- a/docs/TRINITY-STACK.md +++ b/docs/TRINITY-STACK.md @@ -48,6 +48,9 @@ The descriptor is built from the dashboard model, so its URLs are the ones the d - `assets` and `coinage`: `stack.assets` and `stack.coinage` in the network file, for a network whose runtime has them. Previewnet pays in pUSD (asset 50000413 on Asset Hub) and runs Coinage instance 0 on People. +- `contracts`: the Asset Hub contracts a deployment lists in `PPN_STACK_CONTRACTS`, by name, such + as `accountDataStore`. A network file doesn't list them, because a contract deployed by hand + exists in one instance's state only. - `dotns`: the dotNS contract addresses by `DotnsConstants` key, such as `storeFactory`, plus `protocolRegistry` for the registry itself, so readers take them from the descriptor rather than read them from Asset Hub. @@ -98,6 +101,7 @@ into `config/ports.env`, where each has an empty default. The key goes in the se | `PPN_STACK_SECRET` | `0x` and 64 hex digits, in the secrets file. Signs the descriptor, and the pointer carries its public key. Ignored on a fork, which is always published unsigned: a descriptor signed with its source's key would be the source. | | `PPN_STACK_FAUCET_URL` | Adds a `faucet` service. | | `PPN_STACK_WEB_GATEWAY_URL` | Adds a `web-gateway` service, published as written: its path ends in `/`, and a query may follow, as in `https://testnet.li/?network=previewnet`. Only the instance the gateway resolves names against sets it, so staging leaves it empty when the gateway serves production. | +| `PPN_STACK_CONTRACTS` | Publishes `contracts`: the Asset Hub contracts deployed on this instance, as `name=address` pairs separated by commas, such as `accountDataStore=0x18b7116d0c15c1fffe55469bc163a304f702e044` for the account data store hosts read. A contract exists only in the chain state it was deployed to, so each deployment sets its own. | | `PPN_STACK_EXPIRES_AT` | Unix seconds when the network is torn down, for spawner instances. | | `PPN_STACK_VALID_FOR` | Seconds a reader may use a copy before fetching it again. | | `PPN_STACK_REFRESH_SECONDS` | How often the files are rewritten. | diff --git a/packages/cli/src/commands/trinity-stack.ts b/packages/cli/src/commands/trinity-stack.ts index 025544b..2e27fa4 100644 --- a/packages/cli/src/commands/trinity-stack.ts +++ b/packages/cli/src/commands/trinity-stack.ts @@ -68,6 +68,8 @@ export interface Settings { secret?: Uint8Array; faucet?: string; webGateway?: string; + /** Asset Hub contracts by name deployed on this instance, from PPN_STACK_CONTRACTS. */ + contracts?: Record; expiresAt?: number; validFor?: number; /** The dotNS deployment's contract addresses by contract name, from the dotns release. */ @@ -209,6 +211,7 @@ export async function writeStack( forkAt: bite ? Math.floor(Date.parse(bite.at) / 1000) : undefined, faucet: s.faucet, webGateway: s.webGateway, + contracts: s.contracts, dotns: dotnsFacts.dotns, expiresAt: s.expiresAt, validUntil: s.validFor ? Math.floor(now.getTime() / 1000) + s.validFor : undefined, @@ -242,6 +245,23 @@ function readDotnsAddresses(binDir: string): Record | undefined } } +/** + * PPN_STACK_CONTRACTS as a name-to-address map with lowercase addresses. Throws on an entry + * that isn't name=0x<40 hex digits>. + */ +export function parseContracts(value: string | undefined): Record | undefined { + if (!value) return undefined; + const contracts: Record = {}; + for (const entry of value.split(',')) { + const [name, address, extra] = entry.trim().split('='); + if (!name || extra !== undefined || !/^0x[0-9a-fA-F]{40}$/.test(address ?? '')) { + throw new Error(`PPN_STACK_CONTRACTS must be name=0x<40 hex digits>, comma-separated, not '${entry}'`); + } + contracts[name] = address.toLowerCase(); + } + return contracts; +} + function hexSecret(value: string | undefined): Uint8Array | undefined { if (!value) return undefined; if (!/^0x[0-9a-fA-F]{64}$/.test(value)) throw new Error('PPN_STACK_SECRET must be 0x and 64 hex digits'); @@ -277,6 +297,7 @@ export async function trinityStack(ctx: ServiceContext): Promise { secret: hexSecret(setting('PPN_STACK_SECRET')), faucet: setting('PPN_STACK_FAUCET_URL'), webGateway: setting('PPN_STACK_WEB_GATEWAY_URL'), + contracts: parseContracts(setting('PPN_STACK_CONTRACTS')), expiresAt: optionalNumber('PPN_STACK_EXPIRES_AT', setting('PPN_STACK_EXPIRES_AT')), validFor: optionalNumber('PPN_STACK_VALID_FOR', setting('PPN_STACK_VALID_FOR')), // `ppn fetch` writes the release's list only for a genesis network, so on any other one a diff --git a/packages/cli/tests/trinity-stack.test.ts b/packages/cli/tests/trinity-stack.test.ts index a088fc6..b7217e4 100644 --- a/packages/cli/tests/trinity-stack.test.ts +++ b/packages/cli/tests/trinity-stack.test.ts @@ -13,7 +13,7 @@ import os from 'node:os'; import path from 'node:path'; import { loadDescriptorOnly, P2P_PORTS, PORTS, RELAY_BASE_PORT } from '@parity/ppn-network-config'; import { checkSpec, lightSpecGenesis, open } from '@parity/trinity-stack'; -import { trinityStack, writeStack, type Settings } from '../src/commands/trinity-stack.js'; +import { parseContracts, trinityStack, writeStack, type Settings } from '../src/commands/trinity-stack.js'; import type { ServiceContext } from '../src/commands/service-context.js'; const net = loadDescriptorOnly('previewnet'); @@ -120,6 +120,34 @@ describe('writeStack — what it writes', () => { assert.ok(open(read('trinity-stack.json'), written.pointer).signed); }); + // Hosts read the account data store's address from the descriptor, and readers accept only + // lowercase hex there, so a checksummed address from a deploy log still has to publish. + it('publishes PPN_STACK_CONTRACTS by name with lowercase addresses', async () => { + const contracts = parseContracts( + 'accountDataStore=0x18B7116D0c15c1FFFe55469bc163a304f702E044, other=0x898a76b646cb1ebb3083dca781bab4f167be6801' + ); + const { written } = await writeStack({ net }, settings({ contracts })); + assert.deepEqual(open(read('trinity-stack.json'), written.pointer).descriptor.contracts, { + accountDataStore: '0x18b7116d0c15c1fffe55469bc163a304f702e044', + other: '0x898a76b646cb1ebb3083dca781bab4f167be6801', + }); + }); + + // A fork carries the contracts deployed on it, as polkadot-test does, though it is unsigned. + it('publishes the contracts on a fork too', async () => { + stamp({ mode: 'fork' }); + const contracts = parseContracts('accountDataStore=0x4b50651b01f4fa0387957b2b4de54785d4435a50'); + const { written } = await writeStack({ net }, settings({ contracts })); + assert.deepEqual(open(read('trinity-stack.json'), written.pointer).descriptor.contracts, contracts); + }); + + it('rejects a PPN_STACK_CONTRACTS entry that is not name=address', () => { + const address = '0x18b7116d0c15c1fffe55469bc163a304f702e044'; + for (const value of ['accountDataStore', `=${address}`, 'accountDataStore=0x18b7', `a=${address}=x`, `a=${address},`]) { + assert.throws(() => parseContracts(value), /PPN_STACK_CONTRACTS must be name=0x<40 hex digits>/); + } + }); + it('never signs a fork, whose machine may hold its source key', async () => { stamp({ mode: 'fork' }); const { written } = await writeStack({ net }, settings({ secret: new Uint8Array(32).fill(7) })); diff --git a/packages/network-config/src/trinity-stack.ts b/packages/network-config/src/trinity-stack.ts index 9a2d733..0ca543f 100644 --- a/packages/network-config/src/trinity-stack.ts +++ b/packages/network-config/src/trinity-stack.ts @@ -42,6 +42,8 @@ export interface StackFacts { validUntil?: number; /** dotNS contract addresses by protocol registry key. */ dotns?: Record; + /** Asset Hub contracts by name, such as `accountDataStore`, deployed on this instance. */ + contracts?: Record; } /** @@ -161,6 +163,7 @@ export function trinityStackModel(net: NetworkDef, model: DashboardModel, facts: services, ...(net.stack?.assets && { assets: net.stack.assets }), ...(net.stack?.coinage && { coinage: net.stack.coinage }), + ...(facts.contracts && { contracts: facts.contracts }), ...(dotns && { dotns }), }; }