orgchain/README.md

# Orgchain

Lineage's app for creating and operating lineage holdings: https://lineage.yolopreneur.lol/orgchain/

Lineage gives an org its structure, a key tree with a place for every org and agent. Orgchain adds time. Every act is an
inscription on a private toy chain in your browser, and its parent inscription is the node that authorizes it, so the
chain itself records who did what, and when.

- **Found** a holding (a root: the LLC). **Birth** orgs and agents under any org. **Award** a belt (one skill, one
  seat, in any holding: a registry like well-known certifies agents it doesn't hold). **Decide** (a decision on a
  node's record). **Make** an item (an inscription its maker holds, and can sell). **Graduate** an org: its edge flips
  from derived to adopted, and it becomes a holding of its own, with its own tree, timeline and share of the mining,
  while its parent's tree keeps a row for it. **Close** a node (derived children close with it; graduated ones hold
  their own roots and stay open).
- **Time.** A beat is a block. At the default tempo each act is its own beat; at 10, 30 or 60 seconds, acts are cued and
  land together on the next beat; on manual they wait for *Beat now*. The slider and *Replay* show a holding as it
  stood at any beat.
- **Money.** Test BTC lives at each node's SegWit address. **Mining** is a lab setting: under *Split* (the default)
  every active holding mines, and each beat's 50 test BTC splits pro rata by hashrate, a dial from 0 to 9 on each
  holding (1 unless set), one coinbase output per holding; under *Last act* the holding behind the latest act or send
  takes the whole beat (with nothing cued, *Beat now* pays the one being worked in), so at a timed tempo acts race
  for the next beat; under *Mainnet* no holding mines, as on mainnet: beats pay the lab wallet, standing in for the
  world's miners, and **Fund** moves test BTC from it to a holding, the way you'd fund a seed from a wallet you
  already have. **Send** moves test BTC from any active node to any other, in
  its holding or another, signed by the sender's BIP-84 key: at most eight coins in, at most 50 test BTC out, and the
  toy chain's fixed 500-sat fee. Sends land like acts, at once or cued, and *Beat now* mines a beat even when nothing
  is cued. A graduation moves each re-keyed node's money to its new address along with its inscription. Balances
  follow the slider, the timeline lists every reward, send and gas top-up, and Inspect has the exact amounts and the
  raw transaction (`src/orgchain/money.js`).
- **Gas.** Every act is paid by the acting node's own keys: its inscription's two fees and postage (2,000 sats),
  plus 500 for each handoff it makes. They come out of its gas tank, the plain coins at its Taproot key, which tops
  up from its own money 0.0001 test BTC at a time. A node with neither can't act until someone sends it money, and a
  graduating org pays for the claim on its new root itself. The lab wallet pays only for foundings (a holding owns
  nothing until it mines) and for holdings that predate lab keys.
- **Deals.** Any active node can **Offer** on an item another node holds, in any holding: OpenOrdex's buy order, with
  a price. Its SegWit key signs the whole deal at once (SIGHASH_ALL): the item and its own coins in; the item to its
  Taproot key, the price to the holder's SegWit address and its change out. Nothing reaches the chain until the
  holder **Accepts** by countersigning the item's input, so the offer stands, kept in the lab like a PSBT in an
  order book, until it is accepted, withdrawn, or goes stale (a coin it promised moved, or a side closed or re-keyed).
  The buyer pays the fee; a price of 0 is a free claim. Payments spend coins no offer has promised first. Accepted
  offers stay as the deals' receipts, and the timeline and Inspect show each deal (`src/orgchain/offers.js`).
- **One interpretation.** `src/orgchain/lineage.js` folds `lineage/v0` events into trees, and vets every act before
  anything is signed. Events it rejects stay on the chain and show as rejected; they just don't change the tree.
