orgchain/SPEC.md

# lineage/v0

lineage/v0 is an ordinals metaprotocol for lineage holdings: LLCs, the orgs and agents they birth, the belts and
decisions on their record, the items they make, and the orgs and holdings that change hands between them. Every event
is an inscription. The chain orders the events and proves who was allowed to make each one; the state (the trees) is
stored nowhere, and every indexer that applies these rules to the same inscriptions gets the same trees.

Status: test networks only (Orgchain's in-browser chain and Bitcoin Core regtest). The reference implementation is
`reduce()` in `src/orgchain/lineage.js`; `src/indexer/ord.js` and `bin/lineage-index.mjs` run it over a real ord index.

## 1. Inscriptions

lineage/v0 uses these fields of the ord envelope ([inscriptions](https://docs.ordinals.com/inscriptions.html)):

| tag | field | use |
| --- | --- | --- |
| 7 | metaprotocol | exactly `lineage/v0`; inscriptions without it are not lineage's |
| 5 | metadata | a CBOR map: `op` and its fields (section 4), strings except a keyring's `proof` map, in 520-byte pushes (Orgchain keeps it under 2048 bytes) |
| 3 | parent | the inscription id of the node that authorizes the event; exactly one, except for `found` |
| 1 | content type | `text/plain;charset=utf-8`; the body is a short label such as `birth time` (a keyring's is its statement), ignored by the rules |
| 2 | pointer | puts a child's inscription in its own output when the parent is spent first, and a belt on its recipient's sat (section 7) |

The body, delegate (tag 11) and properties (tag 17) carry no meaning here; properties may later carry display traits
such as a belt's colour, never authority. Nor do ord's charms, such as a belt's (section 7). Unknown odd tags are
ignored. Never use unknown even tags: ord treats such an inscription as unbound, so it has no location.

A reveal is a script-path spend whose tapleaf commits to the envelope script's exact bytes (BIP-341). Orgchain's reveals
before v1.9 committed to a re-encoded script; real Bitcoin rejects those, and Orgchain's local chain still loads them.

## 2. Order

Events fold in chain order: block height, then transaction order in the block, then envelope order in the transaction.
ord's inscription numbers follow the same order. Unconfirmed events are provisional, and ord indexes none.

Within a block, the miner sets the order. Events that share an authority are chained, because each one spends that
authority's inscription, so their order is fixed. Independent events may land in any order, and outside the conflicts
in section 6 that changes nothing.

## 3. Nodes and authority

A node is created by an accepted `found` (a holding) or `birth` (an org or an agent), and its id is that event's
inscription id. Each node has a kind (holding, org or agent), a status (active or closed), and, below a holding, an
edge: derived (the parent holds the child's seed) or adopted (it graduated and holds its own root). A child's index
counts its parent's earlier children of the same kind, orgs and agents separately, and is never reused: an org that
changes hands (section 5) takes the next index under its new parent, and its old parent keeps the old one, unused.

An event's parent is the node that authorizes it, and it counts only if the inscribing transaction spends that node's
inscription: ord records a parent only then ([provenance](https://docs.ordinals.com/inscriptions/provenance.html)).
Indexers use ord's recorded parents, never the raw tag. So acting for a node means holding its inscription, and moving
the inscription moves the authority.

## 4. Events

| op | parent | metadata | effect |
| --- | --- | --- | --- |
| `found` | none | `name` | a holding; no active holding may already have that name |
| `birth` | an active holding, org or graduated agent | `name`, `kind` (`org` or `agent`, default `org`) | a child; the parent may not already have an active child of that name |
| `award` | an active holding, org or graduated agent | `to`, `skill`, `belt` (`white`, `green` or `black`) | `to` (any other active node, in any holding) holds that belt in that skill, replacing its earlier belt in it; the award counts only if it is inscribed on `to`'s own sat, so the belt is soulbound (section 7) |
| `decide` | an active node | `title` (required), `why` (optional) | a decision on the node's record |
| `make` | an active node | `name`, `note` (optional) | an item, made and first held by the node; a node makes one item per name |
| `keyring` | the node itself, active | `taproot`, `segwit`, `nostr`, `ethereum`, and `proof`: each key's signature | the node's keys are bound to it, replacing its earlier keyring (section 8) |
| `charter` | the node itself, active; for a series, its master | `form`; `jurisdiction`, `legal`, `provider` and `filing`, or `of` for a series | the node's legal form, replacing its earlier charter (section 5) |
| `graduate` | the child's parent, active | `of` (an active child, org or agent, not yet adopted) | the edge becomes adopted, and the child becomes a holding of its own (section 5) |
| `close` | the node itself, active | none | the node closes, with every active derived descendant; adopted ones stay open |
| `join` | the moving org or holding itself, active | `to` (the new parent) | half of a move: it asks to join `to`, and moves there with its tree once `to` adopts it (section 5) |
| `adopt` | the new parent, active | `of` (the org or holding) | the other half: `to` takes it in, and it moves once it has joined (section 5) |

Names (holdings, children, skills, items) are 1 to 40 lowercase letters, digits or hyphens, starting and ending with a
letter or digit, because they become domains. Text fields are trimmed, and only their first characters count: 140 for a
title, 400 for a why, 280 for a note, 120 for a legal name. Agents birth and award only once they graduate. An event
that breaks a rule is rejected: it stays on the chain and changes nothing. Any other `op` is rejected.

## 5. Holdings, graduation, moves and charters

A holding is a root: a `found`, or a child that graduated. When an org graduates, it and its descendants still in the
old holding re-root under it, and it joins the holdings. An agent can graduate too: it goes independent, and as a holding
of its own it can birth and award. A graduate's parent stays its parent, so where it came from stays on the record, and
its old holding's tree keeps a row for it. A graduation event belongs to both holdings. Its keys change with its new
root, and so do its derived descendants', so their keyrings retire (section 8).

In Orgchain a graduation is followed by a handoff: the graduate's fresh root claims its inscription, and the derived key
that held it countersigns. After that, only the new root can act for it.

An org or a holding can change hands: move to a new parent, in its own holding or in another, with its tree. Both sides
must authorize it, and an event has one parent (section 1), so a move takes two events: a `join`, whose parent is the
moving node (so whoever holds its inscription, its buyer after a sale), names the new parent in `to`, and an `adopt`,
whose parent is the new parent, names the moving node in `of`. Either may come first, and the second completes the move.
A newer `join` replaces the node's pending one; an `adopt` waits for its own join. An org moves with its derived tree,
and a holding, or a graduate (which holds its own root), moves whole; an agent moves only with the org it sits in. The
new parent is an active holding, org or graduated agent, not the moving node nor anything below it by parent links (so
no ancestor of a graduate can join it), with no active child of the moving node's name.

When the move completes, the node takes the next index of its kind under its new parent, and it and its derived
descendants still in its old holding re-root into the new one. A holding that moves becomes an org of its new parent and
leaves the holdings. Its keys now derive from its new parent at its new index, and so do its derived descendants', so
their keyrings retire (section 8); graduated descendants hold their own roots and stay where they are, their parent
links pointing into the tree that moved. Its charter goes with it: a series that leaves its master's holding lapses, and
so does a sole proprietorship, since an org is not a person. The move records both halves, and each half belongs to
both holdings, so the miner may put them in either order within a block. A graduation of a node with a pending join is
rejected.

A `charter` records a node's legal form: what it is off chain. Legal form is an attribute, not an identity, so a node
keeps its inscription, history and keys whatever form it takes, and the newest charter counts.

| `form` | what it is | who may take it | chartered by |
| --- | --- | --- | --- |
| `sole` | a person trading under their own name | a holding or an agent | the node |
| `llc` | a company of its own (for a derived org, one its parent's line controls) | a holding, an org or a graduated agent | the node |
| `series-llc` | an LLC that can hold series | a holding, an org or a graduated agent | the node |
| `series` | a cell of an ancestor's series LLC | an org | that ancestor, its master |
| `corp` | a corporation | a holding, an org or a graduated agent | the node |

`jurisdiction` is an ISO 3166 code such as `US-WY`, required for an LLC, a series LLC or a corporation and optional for
a sole proprietor; a series takes its master's. `legal` is the legal name, `provider` the name of whoever formed it (by
the name rule), and `filing` the SHA-256 of the filed documents, in hex: metadata is public, so a charter carries a hash,
never the documents. A series charter names the series in `of`; its master must be an ancestor whose charter is a series
LLC at the time.

Whether a charter stands is read off the tree as it is, not stored: a charter stands while its node is active, and a
series also needs its master active, still a series LLC, and in the same holding as the series. A series that graduates,
or whose master closes or stops holding series, lapses. Because standing is derived, a charter and a graduation in the
same block land the same way in either order. Control follows the inscription, whatever the form.

## 6. Order-sensitive conflicts

Where independent events conflict within one block, the block's order decides. These are the cases: a close and an act
by one of its derived descendants; an award and a close above its recipient that closes it too (the recipient's own
close is chained with the award, since both spend its inscription); two foundings with the same name; a keyring and a
graduation or close that retires it; two keyrings that list the same key; a join or adoption and a graduation, close or
birth that changes the moving node or its new parent. Orgchain keeps a keyring and the graduation that would retire it
a block apart, and it freezes a tree that is listed or sold (section 7), so nothing in it acts, and nothing above it
graduates or closes it, before its buyer adopts it.

## 7. Ownership, items and deals

Whoever controls the output that holds an inscription's sat holds that node or item; for indexers that is ord's
satpoint. Items and nodes move like any inscription, and one output may hold several. A deal is not an event: ord sees
the lot move, and nothing else needs indexing. Orgchain makes deals both ways OpenOrdex does, on a lot that is an item,
an org with its tree, or a holding, whole:

- An offer is a buy order: one transaction with every output the lot sits in and the buyer's coins in, and the lot to
  the buyer as one output, the price to the seller and the buyer's change out. The buyer signs its inputs first
  (SIGHASH_ALL), and the lot's holders countersign theirs.
- An ask is a sell order: the holder signs the lot's input alone with SIGHASH_SINGLE|ANYONECANPAY (0x83), which commits
  to that input and to the output at its index, the price to the seller, and to nothing else. Any buyer completes it:
  a small coin of its own, the lot and its funds in; the lot to the buyer's key and the price to the seller out. The
  small coin leads so that the lot's sats land in the buyer's output, since sats move first in, first out. One input is
  one output, so a tree is bundled into one before it is listed.

A tree is a node and its active derived descendants, with the items they hold. An org's seller is its parent; a
holding's is its owner, whoever holds its root (in Orgchain, the lab wallet), and the price goes to the owner's key. A
sold node joins its buyer's tree by `join` and `adopt` (section 5); until then the trees still draw it with its seller.
In Orgchain a deal on a tree goes like this:

- Cash-free: before it lists a tree, or accepts an offer on one, the seller takes home the money in it, every node's
  SegWit coins and gas tank, so the price is for the tree and its items.
- Listing bundles it: one transaction spends every output that holds the inscription of one of its nodes or items, the
  lot's own first, and pays them into one output at the lot's key, with a coin of the seller's last for the fee, so no
  inscription's sat pays it. The ask signs that output, and withdrawing the ask splits it back.
- After the `join` and the `adopt`, the buyer splits the output it bought: one transaction with an output for each
  inscribed sat, running from it to the next one (the first from the output's start), to the new key of the node whose
  inscription is on it, or, for an item, to the new key of the node that held it, which the deal records as its layout.
  A sat's inscriptions never part, so a node's belts stay on its sat.
- While a tree is listed or sold it 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 mines nothing. The records of a tree's events (decisions,
  keyrings and the like) are not part of it: they carry no authority, and stay where they landed. Its nodes' belts ride
  their sats (below), so they come along.

A belt is soulbound. An award counts only if it is inscribed on `to`'s own sat, the one that carries `to`'s
inscription, so the belt goes wherever `to` goes and is never a lot. Two inscriptions are on one sat when ord gives them
the same sat number, or, without its sat index, the same satpoint, which they then share for good. Inscribing on that
sat means spending the output that holds it, so `to`'s holder signs, accepting the belt. Orgchain's reveal spends three
outputs: that one; the issuer's, the parent; and the commit, which pays the fee. It returns the first two unchanged, and
its pointer (tag 2) is the offset of `to`'s sat in the first. A newer belt in a skill is another reinscription on the
same sat, over the ones before, so the sat carries the whole ladder in order: white, then green, then black. ord charms
each belt ♻️ reinscription and ❤️‍🔥 vindicated: a pointer, or an envelope past the first input, would have cursed it
before the jubilee. Belts inscribed anywhere else, as Orgchain's were before v1.14, do not count.

## 8. Keys and keyrings

Indexers need no keys to fold the trees. Keys say where a node's inscription is expected to live, and who can sign for
it. Each holding has a 24-word root (BIP-39), and an org's seed is BIP-85 from its parent's (`m/83696968'/39'/0'/24'/i'`)
until it graduates, and from its new parent's at its new index once it moves (a holding that moves becomes an org, and
its old root no longer signs for it). An org is account 0 of its seed and its agents are accounts 1 to n. Each account
holds its inscription at its BIP-86 Taproot address (`m/86'/coin'/account'/0/0`), keeps its money at BIP-84 SegWit, and
has a NIP-06 npub (`m/44'/1237'/account'/0/0`) and an Ethereum address (`m/44'/60'/account'/0/0`). An org's Ethereum
key, at account 0, is its legal-control key: the one that holds its entity NFT.

A `keyring` publishes a node's keys, so other chains and registries can find them without deriving anything. Its parent
is the node itself. Its metadata lists four keys, each written the way its chain writes it, and a proof from each:

| field | key | proof, in `proof` under the same name |
| --- | --- | --- |
| `taproot` | the Taproot address that holds the node's inscription, lowercase | a BIP-322 simple signature, base64 |
| `segwit` | its P2WPKH address, lowercase, on the same network | a BIP-322 simple signature, base64 |
| `nostr` | its npub | the BIP-340 signature, in hex, of the NIP-01 event `{pubkey, created_at: 0, kind: 1, tags: [], content: statement}` |
| `ethereum` | its address, in EIP-55 case | an EIP-191 `personal_sign` signature: `0x`, then r, s and v in hex |

Every proof signs the same statement, one line each:

```
lineage/v0 keyring
node: <the node's inscription id>
taproot: <address>
segwit: <address>
nostr: <npub>
ethereum: <address>
```

The lines are joined by a line feed, with none after the last. Each key signs the way its own wallets sign a message, so
any wallet can make a proof and any library can check one. A Taproot proof is a 64-byte signature (SIGHASH_DEFAULT) or a
65-byte one ending in SIGHASH_ALL; a P2WPKH proof is a low-S DER signature with SIGHASH_ALL and the compressed key. The
inscription's body is the statement, for people to read; the rules rebuild it from the metadata.

A keyring is rejected unless every key is well formed and every proof checks out. While a node's keyring stands, its
keys are bound to that node, and a keyring that lists a key bound to another node is rejected; a key binds once,
whatever network it is written for. A node's newer keyring replaces its older one and frees the keys it no longer lists.
A graduation retires the keyrings of the graduate and its derived descendants, since their keys change with the new
root, a move retires those of the moving node and its derived descendants, since their keys change with its new parent,
and a close retires the keyrings of the nodes it closes. A retired keyring binds nothing, so the node publishes a new
one.

Lineage's key tree page also makes an agent's keyring as a nostr event (kind 30078, `d` = `lineage/keyring/v0`), signed
by its npub and listing its leaves too. The inscription is the chain's record, with a proof from every key.

## 9. Versions and other chains

Tag 7 carries the version. A new version is a new string with its own rules, which v0 indexers ignore. The events and
the rules are chain-agnostic. What another chain must supply is its own proof of order and of authority (a signature
by the node's key where nothing is spent). Each holding's events would live on one home chain, and its nodes' keyrings
(section 8) bind their keys on the others. Another chain's key joins the keyring in a new version, proven the way that
chain's own wallets sign a message.

## 10. Conformance

`tools/regtest` rehearses Orgchain's sample on Bitcoin Core regtest, byte for byte, keyrings, belts, asks, offers and
whole trees changing hands included (bundled outputs and their splits too), and `bin/lineage-index.mjs --compare`
checks that ord and the lab tell the same story: the same events in the same beats, the same metadata and parents, the
same trees and keyrings, and every inscription on the same sat (ord's satpoint), with the same ♻️ reinscription and
❤️‍🔥 vindicated charms. `tests/indexer.test.js` replays a recorded run.
`tests/keyring.test.js` checks the proofs against BIP-322's published vectors, the key tree page's Ethereum vector, and
values cross-checked with bip322-js, ethers and nostr-tools.