The hooks
Hooks are small programs attached to an account. When a transaction touches the account, the network runs them; they can refuse the transaction, keep state, and emit transactions of their own. Xahmoeba is five of them on one account.
Who does what
The same beats every birth goes through, from the keeper’s payment to the child coming home.
One request, nine stages
After admission nobody signs anything. The next wake-up captures the randomness, combines the genomes and mutates them, all on that one fire. Each later step takes a fire of its own, and the two parents are charged on two fires. The button walks the stages one at a time, including the three that share a fire, so each can be read. Watch what the issuer account holds change. Try burning a parent midway to see how a birth breaks.
Five positions, one account
A hook position may declare at most 65,535 instructions and 65,535 bytes of code, and the genetics does not fit beside the stage machine. So the work is split across positions, and one Cron fire wakes all of them at once. A fire is not free: it costs the sum of what the Cron-triggered positions declare, so every fire is paid for before it is booked. Founders need no position of their own: a founder request goes through admission like a birth, and the finalizer draws its genome from the captured ledger hash instead of from two parents.
| Position | Runs on | Does |
|---|---|---|
breed-admit | Payment | Checks a request against every rule, reserves both parents, takes one of the four queue places (the issuer runs at most four births at once), prices the birth from the ledger’s current fees, and guards the account: an operator can withdraw only what the queue does not owe. A founder request (no parents) takes the same door. |
breed-finalize | Cron; a keeper’s Payment; a poke by Invoke | Walks one birth forward on each fire. The fire that captures the randomness also recombines and mutates; mint, seal, each parent’s fertility, delivery, the partner’s price and releasing the queue place take a fire each. Books the next fire, paid from the budget of the birth it will serve. For a founder, draws the genome from the captured ledger hash. On a signed payment from a keeper it also writes their records: publishes or withdraws breeding terms, and gives a name once. On an Invoke from anyone it sweeps a broken birth or restarts a stopped clock. It declares only the types it has work for — a hook is charged to every transaction of a type it declares, run or not, so a moeba changing hands costs its holder the lock’s budget alone. A sweep of a birth whose child was minted and is still here sends that child on, once every partner who was owed a price has been paid. |
breed-recombine | Cron | Reads both parents’ genomes from their records and forms the two gametes. |
breed-mutate | Cron | Applies pathways and drift, continuing the same random stream, and fixes the child’s genome. |
breed-lock | Remit, sell offer, buy, burn | Refuses moving a moeba that a live birth still needs. A burn is never refused; it breaks the birth instead. |
What a payment can ask for
Every request to the issuer except the poke is an ordinary XAH Payment to its account. What makes it a request is a handful of hook parameters on the transaction: one letter each, read by the hooks and by nothing else. F says what is asked; the others name the moeba, the parents, a price. The site fills them in; anyone signing by hand can read them off this table.
F | Asks for | Other parameters | Who may send it |
|---|---|---|---|
01 | A founder | none | anyone |
02 | A birth | P, Q: the two parents’ token ids | the keeper of one parent; the other must be theirs too, or open to others |
03 | Sweeping a stuck birth, or restarting a stopped clock. This is the older form: the site sends the same request as an Invoke addressed to the issuer, with no amount and no parameters, which costs less | none | anyone |
04 | Closing a moeba to others | P: the token id | its keeper |
05 | Opening a moeba to others | P: the token id; A: price per birth in drops; X: expiry ledger, optional | its keeper |
06 | Giving a name | P: the token id; N: the name, UTF-8, at most 24 bytes | its keeper, once |
Parameter names are the letters in hex (F is 46); numbers are four big-endian bytes. The payment carries the fee the request needs and, for a birth, the partner’s price and the birth’s budget; the hooks quote the minimum from the ledger and refuse anything under it.
What is refused, in words
- A parent the issuer did not issue, or a token of the issuer that is not a moeba at all.
- A moeba breeding with itself, with its own parent in either direction, or with a full sibling. The two parents must be the same genetic model.
- A parent that is not mature against the ledger clock, or has no fertility left.
- A parent already reserved by another live birth.
- A parent the requester neither keeps nor has a permission for; a permission belonging to a previous keeper, expired, or malformed.
- A request in which the requester keeps neither parent. Terms open a moeba to other keepers, not to someone with no moeba at all.
- A request that supplies its own randomness, target ledger or serial.
- A request that underpays, partially pays, or is not in XAH — for a birth, a founder, terms or a name alike.
- A requester whose account refuses incoming Remits, or requires a destination tag or deposit authorisation: the child, or a refund, could not be delivered.
- A partner whose account requires a destination tag or deposit authorisation, when a price is owed.
- A parent of a genetic model this issuer does not run.
- A withdrawal by the operator that would touch money the queue owes.
- Moving a moeba a live birth still needs, except a burn, which breaks the birth instead.
- Terms published, changed or withdrawn, or a name given, by anyone but the moeba’s current keeper; a second name for a moeba that has one.
When a hook refuses, it says why in a short sentence that is recorded with the transaction. This site shows that sentence when one of your requests is refused.
The money
A request pays the protocol fee, both partners’ prices, and a budget for the work the birth will make: the emissions, and sixteen Cron fires at the price the ledger quotes at admission. The fee, the founder curve and the price of a name are parameters the issuer can move without a new build. The figures in force are on Getting started. The whole budget is committed at admission and released at settlement; what is unspent stays with the issuer. The fee is earned on the fire that fixes the randomness, and comes back with the rest if the birth is swept before that. Reserves are not charged: a reserve is a deposit, not a cost.
Three places, different jobs
Your device reads the records and draws the moebas. It can cache and explore, but it decides nothing.
Your wallet, whichever one holds your key, shows you a transaction and signs it. The key never leaves it.
Xahau validates transactions and runs the hooks. The Xahmoeba issuer is rMmx5nHzoVJAoMTFWkgCCMrZryTaD682tr on Xahau testnet; its hooks and their hashes are visible there.