The protocol

Where a moeba is

A moeba is a URIToken on Xahau issued by one account, the species: rMmx5nHzoVJAoMTFWkgCCMrZryTaD682tr on Xahau testnet. A URIToken from any other issuer is not a moeba, whatever its URI says; that check comes before any other. Three places hold everything:

• The URI — the identity: model, kind, generation, birth ledger, fertility, rules version, maturity deadline, serial, commitment. Fifty-two bytes, immutable by construction, because a URIToken's id is derived from its issuer and its URI together.
• The Remarks — six named records, three immutable (birth, audit, rules) and three the issuer rewrites at a keeper's signed request (use, terms, name). Only the issuer can write a Remark on its own token, so each record is a statement by the species.
• Hook state on the species account — the birth queue and the counters. Live, not part of any creature; read it through account_namespace or the API.

One genetic model has ever been minted on chain: v0.1-32-deep, model byte 1. The URI reserves a byte for the model so a wider genome can be added later without touching a creature that exists; a reader that meets a model byte it does not know should say so rather than guess. Everything below describes v0.1-32-deep.

Numbers are big-endian throughout. Hex is upper-case where the ledger shows it; base64url is the RFC 4648 §5 alphabet, no padding, and a decoder must reject a string that does not re-encode to itself.

The identity URI

urn:creature:birth:2: followed by 52 bytes as base64url: 91 characters in all. A URIToken's URI is stored as hex on the ledger; decode the hex to ASCII first.

The token id is Xahau's URIToken keylet — a SHA-512-half over the ledger-space prefix, the issuer's AccountID and the URI bytes — so the id is fixed the moment the URI is, and the species can retry a failed mint without producing a second token.

The records

Six Remarks by name. Each value begins with a version byte; a reader that meets a version it does not know reports it as unknown rather than parsing on assumption. Values are at most 256 bytes. The three immutable records and the URI are covered by the token's Digest.

The Digest. SHA-512-half( "KIN/digest/1\0" ‖ len(uri) ‖ uri ‖ len(birth) ‖ birth ‖ len(audit) ‖ audit ‖ len(rules) ‖ rules ), each length a u32, the URI as ASCII. It is fixed before the mint, so it cannot name the mint transaction; what it commits to is the identity and the three immutable records in one fixed order.

The genome

Thirty-two bytes: two haplotypes of 16 bytes, the first from parent P, the second from parent Q. Within a haplotype the 36 loci are packed at the bit offsets below, MSB-first — bit 0 of the haplotype is the top bit of its first byte — using 128 of 128 bits. A locus's value on haplotype h is the bits-wide unsigned integer at h × 128 + offset.14 loci are discrete and choose an allele from a table; the rest are quantitative and add up into 22 traits.

A reserved allele index is invalid: a genome that carries one is malformed, and no birth produces one. Mutation-only alleles have founder weight 0 and appear only through the mutation pathways at birth.

Expression

What the two copies come to, per locus. This is all a reader needs to name a moeba and list its traits; the body that is drawn from the traits is presentation and may change, the traits do not.

• Discrete. Read the allele index on each haplotype. If they are equal, that allele shows. If not, the one with the higher dominance rank in the table shows; the other is carried and can be inherited.
• Quantitative. For each trait, over the loci that feed it: sum = Σ (a + b + ⌊|a − b| · k / 256⌋), max = Σ 2 · (2^bits − 1), and the trait is ⌊sum · 255 / max⌋, an integer 0–255. k is the trait's dominance deviation from the spec, 0 for every trait in v0.1-32-deep, so it is purely additive.
• The name. The taxon is a Latin binomial fixed by four discrete loci — BODY_PLAN, APPENDAGE_FAMILY, SYMMETRY and PATTERN_FAMILY — with a fixed table of genus and epithet stems; the variant is the words for PIGMENT_CLASS and MOVEMENT_FAMILY; the fingerprint is a 32-bit FNV-1a over the 32 genome bytes, folded to 20 bits ((h ^ h >>> 20) & 0xFFFFF) and written as four Crockford base32 characters, so two moebas of one taxon still differ. The API returns all of it, so a reader need not carry the stem tables.

Asking the species

Every request except the poke is an XAH Payment to the species account with hook parameters: one-letter names (as hex: F is 46, P is 50) and values as below. The species' Hooks read them and nothing else; memos and destination tags mean nothing to it. No partial payments, no SendMax, no paths: the amount must be the amount delivered.

