# SUPERB consensus and LITERATE settlement

This is development program source, not a mainnet deployment. The same Anchor
program now defines SUPERB rule/evaluator registries, contrast commitments,
consensus proposals, availability attestations, typed challenges,
finalization and semantic release lineage alongside LITERATE settlement. It
stores no raw passages, individual judgment payloads or complete definitions.
The existing `publish_epoch` instruction remains in the IDL for compatibility
but rejects every call. The operator settlement client uses
`publish_consensus_epoch`, which requires a finalized consensus-backed release.

The on-chain count evaluator uses checked integer arithmetic and basis-point
confidence. A protocol-finalized account is distinct from an RPC response at
Solana `finalized` commitment. Independent replay also requires a signed
submission log and available artifact manifest; an on-chain root alone is not
proof of completeness or data availability.
Receipt signing uses a dedicated Ed25519 keypair. The program records it
separately from the transaction administrator and rejects proposals that reuse
the administrator key. The web service must never hold the administrator key.

The development program ID is
`HujKf44u3eNDVcevgHvepLT1YFGXz1DRQqMr6VCseZP2`. It is not a token mint address.
Program keypairs, local wallets, compiled outputs and ledgers stay in ignored
`solana/target/`. Never commit them or use the local test wallet for real funds.

## Build in WSL

From `app/solana` in Ubuntu, with Solana CLI, Rust and Anchor installed:

```sh
anchor build
```

After a fresh build, `target/idl/superb_settlement.json` is required by
`solana/consensus-local.mjs`. Prepare a fully signed contrast with
`node scripts/export-consensus.mjs CONTRAST_ID CONFIG.json OUTPUT.json` while
`SUPERB_DB` points to the private database. Register the rule and evaluator,
create the contrast, then propose using that output. The operator client also
supports attestation, typed challenge, challenge resolution and finalization
for both consensus and release accounts. Publishing a release requires its
complete artifact and replays every member against finalized chain accounts
before transaction submission. It defaults to local RPC; a remote RPC
requires `--allow-network`. The core transaction path has passed a fresh-validator
end-to-end test. See [the protocol contract](../docs/protocol.md) for the exact
roots, state model and remaining mainnet gates.

The checked-in workspace pins Anchor crates to 1.2.0. Anchor CLI 1.1.2 can build
this workspace. On a fresh checkout, generate a local program keypair with
`solana-keygen new --no-bip39-passphrase --outfile target/deploy/superb_settlement-keypair.json`,
run `anchor keys sync`, and update the development ID in `client.mjs` to match.

Start the validator in a separate terminal, from `app/solana`:

```sh
solana-keygen new --no-bip39-passphrase --outfile target/deploy/local-admin.json
solana-test-validator --ledger target/local-ledger --bind-address 127.0.0.1
```

Fund and deploy using only local funds:

```sh
solana airdrop 100 --url localhost --keypair target/deploy/local-admin.json
solana program deploy --url localhost --keypair target/deploy/local-admin.json --program-id target/deploy/superb_settlement-keypair.json target/deploy/superb_settlement.so
```

From `app/` in the Windows terminal (Node dependencies live there):

```sh
node solana/tests/settlement.mjs
node solana/tests/consensus.mjs
```

Use a fresh local ledger for a repeated integration run: configuration and epochs
are intentionally immutable. The test mints one billion tokens with nine decimals,
funds the work treasury with 80% and protocol treasury with 20%, then revokes mint
authority. It verifies funded publication, Rust/JavaScript proof agreement,
tamper rejection, duplicate claims, pausing and two-step administrator transfer.
The separate atomic bootstrap also supports immutable Metaplex fungible-token metadata before revoking mint authority. It creates no public token listing.
The consensus test needs its own fresh ledger. It verifies proposal, count
rejection, attestation, challenge handling, both finalization windows, release
lineage, reward binding and finalized RPC account decoding.

## Compile allocations

```sh
node solana/compile.mjs evaluated-ledger.json epoch.json
```

Input amounts and points are decimal strings, never floating-point token values.
Example input shape:

```json
{
  "epoch": "1",
  "releaseHash": "abababababababababababababababababababababababababababababababab",
  "budgetBaseUnits": "1000000000",
  "contributors": [{
    "wallet": "11111111111111111111111111111111",
    "eligiblePoints": "3",
    "contributionIds": ["reviewed-judgment-1"]
  }]
}
```

The example address/hash demonstrate encoding only. Real input requires evaluated
records, a claimant-controlled wallet and a finalized on-chain semantic release ID.
An optional decimal-string `pointCap` applies before proportional allocation.
Integer remainder stays unreserved. Duplicate wallets and contribution IDs are
rejected. Reordering input does not alter output. No points means no epoch.

Leaves use SHA-256 over `SUPERB_REWARD_LEAF_V1`, little-endian u64 epoch, 32 wallet
bytes, little-endian u64 amount and 32 contribution-digest bytes. Parents hash
`SUPERB_REWARD_NODE_V1` and the lexicographically sorted child hashes. An unpaired
node advances unchanged. Contribution digests use the supplied spec's sorted,
length-prefixed `SUPERB_CONTRIB_V1` encoding.

## Authority and funding

Only the deployed program's upgrade authority may initialize configuration.
The administrator publishes sequential epochs and can pause publication/claims.
Publication reserves the whole allocation against the canonical treasury balance.
Claimants sign; a separate fee payer may sponsor account creation. Receipts cannot
be reset or closed. Administration changes only after the nominated key accepts.

The program verifies settlement, not eligibility or linguistic truth. The admin
and upgrade authority remain trust assumptions. Independent program review,
production key custody, published metadata assets, measured contribution eligibility, economic
validation and a public deployment manifest remain launch requirements. There is
no automatic path from a preview answer to an on-chain allocation.

References: [Anchor program structure](https://www.anchor-lang.com/docs/basics/program-structure),
[Original SPL Token](https://www.solana-program.com/docs/token).

## Atomic token initialization

`node solana/bootstrap.mjs admin.json PROTOCOL_WALLET RPC_URL deployment.json`
creates the mint, initializes the protocol, funds both treasuries and revokes mint
authority in one transaction. Set `LITERATE_METADATA_URI` to the final HTTPS JSON;
it creates immutable `LITERATE` name and symbol metadata before revocation. Remote
execution requires the explicit `--allow-network` flag. `--plan` only constructs
and sizes the transaction. `--recover` verifies an already initialized, unused
protocol and restores its public deployment manifest after an interrupted response.

Local metadata checks require the Metaplex program on the validator. Load its
public binary using the validator's `--bpf-program` option. The ordinary settlement
integration test deliberately runs without metadata dependencies.

Prepare evaluated allocations with `node scripts/corpus.mjs epoch input.json`.
Set `SUPERB_DB` before `node solana/settle.mjs publish admin.json epoch.json RPC_URL`.
Publication validates the database release and reconciles an already-published
matching epoch after a lost response. Claim with the claimant's wallet using
`node solana/settle.mjs claim claimant.json epoch.json RPC_URL`.

Metadata API: [Metaplex fungible tokens](https://www.metaplex.com/docs/tokens/create-a-token).

For a new claimant without SOL, set `SOLANA_FEE_PAYER` to an authorized sponsor
keypair file. The claimant signs the same immutable proof; the sponsor pays fees
and account rent. No server HTTP endpoint exposes the sponsor key.