lib/machine/src/admission/root.zig

daab053ee43316e1809a84551d573ddd1e5bf3d2

 1 //! Replaying a run requires feeding the guest exactly the inputs the first run saw,
 2 //! in the same order, and this namespace records each one so a later reader can
 3 //! check the whole history from the receipts alone. Four kinds of input cross into
 4 //! the guest: terminal bytes, a virtual-time advance, an entropy block, and an effect
 5 //! result. Each input is checked against where the guest stood when it arrived.
 6 //! Each input reaches the guest through its request ring, together with the authority
 7 //! to run the guest work that settles it.
 8 //!
 9 //! Terminal, entropy, and effect-result payloads are held in fixed storage sized
10 //! by the machine ABI message bounds. While a guest request for an outside effect
11 //! awaits its result, every other kind of input is refused until that result is
12 //! admitted. The counters that order inputs are checked for overflow, so a counter
13 //! at its limit rejects the input and holds its value. Verification recomputes a
14 //! receipt from its material and rejects an input that changed. Receipts of different
15 //! kinds must never collide.
16 //!
17 //! The namespace admits each recorded outside influence (an *admission*): it folds
18 //! the influence into an authenticated position and produces a receipt committing
19 //! the input and that position. That position (the *basis*) names the authenticated
20 //! state in force, the identity of the shared execution rules, the five ordering
21 //! counters, and any effect request still outstanding. `prepare` applies one input
22 //! to a basis it has validated, then hashes the outcome into a receipt. `bindDelivery`
23 //! joins one admission with the world, generation, and token authorized for one
24 //! run turn (an *activation fence*), and with the authenticated state that follows.
25 //! The guest's request ring receives that joined bundle, a *delivery*. Receipts
26 //! are SHA-256 digests, each taken under a distinct constant string hashed before
27 //! the value (a *domain tag*), with one tag for admissions and another for deliveries.
28 //!
29 //! - *record*: one input crossing into the guest.
30 //! - *admission receipt*: the digest committing one admission.
31 //! - *source root*: the digest naming the authenticated state a basis stands on.
32 //! - *contract fingerprint*: the identity of the shared execution rules, computed
33 //!   over the encoded profile with the backend field and the claim fields zeroed.
34 //! - *frontiers*: the five counters that order admitted inputs and only rise, one
35 //!   each for the input position, the terminal offset, the time tick, the entropy
36 //!   generation, and the effect count.
37 
38 const canon = @import("canon.zig");
39 const types = @import("types.zig");
40 
41 pub const Admission = types.Admission;
42 pub const Basis = types.Basis;
43 pub const Delivery = types.Delivery;
44 pub const DeliveryReceipt = types.DeliveryReceipt;
45 pub const Digest = types.Digest;
46 pub const EffectResult = types.EffectResult;
47 pub const EffectRequest = types.EffectRequest;
48 pub const EffectRequestReceipt = types.EffectRequestReceipt;
49 pub const Entropy = types.Entropy;
50 pub const Error = canon.Error;
51 pub const Frontiers = types.Frontiers;
52 pub const Receipt = types.Receipt;
53 pub const Record = types.Record;
54 pub const Terminal = types.Terminal;
55 pub const VirtualTime = types.VirtualTime;
56 pub const effect_result_bytes_max = types.effect_result_bytes_max;
57 pub const entropy = canon.entropy;
58 pub const entropy_bytes_max = types.entropy_bytes_max;
59 pub const effectResult = canon.effectResult;
60 pub const bindDelivery = canon.bindDelivery;
61 pub const prepare = canon.prepare;
62 pub const terminal = canon.terminal;
63 pub const terminal_bytes_max = types.terminal_bytes_max;
64 pub const validateBasis = canon.validateBasis;
65 pub const verify = canon.verify;
66 pub const verifyDelivery = canon.verifyDelivery;
67 pub const virtualTime = canon.virtualTime;