- **Keys.** Each holding gets its own 24-word lab root, and every node has lineage's keys at its place in the tree
  (`src/orgchain/keys.js`): an org's seed is BIP-85 from its parent's, or its own root once it graduates; an org is
  account 0 of its seed and its agents are accounts 1..n. Every account lists its addresses, so no one has to derive
  them: **Taproot** (BIP-86, `m/86'/1'/account'/0/0`), which holds the node's inscription, signs its acts and receives
  inscriptions; **SegWit** (BIP-84, `m/84'/1'/account'/0/0`) for payments; its **Tapkey**, the npub as a Taproot
  address (its nostr key with the BIP-86 tweak), which the npub alone finds; and its **npub** (NIP-06). Its **leaves**
  hang off the same tree, byte for byte as on lineage's key tree page (`src/orgchain/leaves.js`): an agent's ssh, git,
  dkim and wg keys from its nostr secret, an org's ssh-ca, mtls and noise keys from its seed, each with the public line
  to paste. Every act is signed by the Taproot key that holds the authorizing inscription, and a birth hands the child
  its own. Graduation is a claim by the org's fresh root, countersigned by its derived key, and the derived subtree
  re-keys under the new root, so the parent's line can no longer sign for it. Labs keyed by v1.1 or v1.2 keep their
  chain keys until they are reset.
- **Secrets.** Each node's Inspect has a Reveal panel, as on lineage's key tree page: its seed (holdings and orgs),
  its nsec, its Taproot, SegWit and Tapkey keys as descriptors Bitcoin Core imports as they are (test-network WIF,
  BIP-380 checksums), and its leaves' private keys (OpenSSH, DKIM, WireGuard, PKCS#8, Headscale). Hidden again on
  every selection; lab keys only.

Test coins and test keys only: a local chain, the lab wallet (the faucet that pays for foundings, and under *Mainnet*
the wallet holdings are funded from) and each holding's lab root, kept in this browser (`localStorage`, key
`orgchain:lab:v1`). Nothing here is a real key; minting a real root is
the operator's call.

## Events

`lineage/v0` is the ord metaprotocol (tag 7); the fields are CBOR metadata (tag 5); the body is a short text label.

| op | parent inscription (spent to authorize) | metadata |
| --- | --- | --- |
| `found` | none | `name` |
| `birth` | the parent | `name`, `kind` (`org` or `agent`) |
| `award` | the issuing org or holding (`to` may sit in any holding) | `to`, `skill`, `belt` (`white`, `green`, `black`) |
| `decide` | the deciding node | `title`, `why` |
| `make` | the making node, which then holds the item | `name`, `note` |
| `graduate` | the child's parent (then the handoff to the child's fresh root); the child becomes a holding | `of` |
| `close` | the node itself | none |

Names are domain labels (lowercase letters, digits, hyphens). Org and agent indices count separately and are never
reused. The metadata says what an event means; the parent it spends proves who was allowed to make it; who holds an
item afterwards is the chain's to say, never the metadata's. Metadata is public and permanent: an item's note is for a
hash or a link, never a secret or a document.

## Build and test

```
npm ci
npm test            # engine, reducer, lab and money (node --test)
npm run build       # dist/ is the site; relative paths, so it works at any sub-path
npm run test:e2e    # Playwright on vite preview; PW_CHANNEL=chrome uses installed Chrome
```

`ORGCHAIN_URL` (plus `PW_ARGS`, a JSON array of browser flags) points the same end-to-end spec at a deployed copy.

Deploy: copy `dist/` to `ventures/lineage/orgchain/` on `teahubxyz/time` `gh-pages`. Its headers (a strict CSP with
`connect-src 'none'`: the app makes no network requests) come from `ventures/lineage/_headers`.

## Built on Super Testnet

The chain, wallet, inscriptions, metadata and index (`src/adapters`, `src/upstream`, with `src/storage.js` and
`src/miner.js`) are [Super Testnet](https://supertestnet.lol)'s, with their tests (`tests/adapters.test.js`) and three
additions: the chain also moves native SegWit (P2WPKH) payments, BIP-143 signatures included; a coinbase may split
its reward across up to 64 outputs; and ordinary spends take up to eight inputs and outputs, whose key-path
signatures may carry SIGHASH_SINGLE|ANYONECANPAY (0x83, the sell-order flag), while reveals keep their two-in,
two-out shape (`tests/money.test.js`).
See `PROVENANCE.md` and `public/licenses/`. Lineage's key derivation and the claim and
countersign handoff (`src/adapters/lineage-keys.js`, `src/adapters/handoff.js`, with their spec vectors in
`tests/keys.test.js`) come from the `tree` branch. The full lab (explorer, delegates, recursion and
the Inscriboor extension) lives at supertestnet.lol.