commonware-reshare 2026.9.0

Reshare a threshold secret over an epoched log.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78

# commonware-reshare

[![Crates.io](https://img.shields.io/crates/v/commonware-reshare.svg)](https://crates.io/crates/commonware-reshare)

Reshare a threshold secret over an epoched log.

## CLI

The example has one binary with three subcommands:

```sh
cargo run --bin commonware-reshare -- setup --node-dir ./data --peers 6 --committee-size 4 --base-port 3000
cargo run --bin commonware-reshare -- setup --bootstrap dkg --node-dir ./data --peers 6 --committee-size 4 --base-port 3000
cargo run --bin commonware-reshare -- dkg --node-dir ./data/validator-0
cargo run --bin commonware-reshare -- validator --node-dir ./data/validator-0
```

`setup` creates every `validator-*` directory and writes node and network
config. By default, it also performs a trusted threshold setup, writes the
genesis `EpochInfo`, and seeds each active epoch-0 player with its private
share.

Use `setup --bootstrap dkg` for deployments that want the initial secret
generated by protocol. In this mode, `setup` writes only node and network config
and prints DKG commands only for the epoch-0 committee.

`dkg` runs the one-shot glue DKG bootstrap for deployments that want the initial
secret generated by protocol instead of trusted setup. Only the epoch-0 players
run it because only they receive shares. After DKG completes, the generated
`genesis.json` is written into every generated validator directory so all
validators can start from the same genesis.

`validator` starts the application chain, stateful QMDB, continuous reshare, DKG
orchestrator, DKG anchor, and stateful probe.

## Node Layout

Each validator owns one directory under the configured data directory:

```text
data/
  validator-0/
    node.json
    network.json
    genesis.json
    secrets.json
    runtime/
```

`node.json` contains the node's Ed25519 signing key and listen/dial addresses.
`network.json` contains the ordered participant list, fixed committee size, and
peer dial addresses. `genesis.json` is written by `setup` or `dkg` and then
consumed by `validator`. `secrets.json` is the file-backed DKG secret store.
`runtime/` is the Commonware storage root for all blob partitions used by that
node.

Committees rotate deterministically: for epoch `E`, the committee starts at
offset `E % participants.len()` and takes `committee_size` consecutive
participants with wraparound.

The application state is intentionally tiny: one `any::unordered::fixed` QMDB,
one fixed key, and each non-genesis block writes its height to that key. Genesis
carries the epoch-0 `EpochInfo`.

## State Sync

`validator --state-sync` is only for a new late joiner whose key is already in a
future committee. It asks peers for a finalized anchor, uses `stateful::probe` to
select a floor, and state-syncs QMDB from that floor before normal processing.

Do not use `--state-sync` as a normal restart flag. A restart recovers from
local storage. A player that misses its private dealings cannot recover them by
syncing: the ceremony completes without it and publicly reveals its share.

## Limits

Generated data from older versions of this example is not migrated. Recreate the
`data/validator-*` directories when switching to this glue-based example.