Bombil names, admission and activation contracts

This reference describes the inspected checkout's Bombil boundary. Bombil is the current name of One Book / OneBook; existing code and wire names remain valid. The resident CUDA installation helper is test-only, and normal dispatch refuses an absent runtime. These contracts are useful for source integration and review; they do not establish a working public trading service. For the financial architecture and a concrete order example, read the Bombil VM explanation.

Names and interface ownership

Public concept	Exact implementation name
Runtime boundary	`runtime/src/onebook/`
Financial state-machine crate	`one-book`, under `orderbook/`
Native dispatch identity	`ONEBOOK_PROGRAM_ID = SHA256("eto:program:onebook")`
SDK namespace	`onebook`
Manifest RPC spelling	`eto_oneBook*`, including `eto_oneBookGetAbi`
Earlier architectural proposals	`onebook_*` names in the design plan; not proof of registered RPC methods

Do not substitute guessed bombil_* methods. The design plan's proposed 128-byte order record, scalar machine's current 96-byte order record and native boundary's 40-byte command describe different layers. The planned UTH vm_origin = 5 reservation also does not establish every adapter or cross-VM route. Dispatch identity, scalar types, architectural plan.

Native transaction admission

Constraint	Required value or behavior
Command count	Exactly one Bombil instruction per transaction
Companion instructions	Compute-budget instructions only
Execution intent	Commit; simulation needs an unimplemented resident GPU fork overlay
Journal	Ordered transaction journal required
Instruction data	Exactly 40 bytes of canonical CUDA wire v1
Declared accounts	Exactly three distinct keys, in the order below
Result origin	Sealed validator-local runtime; clients submit commands, not trusted OBD2/OBO1/receipt bytes

Position	Account	Permission
0	Instance descriptor	Read-only
1	Derived output account	Writable
2	Authority	Read-only transaction signer

The command validator requires version byte 0 to equal 1, kind byte 1 in 1..=3, and reserved bytes 5–7 to be zero. Additional reserved-byte and flag rules depend on the kind; use the canonical encoder and validator instead of treating the length check as sufficient. These restrictions mean the present entrypoint does not admit an arbitrary multi-program financial bundle. Admission and account checks, canonical command checks.

Provisioned state and error boundaries

Preflight checks the instance descriptor, the signer's authority over the command account index, the derived output account, and ordered metadata/tip pages before requesting a speculative CUDA mutation. The output account must be non-executable, owned by the Bombil program and exactly 1,024 bytes. The descriptor is versioned OBI2, binds the instance/configuration and contains 1–4,096 account authorities. Preflight, descriptor and output derivation.

Error text at native dispatch	Meaning
`OneBook requires instance, output, and signer accounts`	Wrong declared-account count
`OneBook simulation requires a resident GPU fork overlay`	Non-commit execution is rejected
`OneBook requires an ordered transaction journal`	Missing enclosing journal
`One Book transaction contains another program`	A companion is neither Bombil nor compute-budget
`One Book transaction must contain exactly one command`	Wrong Bombil instruction count
`OneBook instruction aliases declared accounts`	Two or more declared roles use the same key
`OneBook ordered state is not provisioned`	Ordered-state preflight failed; debug diagnostics contain the specific cause
`OneBook resident CUDA runtime unavailable`	No resident engine is installed; no scalar fallback runs

Permission failures have separate messages for the writable output, read-only instance and read-only signer. A configuration mismatch after engine selection is an engine defect, rather than an ordinary financial rejection. The installation helper with_onebook_cuda_runtime is guarded by #[cfg(test)]; enabling the Cargo CUDA dependency does not install it in production. Installation gate, preflight and engine selection.

Reference account wrappers

The older account wrapper authenticates a decoded command's actor against the signer, applies the scalar reference machine and prepares replacement state/receipt accounts. Its wrapper version is 1; state magic is OBVMST01, receipt magic is OBVMRC01, and each fixed-capacity account is capped at 10 MiB. This is a different seam from the resident device-page representation. Wrapper constants and errors, scalar authority and transition.

Current native dispatch deliberately does not call apply_to_accounts when the resident engine is missing. Restoring a device from a host snapshot or running the scalar machine does not satisfy its rollback and block-promotion contract. QMDB remains the authoritative commit/state-root boundary; the device-page adapter does not independently commit a second root. No fallback, device-page contract.

SDK manifest and server availability

The source manifest contains these names:

eto_oneBookGetAbi                 eto_oneBookGetManifest
eto_oneBookGetMetadata            eto_oneBookGetAccount
eto_oneBookGetOrder               eto_oneBookGetFreePosition
eto_oneBookGetTransition          eto_oneBookGetStatus
eto_oneBookGetExecutionBlock      eto_oneBookGetExecutionArtifact
eto_oneBookGetFinalityProof       eto_oneBookVerifyFinalityProof
eto_oneBookEncodeCommand          eto_oneBookBuildSvmInstruction
eto_oneBookBuildVmCall

These are names the client can send, not evidence that a server implements them. A fresh scan of runtime/src/rpc/ during this pass found no matching Bombil/OneBook handlers. The artifact service, supported release and deployed method behavior remain to be established. Manifest, CLI dispatch reference.

No Bombil-specific HILSA host ABI is established by the documented interfaces. Use HILSA's exact VM interfaces when evaluating that integration. Source tests for missing-runtime rejection, financial rejection and malformed local artifacts were inspected; no Bombil transaction, CUDA compilation or public tutorial was executed during this documentation pass.