# puppeth — XDPoS genesis assembler

Interactive CLI that produces a JSON genesis for an XDPoS chain (V1 + V2
config, signer list embedded in extraData, alloc with precompiles and funded
operator accounts).

Port of `cmd/puppeth` from `XinFinOrg/XDPoSChain`, reduced to the
genesis-creation subset. Issue #595 has the full rationale.

## Build

```
make puppeth
# binary at ./build/bin/puppeth
```

## Usage

```
./build/bin/puppeth --network mynet
```

The wizard walks you through:

1. **Consensus engine** — choose `3` for XDPoS (default), or `1`/`2` for
   ethash/clique if you really want them.
2. **Block period / epoch / gap / reward / foundation wallet** — defaults
   match XDC mainnet (2s / 900 / 450 / 5000 / `0x...0068`).
3. **V2 BFT switch block** — must be a multiple of `epoch`. Pick a high
   value (e.g. `999999900`) to keep the chain V1-only for testing. Mainnet
   uses `80370000`; Apothem uses `56828700`.
4. **V2 timeout / cert threshold** — defaults `10s` / `3` / `0.667`.
5. **Signer addresses** — one per line, blank to end. Stored sorted in
   extraData.
6. **Pre-funded accounts** — one per line, blank to end. Each gets a
   2²⁴⁹-wei balance.
7. **Chain ID** — pick anything (avoid 50 / 51, which are mainnet /
   Apothem).

The wizard saves an internal config to `~/.puppeth/<network>`. Re-running
loads that config and offers `Manage existing genesis` → `Export` to
write the final JSON.

## What this does NOT generate

The four XDC system contracts at `0x...0088` (XDCValidator),
`0x...0089` (BlockSigner), `0x...0090` (Randomize), and `0x...0099`
(Foundation MultiSig) are **not** pre-deployed. V1 consensus runs fine
without them — sealing reads signers from extraData/the snapshot, not from
the validator contract.

If you need a genesis with the system contracts populated (e.g. to test
validator-contract `eth_call` paths or V2 candidate-set queries), build the
**patched legacy XDPoSChain puppeth** standalone — `docs/MINING_WIREUP.md`
documents the reproduction recipe. Porting that contract-deployment path
into this fork requires either reverse-engineering the Solidity storage
layouts or extending `ethclient/simulated.Backend` with state iteration;
see issue #595 for the follow-up scope.

## Init a chain from the generated genesis

```
geth --datadir nodes/node1 init mynet.json
```

For V1 sealing on the new chain, also see `docs/MINING_WIREUP.md` for the
`XDC_MINER_PASSWORD` env var and `--miner.pending.feeRecipient` flag wiring.