Architecture · Explanation
Bombil financial execution environment
Bombil is Singularity's financial execution environment. Its VM-level design makes signed financial commands, such as placing an order, the unit of execution. Matching and accounting produce changes for the same shared state used by the other runtimes.
Consider an order to buy ten units at no more than 100 price ticks per unit. A protected market order carries that price bound into the financial state machine, which applies its matching rules and produces a receipt for the invocation. Bombil's scalar reference models this order type; its native adapter binds the validator-local result to the signed command and ordered state. Order semantics, invocation binding.
Bombil was previously called One Book / OneBook. Code and interfaces retain onebook, ONEBOOK_PROGRAM_ID and eto_oneBook*. Resident CUDA execution is still gated in the inspected source: the installation helper is test-only, and dispatch rejects a missing runtime. Installation seam, dispatch gate.
For identifiers, command bytes, account permissions and errors, use the Bombil command and integration reference.
Why give finance a VM-level boundary?
The design places Bombil alongside SVM, EVM, WASM, Move and proof-verification services on common state. Its intended generalized instrument model describes instruments as versioned data: prices and quantities use integers, while risk parameters and oracle references describe the financial rules.
That separation lets the architecture distinguish two clocks. Matching and liquidation work against accepted local state. A foreign-chain deposit or withdrawal progresses through its own verification and settlement lifecycle. The financial hot path does not wait for a foreign RPC request or bridge relay to complete.
The planned HILSA relationship makes the distinction useful for credit decisions: verified inputs can authorize changes to credit, while unverified observations belong only in paper-mode displays and marks. This is architectural intent, not an implemented Bombil HILSA host ABI. Follow HILSA's read model for the implemented common read boundary and cross-chain settlement for the separate external effect. Architectural intent.
The dated plan's batch pipeline and record layout differ from current native admission. Its UTH vm_origin = 5 reservation also does not establish a generic cross-VM route. The reference distinguishes the design's proposed layouts from the current command and scalar records.
One command, one ordered invocation
Current native admission deliberately narrows the operation: exactly one financial command may accompany compute-budget instructions, using an ordered transaction journal and commit intent. It declares three distinct accounts: a read-only instance descriptor, a writable output account, and a read-only transaction signer. An unrelated application instruction or a second financial command is rejected. This entrypoint does not currently provide arbitrary multi-program composition around the financial transition. Admission and permissions.
Preflight validates the command, instance, signer's account ownership and ordered state before asking CUDA to change its speculative branch. Simulation is not a workaround for the missing resident engine; it requires a resident GPU fork overlay. Use the reference's admission and error tables when diagnosing an integration. Ordered preflight.
The node supplies the result, not the client
The transaction supplies a command, never client-authored OBD2 deltas, OBO1 output bytes or a trusted receipt. The local invocation fingerprint binds the transaction hash, signer, instruction position, transaction position, consensus slot, instance, configuration, previous tip, expected sequence and command. The sealed validator-local producer returns a result that is consumed once. A result from one invocation cannot stand in for another. Binding and producer, sealed result ownership.
After artifact validation, device-page staging checks every previous image against ordered account state before publishing any replacements into the transaction-local changeset. The adapter preserves canonical instance-scoped page bytes. QMDB remains the state-root and commit boundary; the financial adapter does not commit an independent database or second authoritative root. Page staging contract.
This gives failures distinct meanings. A rejected financial command stages no accepted pages. A malformed local engine artifact or configuration mismatch is an engine defect, not an ordinary user rejection. The dispatch regressions inspect those boundaries separately. Regression evidence.
The reference machine is a different seam
The one-book crate supplies checked scalar transitions and canonical encodings for comparison with optimized execution. It models limit, immediate-or-cancel, fill-or-kill, post-only and protected market placement. A protected market order still carries a price bound.
The older account wrapper authenticates the command's actor against the signer, applies the scalar transition and produces versioned, fixed-capacity state and receipt replacements. These helpers support tests and reference integration. They are not a fallback in current native dispatch: restoring a fresh device from a host snapshot or invoking scalar execution does not fulfill the resident engine's rollback and block-promotion contract. Reference wrapper, no fallback.
Integration and acceptance evidence
The SDK's onebook manifest lists artifact and command-building methods. A name the client can send does not establish a server implementation; matching handlers were not located in the inspected node RPC tree. The Bombil reference records the names and that availability boundary. An artifact-service deployment and supported release remain to be established.
Focused source tests distinguish missing CUDA, financial rejection and malformed local artifacts; wrapper tests separately cover matching, authority and capacity failure. They were inspected, not compiled or run for this documentation. For a design evaluation, decide which inputs must be verified before credit changes, then follow HILSA. For integration, establish the exact resident engine, provisioning, RPC service and release before attempting a transaction.