# Lineage reward settlement

## Status

The settlement pipeline is staged but disabled. Reward assets are selected from the verifier-accepted GPU vendor:

```text
NVIDIA or unknown -> NVDAx -> Xsc9qvGR1efVDFGLrVsmkzv3qi45LTBjeUKSPmx9qEh
AMD               -> AMDx  -> XsXcJ6GZ9kVnjqGsjBnktRcuwMBmvKWh8S93RefZ1rF
Intel             -> INTCx -> XshPgPdXFRWB8tP1j82rebb2Q9rPgGX37RuqzohmArM
Apple             -> AAPLx -> XsbEhLAtcf6HdfpFZ5xEMdqW8nfAvcsP5bdudRLJzJp

All four use 8 decimals and Token-2022.
```

No signing key, treasury authority, or RPC credential belongs in this repository. The backend accepts `LINEAGE_KEY` (or `lineage_key`) only from the server environment and derives its public key at runtime. That public key is used as both the pre-launch treasury authority and epoch signer. The secret is never returned by an API.

## Settlement boundary

Only runs accepted by the independent verifier can create a reward liability. Browser-local units, free trials, stopped sessions, failed sessions, and unsigned submissions are never settlement inputs.

The coordinator assigns each verified run to one six-hour epoch and records:

- Wallet and one-use lease identifier.
- Verified VCU and policy version.
- Mining-pass tier active when the lease was issued.
- USD-denominated nominal liability.
- Verifier-accepted vendor, mapped payout mint, price observation, and raw integer token units.
- Verification and run digests.

## Epoch close

1. Freeze the epoch input set.
2. Reject duplicate leases and runs without accepted proof.
3. Apply the policy and treasury governor.
4. Map each run to NVDAx, AMDx, INTCx, or AAPLx; unknown vendors map to NVDAx.
5. Convert covered rewards into raw units using a recorded Jupiter Price API v3 observation for that mint. Persist its USD price, Solana block ID, source timestamp, and observation timestamp.
6. Aggregate one leaf per wallet and payout mint.
7. Sort leaves deterministically and build the Merkle root.
8. Confirm every asset vault holds at least its full raw-unit liability.
9. Persist the immutable manifest and digest.
10. Submit the root, raw-unit totals by asset, and manifest digest to the Solana claim program.
11. Mark vouchers claimable only after the root transaction is finalized.

## Claim

The wallet submits its epoch, mint, raw-unit amount, and Merkle proof. The program verifies the proof, checks the epoch state, transfers from the matching xStock vault, and creates a claim receipt in one transaction. A second claim for the same wallet, mint, and epoch must fail.

## Job funding

The buyer flow accepts inference and render jobs only after the server verifies a finalized Solana payment. Verification checks that the connected buyer signed the transaction, the configured treasury authority received at least the required lamports, and the signature has not funded another job. A paid job becomes queued work, not an automatic completion. Compatible miners still need signed leases, output verification, and delivery storage.

Paid job intake must remain disabled until fulfillment capacity is operational. The current minimums are staged at 0.001 SOL for inference and 0.002 SOL for render; they are policy values rather than promises of service.

The private record follows `data/job-schema.json`. It retains the buyer wallet, finalized signature, paid lamports, private workload input, and assignment state. The public API strips the wallet, signature, and input. A dispatcher may move a job from `queued` to `leased` only by binding it to an unused production run lease; output moves through `running` and `verifying` before it can become `complete`.

## Required production configuration

```text
LINEAGE_KEY
LINEAGE_CLAIM_PROGRAM_ID
JUPITER_API_KEY (recommended for production)
SOLANA_RPC_URL or HELIUS_RPC_URL
LINEAGE_JOB_INTAKE_ENABLED=true
LINEAGE_DISPATCHER_ENABLED=true
LINEAGE_VERIFIER_ENABLED=true
LINEAGE_SETTLEMENT_ENABLED=true
```

The four public payout mints are fixed in application code and are not overridden by environment variables. A standard Solana RPC can prove token balances and transactions but cannot supply USD prices. The server therefore resolves the mints with Jupiter Price API v3. The unauthenticated lite endpoint is suitable for preview; production settlement should use `JUPITER_API_KEY`, persist every observation, and halt an epoch if any response is stale or unavailable.

The derived wallet public key is the treasury authority, not a token vault itself. Each vault is the authority's Token-2022 token account for one configured mint. The Treasury API reads all four owner/mint balances at finalized commitment through the configured Solana RPC and values them with the matching Jupiter observations. The launch switch must remain false until all required token accounts are funded and the claim program is audited.

Job intake has separate switches for intake, dispatch, and verification. All three must be enabled before the buyer API accepts SOL. This prevents a payment from entering a queue that has no production worker or verification capacity.

## OTC funding role

$LINEAGE is planned for launch through OTC. OTC documents that the holder allocation is 70% of creator fees and buys the launch's chosen tokenized stock or rotating basket. The team plans to keep 10% of $LINEAGE supply in the disclosed treasury wallet so its proportional holder credits can add inventory for runner settlement. Assets outside the chosen reward still require buyer revenue or disclosed treasury acquisition. This is supplemental treasury funding; it does not replace paid jobs, vault coverage checks, or verifier acceptance.

## Signing policy

- Keep `LINEAGE_KEY` only in encrypted server environment storage, never in Vercel source, browser code, logs, or API responses.
- Use a multisig as program upgrade and treasury authority.
- The pre-launch build permits one key for treasury authority and epoch signing as requested. Split those roles before meaningful treasury value is deposited.
- Require an emergency pause and signer rotation procedure.
- Treat webhook and RPC results as observations; verify settlement transactions against finalized Solana state.

## Public artifacts

Every closed epoch publishes the manifest matching `data/settlement-schema.json`, its digest, Merkle root, policy version, vault coverage, and Solana signature. This allows an independent implementation to reproduce the committed root.