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), soulbound to its seat. **Decide** (a
  decision on a node's record). **Make** an item (an inscription its maker holds, and can sell). **Buy** an item, an org
  or a whole holding, and **Sell** your own (both sides of a deal, below). **Keyring** (a node publishes its keys on
  each chain, each key signing the same statement). **Charter** (a node's legal form, from sole proprietor to series
  LLC). **Graduate** an org or an agent: 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 64 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; an
  award rides its seat's sat, so it needs no postage and costs 1,000), 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.** Both sides of OpenOrdex's partially signed transaction, on a lot: an item, which its holder sells; an org
  inside a holding, which its parent sells with its tree; or a whole holding, which its owner sells (the lab wallet
  plays the owner). **Buy** makes an offer, the buy order: the buyer's SegWit key signs the whole deal at once
  (SIGHASH_ALL), every coin the lot sits in and its own coins in, the lot to its Taproot key as one coin, the price to
  the seller and its change out, and nothing reaches the chain until the holder **Accepts** by countersigning the lot's
  inputs. **Sell** makes an ask, the sell order: the lot's key signs its input alone with SIGHASH_SINGLE|ANYONECANPAY
  (0x83), which commits to that input and to the price to the seller at the same index and to nothing else, so any node
  can **Take** it. The buyer leads with a 600-sat coin of its own, so the lot lands in its first output (sats move first
  in, first out), then the lot and its funds; out go the lot to the buyer and the price to the seller. Offers and asks
  stand in the lab like PSBTs in an order book until they land, are withdrawn, or go stale (a coin they spend moved, or
  a side closed or re-keyed). The buyer pays the fees, and an offer of 0 is a free claim. Payments spend coins no offer
  has promised first, and the timeline and Inspect show each deal (`src/orgchain/offers.js`).
- **Acquisitions.** An org changes hands with its tree (the derived orgs and agents below it, and the items they hold),
  and a holding changes hands whole. Either sells cash-free: before it is listed, or an offer on it is accepted, the
  money in its tree, every gas tank included, goes to its seller (for a holding, the lab wallet), so the price is for
  the tree and its items. An ask signs one input, so listing a tree first bundles every inscription in it into one coin
  at its key, and while it's listed the whole tree is frozen: nothing in it acts or moves money, nothing above it
  graduates or closes it, nothing in it sells alone, and a listed holding doesn't mine. An offer spends every coin the
  tree sits in and merges them into one. The buyer then adopts it: a `join`, signed by the key that now holds its
  inscription, and an `adopt`, signed by the buyer, move it into the buyer's tree at the buyer's next index (a holding
  becomes an org there), where its keys and its tree's derive from the buyer's seed. Then the coin it came in splits
  back, each node's inscription to its new key, its belts on the same sat, and each item to the node that held it, by
  the layout the deal kept. Taking an ask adopts at once; after an accepted offer the buyer adopts when it's ready. The
  seller's tree keeps a row at the old index, marked with where the org went, and a holding bought whole brings its
  history into its buyer's timeline. The sample ends with both sides standing: lineage's offer for the launch kit, and
  well-known's ask for mailr; selling time with its ventures, or yolopreneur whole, is one Sell away.
- **Belts.** A belt is soulbound: it counts only when it is inscribed on its seat's own sat, a rule of `lineage/v0`
  that any indexer can check, so it moves with the seat through every act, graduation and sale, and never sells on its
  own. A promotion is another reinscription on the same sat, over the belt before it, so the sat carries the seat's
  whole ladder in each skill, ⬜ white, 🟩 green, ⬛ black (the sample's sol goes white, then green). One reveal carries
  a belt, three coins in: the seat's, which the pointer puts the belt in and the seat's key signs, accepting it; the
  issuer's, the parent that authorizes it; and the commit, which pays the fee. Both coins come back unchanged. `ord`
  gives each belt two charms: ♻️ reinscription, since its sat already carries the seat's inscription, and ❤️‍🔥
  vindicated, since a pointer and an envelope past the first input would have cursed it before the jubilee. Inspect
  lists a node's belts with their ladders and charms (`src/orgchain/belts.js`). Belts inscribed anywhere else, as they
  were before v1.14, don't count.
- **Keyrings.** **Keyring** publishes a node's keys in one inscription whose parent is the node itself: its Taproot and
  SegWit addresses, its npub and its Ethereum address, so another chain or a registry like well-known can find them
  without deriving anything. Every key signs the same statement, the way its own wallets sign a message: BIP-322 for the
  Bitcoin addresses, a nostr note for the npub, EIP-191 for Ethereum, so any wallet can make a proof and any library can
  check one. The newest keyring counts, no key is bound to two nodes at once, and a graduation retires the keyrings it
  re-keys, so the graduate publishes its new keys (the sample shows lineage's). Inspect shows each node's keyring and
  the statement its keys signed (`src/orgchain/keyring.js`).
- **Charters.** **Charter** records a node's legal form, which is an attribute, not an identity: a freelancer's holding
  starts with no form, takes one when it needs to (sole proprietor, LLC, series LLC or corporation), and keeps its
  inscription, keys and history throughout. A series LLC holds its ventures as series, each chartered by the master; a
  series lapses if it graduates or its master closes or stops holding series, which the tree shows by striking its tag.
  A graduated venture charters itself as an LLC. An agent can graduate too: a seat goes independent as a holding of its
  own, free to birth and award, then incorporate. A charter carries a jurisdiction, a legal name, who formed it and a
  SHA-256 of the filings, which Charter can compute from a file without the file leaving the tab. The sample shows
  yolopreneur as a Wyoming series LLC with its ventures as series, and lineage graduating into Lineage LLC.
- **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; its **npub** (NIP-06); and its **Ethereum** address
  (BIP-44, `m/44'/60'/account'/0/0`; an org's, at account 0, is its legal-control key, as on the key tree page). 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), its Ethereum private key, 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 (a
keyring's is the statement its keys signed).

| 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; the belt counts only on `to`'s own sat, so `to` co-signs) | `to`, `skill`, `belt` (`white`, `green`, `black`) |
| `decide` | the deciding node | `title`, `why` |
| `make` | the making node, which then holds the item | `name`, `note` |
| `keyring` | the node itself; the newest counts, and a graduation retires it | `taproot`, `segwit`, `nostr`, `ethereum`, and `proof` (each key's signature) |
| `charter` | the node itself, or a series' master; the newest counts | `form`; `jurisdiction`, `legal`, `provider`, `filing`, or `of` for a series |
| `graduate` | the child's parent (then the handoff to the child's fresh root); the child, org or agent, becomes a holding | `of` |
| `close` | the node itself | none |
| `join` | the org or holding, signed by whoever holds its inscription (its buyer); with the `adopt`, in either order, it moves with its tree | `to` |
| `adopt` | the new parent, which takes it in at its next index; its keys and its tree's derive from there | `of` |

Names are domain labels (lowercase letters, digits, hyphens). Org and agent indices count separately and are never
reused (an org or a holding that changes hands takes its buyer's next one). 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.

## Lineage as a metaprotocol

`SPEC.md` defines `lineage/v0` as an ordinals metaprotocol: what each field of the envelope means, the order events
fold in, why a parent proves authority, and every rule the reducer applies. The lab is one implementation. The other is
`bin/lineage-index.mjs`, which reads the events from a real `ord` server and folds them with the same reducer:

```
node bin/lineage-index.mjs --ord http://127.0.0.1:8088 [--from <height>] [--compare <lab backup>]
```

`tools/regtest/` rehearses the sample, keyrings, belts, asks, offers and whole trees changing hands included, on Bitcoin
Core regtest: the lab's own transactions, byte for byte, confirmed by Bitcoin Core and indexed by `ord`, which then tell
the same story as the lab (`tests/indexer.test.js` replays a recorded run). The first rehearsal found that the lab's
reveals committed to the wrong tapleaf, which real Bitcoin rejects; reveals are now checked the way Bitcoin checks them
(`SPEC.md`, section 1). The rehearsal of org sales found that a miner can put a join and its adoption in either order
within a block, so a move records both halves and each half belongs to both holdings (`SPEC.md`, section 5). The
rehearsal of whole trees sold an org with its six below it on an offer and a holding whole on an ask, bundling eleven
nodes into one coin and splitting them again, and `ord` put every inscription on the same sat as the lab (`SPEC.md`,
section 7). Three of those nodes wore belts, each inscribed on its seat's own sat by a three-input reveal, sol's twice
(white, then green over it): `ord` charmed every belt ♻️ and ❤️‍🔥, and after both sales each was still on its seat's
sat.

## Build and test

```
npm ci
npm test            # engine, reducer, lab, money and the ord indexer (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 six
additions: the chain also moves native SegWit (P2WPKH) payments, BIP-143 signatures included; a coinbase may split
its reward across up to 64 outputs; ordinary spends take up to 64 inputs and outputs, whose key-path signatures may
carry SIGHASH_SINGLE|ANYONECANPAY, the sell-order flag 0x83 (`tests/money.test.js`); a reveal, otherwise two in and
two out, may inscribe on a sat another key holds, spending that sat's coin, its parent's and the commit and returning
both coins unchanged (`tests/belts.test.js`); a chain may start from coins imported from a real chain; and reveals'
script paths are checked per BIP-341 and BIP-342 (`tests/indexer.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.