Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions config/ports.env
Original file line number Diff line number Diff line change
Expand Up @@ -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=
Expand Down
4 changes: 4 additions & 0 deletions docs/TRINITY-STACK.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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. |
21 changes: 21 additions & 0 deletions packages/cli/src/commands/trinity-stack.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<string, string>;
expiresAt?: number;
validFor?: number;
/** The dotNS deployment's contract addresses by contract name, from the dotns release. */
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -242,6 +245,23 @@ function readDotnsAddresses(binDir: string): Record<string, string> | 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<string, string> | undefined {
if (!value) return undefined;
const contracts: Record<string, string> = {};
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');
Expand Down Expand Up @@ -277,6 +297,7 @@ export async function trinityStack(ctx: ServiceContext): Promise<void> {
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
Expand Down
30 changes: 29 additions & 1 deletion packages/cli/tests/trinity-stack.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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');
Expand Down Expand Up @@ -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) }));
Expand Down
3 changes: 3 additions & 0 deletions packages/network-config/src/trinity-stack.ts
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,8 @@ export interface StackFacts {
validUntil?: number;
/** dotNS contract addresses by protocol registry key. */
dotns?: Record<string, string>;
/** Asset Hub contracts by name, such as `accountDataStore`, deployed on this instance. */
contracts?: Record<string, string>;
}

/**
Expand Down Expand Up @@ -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 }),
};
}
Loading