How KEA works

KEA is a signer you control. It reads a transaction, checks it against rules you published, and signs the ones that match. Its authority is the rule; its answer is a signature.

The one idea

Assembling a transaction and approving one are separate jobs, done by separate parties. Whoever builds it hands it on; whoever holds a key approves what matches a rule published in advance.

Five jobs, and the useful part is that five different parties can do them — the author of a rule, the one proposing against it, and the one holding a key are free to be three different people:

How the pieces connect

KEA talks outbound only: it opens a connection to the pool and to a public Hedera mirror node, and everything it needs arrives over those. That is what lets a signer live on a phone behind an ordinary home router.

The machine: what happens to one transaction

This is the part worth understanding properly. Think of a transaction as a ball dropped into the top of a machine. It falls through a series of gates, and each gate either passes it on or sets it aside with a named reason. A ball that clears every gate reaches the bottom and gets signed.

What each gate is actually doing

How signatures add up

KEA's job ends at the signature: it holds a key, it signs, it posts the signature back. Counting the approvals is the ledger's job.

A Hedera account states its own requirement — "any one of these three", "any two of these three", or "this one, or any two of those three". So a payout can be made to require two separate devices held by two separate people, each contributing a share of the approval. That is a change to the account's key; the signer carries on exactly as before.

Ways to run a signer

A signer is its own thing, running beside your application. It watches the pool and holds a key your application's accounts depend on. That separation is the point: your application can be rewritten and redeployed as often as you like while the key stays exactly where you put it.

All of these run the same decision. The checks in the machine above are one pure piece of code; each shape supplies the surroundings around it — how it hears about a transaction, where the key is kept, how it reads the chain. That is why a phone and a server reach identical verdicts, and why a new shape is a new set of surroundings rather than a new rulebook.

Running more than one

Each signer works alone: it hears about the same transaction, decides for itself, and posts its own signature. Two signers reaching the same conclusion is the point — that is the agreement the ledger counts. When they differ, the dashboard shows you both verdicts side by side.

Using KEA yourself

What you will need

1. Rules you have published. One document per thing you are willing to pay for, each identified by its own hash. A catalogue is just how others find them.
2. An account whose key you control, set to require whichever devices you want — one, or two of three, or whatever suits what is at stake.
3. A key on each device, generated on that device. The public half goes onto the account; the private half stays where it was made.
4. A config file per signer: which keys it holds (as references), which deals it will sign and with which of those keys, and where the deal documents are. Nothing else about your application.

The shape of it

{
  "network": "testnet",
  "pool":    { "base": "https://<the pool>" },
  "mirror":  "https://testnet.mirrornode.hedera.com/api/v1",

  "keysets": { "mine": ["env:MY_SIGNING_KEY"] },
  "resolve": ["vendor/<your app>/deals"],

  "deals": {
    "<dealId>": { "sign": ["mine"], "limits": { "<asset>": 1000000 } },
    "<dealId>": { "sign": ["mine"], "witness": true }
  },

  "report":   "refusals",
  "presence": { "everyMs": 30000 }
}

Three things in that file carry most of the safety:

• deals — a deal's id is the hash of its document, so listing it pins it: the signer refuses a document that does not hash to the id it was asked for. Updating your rules is therefore a deliberate act: review, then change one line. No accounts appear anywhere: which accounts a key answers for is read from the chain, per transaction.
• limits — the most this signer will approve per asset per hour, whatever the rules allow. This is the signer's own private budget; a rule can only see the chain, and your signature is not on it yet.
• keysets — references (env:NAME or a file path), so the config is a file you can commit, review and share freely. The first key is the device key: it signs the signer's announcements and verdicts.

Running one — the short way

bin/kea is the launcher (put bin/ on your PATH and it is just kea go). It defaults to the remote config — a phone is never the box — and to the name this device remembers:

bin/kea name honor      remember what this device is called — once, ever
bin/kea check           is this device ready to sign?  (the doctor: config, keys, chain, pool, doorbell, who else is on)
bin/kea                 watch only — decide and log, never sign      (dry run)
bin/kea go              sign what passes
bin/kea go quiet        sign, but announce nothing this run
bin/kea who             who else is announcing right now

Stopping one: Ctrl-C says goodbye — one last signed announcement, mode: "stopped", so the board shows stopped rather than a device that silently went stale — and exits. Ctrl-\ exits at once and says nothing: the quiet restart. The long form is node kea/node.js --config <file> [--go] [--quiet|--announce]; there is no default config.

Bringing one up

1. Check before you run. A doctor command answers the questions in the order they bite: is the config valid, is the key present, does the chain accept it, can this device reach the pool — and how much weight this key carries on its own, as against counting towards a group.
2. Watch first. Start in dry run: it decides on everything and reports each verdict — to its log, and, if you let it, back to the pool where the dashboard shows who refused what and at which step — so you can read those against real traffic first.
3. Expect most of the pool to be none of its business. A shared pool carries everyone's transactions. A signer stays silent about the ones that were never aimed at it (see below) — silence there is the filter working, not a fault.
4. Then let it sign. One flag.
5. Rehearse the threshold. Stop the signers that can act alone, and confirm the remaining ones behave as you expect. Do this while it is still a rehearsal.

Addressed, or none of my business

The nine checks fall into two halves, and only one of them is worth anyone's attention.

The addressing checks run before any chain read, so deciding that something was never yours costs nothing. A signer chooses how much of its judgement to publish with report: none, refusals (the default), all, or debug — the last one also publishes the transactions that were never its business, flagged as such, which is only useful while working out why a signer is or is not being offered something.

Reading an announcement

What /kpool/signers returns per device is the signed announcement, kept whole, plus four things the pool adds. Nothing derived is added beside it: the accounts are the values of keys, the deal ids are the keys of deals.

To verify one yourself (v2): build the JSON object { v, network, label, mode, at, startedAt, version, keys, deals, subscription } with the keys in exactly that order and the values as returned (startedAt, version, subscription as null when absent), take JSON.stringify of it as UTF-8 bytes, and check sig against by as a raw ed25519 signature over those bytes. That is the same primitive that signs a transaction body; the pool did exactly this before storing the record.

Words used here

Questions this raises

Everything above says what each part does. These are the questions that tend to follow, and the answers are the boundaries of it.