The amounts are quoted from the ledger at the moment of the request and refused below the quote; an overpayment is kept as budget. The protocol fee for a birth, the founder curve, the issuer's share of partner prices and the name fee are Hook parameters on the species account and are read for you at /v1/issuer (birthFeeDrops, founderCurve, partnerCutBps, nameFeeDrops, tickDrops). The share comes out of the partner's payout: the requester pays the published price, and the slot records what the partner will receive. The budget a birth carries is 20 × tickDrops for the clock plus 124 emitted transactions at the network's emission price; what a birth does not spend stays with the species. The founder price is FFEE × (FMUL/100)^⌊n/FTRN⌋ with n the founders admitted so far, all from founderCurve. The site's own arithmetic for this is in its request pages; a wallet can copy it or over-quote slightly.

A request is accepted when the Payment succeeds and the species' Hooks return accept; a refusal is a tecHOOK_REJECTED with the reason in the Hook execution's return string, in plain words. After admission nothing more is signed: the species' own clock fixes the randomness, breeds, mints and delivers by Remit. A receiving account with lsfDisallowIncomingRemit set is refused at admission, since the child could never land.

LIFE

A moeba brought to life has its life on a second account, the LIFE account rGXvnPHRDktpq8BQYkKVz8AiByy3Q4BTDy on Xahau testnet. Its hooks keep one entry per living moeba and change it only by the transactions below. Everything this site shows about a living moeba is read from those entries; how it moves is worked out on each device from them.

Five positions

Two unnamed positions, the gate and the guard, and three named ones (NamedHooks): a transaction names the position it is for with HookName. The hashes are what this site recognises; any other installation reads as no LIFE.

The transactions

Bring to Life is a Payment of exactly the price (the hook parameter LP), named awaken, with the parameter T, the token id. Every other action is an Invoke named life (or visit), with A, one byte, and T; Start Visit adds H, the host’s token id; Play may add S, a spot the hook ignores; Rest may add U, when it ends (ledger time, u32).

The state, and how to read it yourself

The entries are in the LIFE account’s HookState under the namespace 0F40B4738BB475C506966169F8060ACE20CDBCD48B2A97E7E8E67FD025F212F0 (sha256 of kin:life). A moeba’s LifeState is keyed by its token id: ask a node { "method": "ledger_entry", "params": [{ "hook_state": { "account": "rGXvnPHRDktpq8BQYkKVz8AiByy3Q4BTDy", "key": "<token id>", "namespace_id": "0F40B473…" } }] }. While it hosts, its roster is keyed 52 followed by the first 31 bytes of its token id (for example 52ABABABABAB…), and the count of living moebas is under 4C4946453A434F554E54…. Every entry at once: account_namespace. Times are ledger time, seconds since 2000-01-01.

The LifeState is 256 bytes, big-endian, fixed width: its length never changes, its first byte says which layout it is in, and what the fields do not use is kept empty at the end. What it holds is the state as of its last write: needs drift, rests end and long sleeps come by time alone, so a reader brings it to now with the rules in the hooks’ parameters (@kin/life’s effective() does exactly what the hooks do).

The roster is 217 bytes: version 1, then six slots of a visitor’s token id and when its visit ends. The count is 5 bytes: version 1, then the number living, u32.

Fees

Each action is one transaction with its network fee, which depends on the hooks it runs. Bring to Life also pays the price, once. Touching, calling and pointing are free: nothing is signed.

Refusals

A refused action rolls back with its reason’s code (HookReturnCode) and its words; the network fee is spent and nothing else changes. Every reason, by code, in the reference’s own words:

The API

Everything above is what the ledger says; the API says the same in words and pictures, from an index that re-reads the ledger every few seconds. It is read-only, allows any origin, and every JSON answer carries headLedger so you know what ledger you are looking at. This deployment's is at https://api.xahmoeba.com.

Each client has a budget — a few hundred requests a minute, a fresh picture costing several and a fresh plate or model a few dozen — and gets 429 with Retry-After over it. Pictures and the population are cacheable; please cache them. A marketplace that shows moebas needs only metadata.json and the picture, and can verify either against the ledger with this page.

Try it on a real one

Choose a moeba, or paste a token id. Its URI is decoded byte by byte on this device by the rules above, the genome is unpacked locus by locus, and each API link opens what the index says about it.

If this page and the ledger disagree, the ledger is right and this page has a fault. Tell us.