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). **Decide** (a decision on a node's record). **Graduate** an org (its edge flips from derived to adopted).
  **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.
- **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 funds every key) 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`, `skill`, `belt` (`white`, `green`, `black`) |
| `decide` | the deciding node | `title`, `why` |
| `graduate` | the child's parent (then the handoff to the child's fresh root) | `of` |
| `close` | the node itself | none |

Names are domain labels (lowercase letters, digits, hyphens). Org and agent indices count separately and are never
reused.

## Build and test

```
npm ci
npm test            # engine, reducer and lab (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, unchanged and with their tests
(`tests/adapters.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.