Skip to content
Bindings · Writing an accelerator6 pages

Writing an accelerator

Partly built

How a native entry point comes to stand in for a Clay definition: bindings, stand-in claims and the evidence they carry.

An accelerator is a binding whose native code stands in for one exact Clay definition. The Clay definition stays the meaning; the native code is an optimisation of it, chosen by the definition’s hash and invisible to the program.

Native code enters a Clay program in exactly two ways. A handler answers an ability (effects: sockets, clock, GPU) and is visible in the program’s type. An accelerator replaces a definition that has no effects (speed: parsing JSON, the size of a map), and needs no ability, because a function that makes no effect must not make its callers declare one.

The pieces

Entry points. The binding’s manifest lists the symbols it exports, each with its arity: {"name": "json.from_text", "arity": 1}.

A stand-in claim. A separate signed file that names one entry point and one exact Clay definition (its hash and the member index inside it), repeats the definition’s type, says which library it comes from, and carries the evidence:

  • the test that checks the native code against the Clay code,
  • optionally a corpus and a fuzz seed,
  • what the native code declines, in words.

A claim is signed over "clay-substitution-claim-v1\n" plus its id, and its id is the SHA-256 of its canonical bytes without the signatures. Because claims are separate files, adding one never changes the binding’s id.

Declining

The native function may decline: it gets an argument it does not handle exactly as the Clay code would, so the Clay body runs instead. Declining is always safe.

Many to one

Several claims may name the same entry point with different hashes: two definitions that differ trivially, or two library versions with the same behaviour. Each claim stands on its own evidence, because behavioural equivalence is undecidable in general. clay-kernel has a test-only variant of data.Map.size (its two cases in the other order) to show the rule.

Stale claims are harmless

If the definition changes, its hash changes and no claim matches, so the Clay code runs. Correctness is never lost, only speed. That is the property the whole design rests on.

Commands

npm run registry -- claim add claims/my-claim.json
npm run registry -- claim sign
npm run registry -- claims verify
npm run registry -- revoke --claim <id>

claim seed re-creates every claim and signs it. A claim is tied to the exact bytes it covers, so after a rebuild of the kernel its claims are re-signed.

The registry’s Accelerated definitions page lists every claim across bindings. Search it with a definition’s name or hash to find out whether your program will get native speed.