WikiDeck/wikideck
3
0
Fork 1
Code Issues 8 Pull Requests Actions Packages Projects 2 Releases Wiki Activity

V2.1 (#21)

Browse Source 
Working version Reviewed-on: #21
This commit was merged in pull request #21.
This commit is contained in:
eric
2026-11-01 22:07:51 +00:00
parent 1edf2e6200
commit 636f5b9c77
80 changed files with 4065 additions and 549 deletions
Download Patch File Download Diff File Expand all files Collapse all files
server/testnet/consensus.ts
+122 -27
View File
@@ -1,15 +1,17 @@
import { createHash, createPublicKey, verify } from 'node:crypto';
import { z } from 'zod';
import { NETWORK, CONSENSUS, headerMessage, blockClaimMessage, nftTransferMessage, statsSnapshotTuple,
type BlockHeader, type TestnetBlock, type NftTransfer, type NftState, type MiningTemplate } from '../../shared/testnet.ts';
import { NETWORK, CONSENSUS, MAX_TARGET, headerMessage, blockClaimMessage, nftTransferMessage, nftTradeMessage, statsSnapshotTuple,
type BlockHeader, type TestnetBlock, type NftTransfer, type NftState, type NftStateLayer,
isNftTrade, type NftStateView, type NftTrade, type TestnetTransaction, type MiningTemplate } from '../../shared/testnet.ts';
import type { Article } from '../../shared/protocol.ts';
import { deriveStats, type MintStatsSnapshot } from '../../shared/enrichment.ts';
import type { PowEngine } from './randomx.ts';
import { NETWORK_GENESIS_TIME } from '../../shared/network.ts';
export const sha256 = (data: string | Uint8Array) => createHash('sha256').update(data).digest('hex');
export const MAX_TARGET = `0fff${'f'.repeat(60)}`;
export { MAX_TARGET };
// Consensus manifest: an independently running node derives exactly the same genesis.
export const GENESIS_TIME = 1_792_411_200;
export const GENESIS_TIME = NETWORK_GENESIS_TIME;
export const CHAIN_ID = sha256(JSON.stringify([NETWORK, CONSENSUS, GENESIS_TIME, MAX_TARGET]));
export const GENESIS_HASH = sha256(`${NETWORK}:genesis:${CHAIN_ID}`);
export const INITIAL_KEY = sha256(`${NETWORK}:initial-key:${CHAIN_ID}`);
@@ -19,6 +21,25 @@ const signature = z.string().regex(/^[A-Za-z0-9+/]+={0,2}$/).length(88);
const integer = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
export const transferSchema = z.object({ network: z.literal(NETWORK), chainId: z.literal(CHAIN_ID),
cardHash: hex, from: hex, to: hex, sequence: integer, publicKey: key, signature }).strict();
const tradeLegSchema = z.object({ cardHash: hex, sequence: integer }).strict();
export const tradeSchema = z.object({ type: z.literal('trade'), network: z.literal(NETWORK), chainId: z.literal(CHAIN_ID),
proposer: hex, counterparty: hex, offered: z.array(tradeLegSchema).min(1).max(CONSENSUS.maxTradeCards),
requested: z.array(tradeLegSchema).min(1).max(CONSENSUS.maxTradeCards),
proposerPublicKey: key, proposerSignature: signature, counterpartyPublicKey: key,
counterpartySignature: signature }).strict().superRefine((trade, ctx) => {
const offered = new Set(trade.offered.map(leg => leg.cardHash));
const requested = new Set(trade.requested.map(leg => leg.cardHash));
if (trade.proposer === trade.counterparty) ctx.addIssue({ code: 'custom', message: 'Trade parties must differ' });
if (offered.size !== trade.offered.length || requested.size !== trade.requested.length ||
trade.requested.some(leg => offered.has(leg.cardHash))) {
ctx.addIssue({ code: 'custom', message: 'Trade cards must be unique and cannot appear on both sides' });
}
if (!verifySignature(trade.proposerPublicKey, trade.proposer, nftTradeMessage(trade), trade.proposerSignature) ||
!verifySignature(trade.counterpartyPublicKey, trade.counterparty, nftTradeMessage(trade), trade.counterpartySignature)) {
ctx.addIssue({ code: 'custom', message: 'Trade requires valid signatures from both parties' });
}
});
export const transactionSchema = z.union([transferSchema, tradeSchema]);
const articleSchema = z.object({ pageId: integer.positive(), title: z.string().trim().min(1).max(200),
extract: z.string().trim().min(1).max(1000), image: z.string().url().max(1500),
url: z.string().url().max(500), revisionId: integer.positive(),
@@ -70,10 +91,10 @@ const statsSnapshotSchema = z.object({ capturedAt: z.string().datetime(), revisi
ctx.addIssue({ code: 'custom', message: 'Derived statistics do not match the page metrics', path: ['stats'] });
}
});
export const blockSchema = z.object({ version: z.literal(4), network: z.literal(NETWORK), chainId: z.literal(CHAIN_ID),
export const blockSchema = z.object({ version: z.literal(6), network: z.literal(NETWORK), chainId: z.literal(CHAIN_ID),
height: integer, previousHash: hex, createdAt: integer, article: articleSchema, statsSnapshot: statsSnapshotSchema, owner: hex,
publicKey: key, nonce: integer, target: hex, key: hex, transactionsRoot: hex, stateRoot: hex,
hash: hex, tokenId: hex, powHash: hex, signature, transactions: z.array(transferSchema).max(CONSENSUS.maxTransactions) }).strict();
hash: hex, tokenId: hex, powHash: hex, signature, transactions: z.array(transactionSchema).max(CONSENSUS.maxTransactions) }).strict();
export function address(publicKey: string): string { return sha256(Buffer.from(publicKey, 'base64')); }
export function verifySignature(publicKey: string, owner: string, message: string, sig: string): boolean {
@@ -90,6 +111,10 @@ export function transferId(t: NftTransfer): string {
// Exclude malleable ECDSA signature bytes from transaction identity.
return sha256(nftTransferMessage(t));
}
export function transactionId(transaction: TestnetTransaction): string {
if (isNftTrade(transaction)) return sha256(nftTradeMessage(transaction));
return transferId(transaction);
}
export function merkleRoot(leaves: string[]): string {
if (!leaves.length) return sha256(`${NETWORK}:empty`);
let layer = leaves.map(leaf => sha256(Buffer.concat([Buffer.from([0]), Buffer.from(leaf,'hex')])));
@@ -102,9 +127,32 @@ export function merkleRoot(leaves: string[]): string {
// Commit the count as well: odd-leaf padding must not make [a,b,c] equal [a,b,c,c].
return sha256(JSON.stringify([NETWORK,'merkle',leaves.length,layer[0]]));
}
export function stateRoot(state: NftState): string {
return merkleRoot(Object.keys(state).sort().map(id => {
const n = state[id]; return sha256(JSON.stringify([id, n.owner, n.sequence, n.mintedHeight, n.pageId]));
export function materializeState(state: NftStateView): NftState {
const layers: NftState[] = [];
let cursor: NftStateView = state;
while (isStateLayer(cursor)) {
layers.push(cursor.changes);
cursor = cursor.parent;
}
const result: NftState = Object.assign(Object.create(null) as NftState, cursor as NftState);
for (let i = layers.length - 1; i >= 0; i--) Object.assign(result, layers[i]);
return result;
}
function stateEntry(state: NftStateView, id: string): NftState[string] | undefined {
let cursor: NftStateView = state;
while (isStateLayer(cursor)) {
if (Object.hasOwn(cursor.changes, id)) return cursor.changes[id];
cursor = cursor.parent;
}
return (cursor as NftState)[id];
}
function isStateLayer(state: NftStateView): state is NftStateLayer {
return (state as NftStateLayer).kind === 'layer';
}
export function stateRoot(state: NftStateView): string {
const materialized = materializeState(state);
return merkleRoot(Object.keys(materialized).sort().map(id => {
const n = materialized[id]; return sha256(JSON.stringify([id, n.owner, n.sequence, n.mintedHeight, n.pageId]));
}));
}
export function mintId(h: Pick<BlockHeader, 'previousHash' | 'height' | 'owner' | 'article' | 'statsSnapshot'>): string {
@@ -143,47 +191,94 @@ export function applyTransfer(state: NftState, tx: NftTransfer, height: number):
if (!verifySignature(tx.publicKey, tx.from, nftTransferMessage(tx), tx.signature)) throw new Error('Invalid transfer signature');
state[tx.cardHash] = { ...nft, owner: tx.to, sequence: tx.sequence + 1 };
}
export function transition(parent: NftState, header: BlockHeader, txs: NftTransfer[]): NftState {
const next = structuredClone(parent);
export function applyTransferOverlay(state: NftStateView, tx: NftTransfer, height: number): NftStateLayer {
if (!transferSchema.safeParse(tx).success) throw new Error('Invalid transfer encoding/network');
const nft = stateEntry(state, tx.cardHash);
if (!nft || nft.owner !== tx.from || tx.from === tx.to || nft.sequence !== tx.sequence) {
throw new Error('Invalid NFT owner/sequence');
}
if (height - nft.mintedHeight < CONSENSUS.coinbaseMaturity) throw new Error('NFT coinbase is immature');
if (!verifySignature(tx.publicKey, tx.from, nftTransferMessage(tx), tx.signature)) throw new Error('Invalid transfer signature');
const changes: NftState = Object.create(null) as NftState;
changes[tx.cardHash] = { ...nft, owner: tx.to, sequence: tx.sequence + 1 };
return { kind: 'layer', parent: state, changes };
}
export function applyTradeOverlay(state: NftStateView, trade: NftTrade, height: number): NftStateLayer {
const parsed = tradeSchema.parse(trade);
const allLegs = [...parsed.offered, ...parsed.requested];
const current = allLegs.map(leg => stateEntry(state, leg.cardHash));
if (current.some((entry, index) => !entry || entry.sequence !== allLegs[index].sequence ||
height - entry.mintedHeight < CONSENSUS.coinbaseMaturity)) {
throw new Error('Trade contains missing, stale, or immature NFTs');
}
if (current.slice(0, parsed.offered.length).some(entry => entry!.owner !== parsed.proposer) ||
current.slice(parsed.offered.length).some(entry => entry!.owner !== parsed.counterparty)) {
throw new Error('Trade NFT owners do not match the signed parties');
}
const changes: NftState = Object.create(null) as NftState;
parsed.offered.forEach((leg, index) => {
const nft = current[index]!;
changes[leg.cardHash] = { ...nft, owner: parsed.counterparty, sequence: nft.sequence + 1 };
});
parsed.requested.forEach((leg, index) => {
const nft = current[parsed.offered.length + index]!;
changes[leg.cardHash] = { ...nft, owner: parsed.proposer, sequence: nft.sequence + 1 };
});
return { kind: 'layer', parent: state, changes };
}
export function applyTransactionOverlay(state: NftStateView, transaction: TestnetTransaction, height: number): NftStateLayer {
return isNftTrade(transaction)
? applyTradeOverlay(state, transaction, height)
: applyTransferOverlay(state, transaction, height);
}
export function transition(parent: NftStateView, header: BlockHeader, txs: TestnetTransaction[]): NftStateLayer {
let next = parent;
const ids = new Set<string>();
for (const tx of txs) {
const id = transferId(tx);
for (const transaction of txs) {
const id = transactionId(transaction);
if (ids.has(id)) throw new Error('Duplicate transfer');
ids.add(id); applyTransfer(next, tx, header.height);
ids.add(id);
next = applyTransactionOverlay(next, transaction, header.height);
}
const id = mintId(header);
if (next[id]) throw new Error('Duplicate NFT issuance');
next[id] = { owner: header.owner, sequence: 0, mintedHeight: header.height, pageId: header.article.pageId };
return next;
if (stateEntry(next, id)) throw new Error('Duplicate NFT issuance');
const changes: NftState = Object.create(null) as NftState;
changes[id] = { owner: header.owner, sequence: 0, mintedHeight: header.height, pageId: header.article.pageId };
return { kind: 'layer', parent: next, changes };
}
export function makeTemplate(ancestors: TestnetBlock[], state: NftState, owner: string,
publicKey: string, transactions: NftTransfer[], article: Article, statsSnapshot: MintStatsSnapshot,
export function makeTemplate(ancestors: TestnetBlock[], state: NftStateView, owner: string,
publicKey: string, transactions: TestnetTransaction[], article: Article, statsSnapshot: MintStatsSnapshot,
now = Math.floor(Date.now()/1000)): MiningTemplate {
if (!hex.safeParse(owner).success || address(publicKey) !== owner) throw new Error('Invalid miner identity');
const parsedArticle = articleSchema.parse(article);
const parsedStats = statsSnapshotSchema.parse(statsSnapshot);
const previousHash = ancestors.at(-1)?.hash ?? GENESIS_HASH;
const header: BlockHeader = { version: 4, network: NETWORK, chainId: CHAIN_ID,
const header: BlockHeader = { version: 6, network: NETWORK, chainId: CHAIN_ID,
height: ancestors.length + 1, previousHash, createdAt: Math.max(now, medianTime(ancestors) + 1),
article: parsedArticle, statsSnapshot: parsedStats, owner, publicKey, nonce: 0, target: expectedTarget(ancestors),
key: expectedKey(ancestors, ancestors.length + 1), transactionsRoot: merkleRoot(transactions.map(transferId)), stateRoot: '' };
key: expectedKey(ancestors, ancestors.length + 1), transactionsRoot: merkleRoot(transactions.map(transactionId)), stateRoot: '' };
header.stateRoot = stateRoot(transition(state, header, transactions));
return { header, transactions, blob: miningBlob(header).toString('hex'), nonceOffset: 32 };
}
export async function validateBlock(raw: unknown, ancestors: TestnetBlock[], parentState: NftState,
pow: PowEngine, now = Math.floor(Date.now()/1000)): Promise<{block:TestnetBlock;state:NftState}> {
export async function validateBlock(raw: unknown, ancestors: TestnetBlock[], parentState: NftStateView,
pow: PowEngine, now = Math.floor(Date.now()/1000), allowHistoricalFutureTimestamp = false): Promise<{block:TestnetBlock;state:NftStateView}> {
if (Buffer.byteLength(JSON.stringify(raw)) > CONSENSUS.maxBlockBytes) throw new Error('Block size limit exceeded');
const b = blockSchema.parse(raw);
if (b.height !== ancestors.length + 1 || b.previousHash !== (ancestors.at(-1)?.hash ?? GENESIS_HASH)) throw new Error('Invalid parent/height');
if (b.createdAt <= medianTime(ancestors) || b.createdAt > now + CONSENSUS.maxFutureSeconds) throw new Error('Invalid block timestamp');
if (b.createdAt <= medianTime(ancestors) || (!allowHistoricalFutureTimestamp && b.createdAt > now + CONSENSUS.maxFutureSeconds)) {
throw new Error('Invalid block timestamp');
}
if (b.target !== expectedTarget(ancestors) || b.key !== expectedKey(ancestors, b.height)) throw new Error('Invalid difficulty or RandomX epoch key');
if (b.transactionsRoot !== merkleRoot(b.transactions.map(transferId))) throw new Error('Invalid transaction root');
const next = transition(parentState, b, b.transactions);
if (b.stateRoot !== stateRoot(next) || b.tokenId !== mintId(b)) throw new Error('Invalid NFT state commitment');
if (b.transactionsRoot !== merkleRoot(b.transactions.map(transactionId))) throw new Error('Invalid transaction root');
if (b.tokenId !== mintId(b)) throw new Error('Invalid NFT state commitment');
const blob = miningBlob(b);
if (b.hash !== sha256(blob)) throw new Error('Invalid block ID');
if (!verifySignature(b.publicKey, b.owner, blockClaimMessage(b.hash), b.signature)) throw new Error('Invalid miner signature');
if (BigInt(`0x${b.powHash}`) > BigInt(`0x${b.target}`)) throw new Error('Insufficient work');
if (await pow.hash(b.key, blob) !== b.powHash) throw new Error('Invalid RandomX proof');
// Verify native work before materializing/sorting the complete NFT state. A malformed
// low-work block must not force O(total NFTs) commitment work on the request path.
const next = transition(parentState, b, b.transactions);
if (b.stateRoot !== stateRoot(next)) throw new Error('Invalid NFT state commitment');
return { block: b, state: next };
}