lib/machine/src/admission/types.zig

daab053ee43316e1809a84551d573ddd1e5bf3d2

  1 const os = @import("os");
  2 const profile = @import("../profile/root.zig");
  3 
  4 /// The 32-byte digest type every root and receipt in this namespace carries.
  5 /// The type comes from the machine ABI, so an admission digest and a message digest
  6 /// are one type.
  7 pub const Digest = os.abi.Digest;
  8 /// The largest terminal payload the machine ABI allows, in bytes.
  9 /// A terminal record built from more bytes than this is rejected.
 10 pub const terminal_bytes_max: usize = os.abi.message.terminal_bytes_max;
 11 /// The largest entropy payload the machine ABI allows, in bytes.
 12 /// An entropy record built from more bytes than this is rejected.
 13 pub const entropy_bytes_max: usize = os.abi.message.entropy_bytes_max;
 14 /// The largest effect-result payload the machine ABI allows, in bytes.
 15 /// An effect result built from more bytes than this is rejected.
 16 pub const effect_result_bytes_max: usize = os.abi.message.effect_result_bytes_max;
 17 
 18 /// One terminal input after admission, holding where its bytes sit in the terminal
 19 /// stream, how many bytes it carries, and the fixed storage those bytes occupy.
 20 /// The offset must equal the terminal frontier at admission, and admitting the record
 21 /// moves that frontier forward by the payload length.
 22 /// Every storage byte past the payload length is zero.
 23 pub const Terminal = struct {
 24     offset: u64,
 25     length: u16,
 26     storage: [terminal_bytes_max]u8,
 27 };
 28 
 29 /// One clock advance after admission, holding the tick it leaves and the strictly
 30 /// greater tick it moves to.
 31 /// The source tick must equal the time frontier at admission.
 32 pub const VirtualTime = struct {
 33     from_tick: u64,
 34     to_tick: u64,
 35 };
 36 
 37 /// One admitted entropy block: its generation, its payload length, and fixed payload
 38 /// storage.
 39 /// The generation must be the entropy frontier plus one.
 40 pub const Entropy = struct {
 41     generation: u64,
 42     length: u16,
 43     storage: [entropy_bytes_max]u8,
 44 };
 45 
 46 /// One admitted result for outside work, bound to the request it answers: the request,
 47 /// the effect status, the output root, the payload length, and fixed payload storage.
 48 /// The carried request must equal the outstanding effect, and admitting the result
 49 /// clears that effect.
 50 pub const EffectResult = struct {
 51     request: EffectRequest,
 52     status: os.abi.EffectStatus,
 53     output_root: Digest,
 54     length: u16,
 55     storage: [effect_result_bytes_max]u8,
 56 };
 57 
 58 /// One outstanding guest request: the digest of its receipt and its correlation
 59 /// value.
 60 /// The correlation must be the effect frontier plus one, so requests answer in order.
 61 pub const EffectRequest = struct {
 62     receipt: EffectRequestReceipt,
 63     correlation: u64,
 64 };
 65 
 66 /// The receipt digest that names one guest effect request.
 67 pub const EffectRequestReceipt = struct {
 68     digest: Digest,
 69 };
 70 
 71 /// One record of an input crossing into the guest.
 72 /// The four kinds are terminal bytes, a virtual-time advance, an entropy block,
 73 /// and an effect result.
 74 pub const Record = union(enum) {
 75     terminal: Terminal,
 76     virtual_time: VirtualTime,
 77     entropy: Entropy,
 78     effect_result: EffectResult,
 79 };
 80 
 81 /// The five counters that fix the order of admitted inputs and only rise, one for
 82 /// the input position, one for the terminal offset, one for the time tick, one for
 83 /// the entropy generation, and one for the effect count.
 84 /// Every counter moves forward under overflow-checked arithmetic, and an exhausted
 85 /// counter rejects the admission.
 86 pub const Frontiers = struct {
 87     input: u64,
 88     terminal_input_offset: u64,
 89     virtual_time_tick: u64,
 90     entropy_generation: u64,
 91     effect: u64,
 92 };
 93 
 94 /// The authenticated position an input is admitted against, naming the source root
 95 /// in force, the contract fingerprint, the five frontiers, and any effect still
 96 /// outstanding.
 97 /// A basis with an all-zero contract digest, an all-zero source root, or an out-of-order
 98 /// outstanding request is rejected.
 99 pub const Basis = struct {
100     contract: profile.ContractFingerprint,
101     source_root: Digest,
102     frontiers: Frontiers,
103     outstanding_effect: ?EffectRequest,
104 };
105 
106 /// The receipt digest taken over one admission.
107 pub const Receipt = struct {
108     digest: Digest,
109 };
110 
111 /// One admitted record with everything needed to recheck it: the contract fingerprint,
112 /// the source root, the input position, the frontiers before it, the record, the
113 /// frontiers expected after it, the outstanding effect before and after, and the
114 /// committing receipt.
115 /// Verification rebuilds the whole value from the basis and the record, then compares
116 /// that rebuild against the stored one.
117 pub const Admission = struct {
118     contract: profile.ContractFingerprint,
119     source_root: Digest,
120     position: u64,
121     frontiers: Frontiers,
122     record: Record,
123     expected: Frontiers,
124     outstanding_effect: ?EffectRequest,
125     expected_outstanding_effect: ?EffectRequest,
126     receipt: Receipt,
127 };
128 
129 /// One admission joined to an activation fence and to the source root that follows,
130 /// in the form written into the guest's request ring.
131 /// The delivery receipt commits the admission receipt, the next source root, and
132 /// all three fence fields.
133 pub const Delivery = struct {
134     admission: Admission,
135     next_source_root: Digest,
136     fence: os.abi.ActivationFence,
137     receipt: DeliveryReceipt,
138 };
139 
140 /// The digest committing one delivery.
141 pub const DeliveryReceipt = struct {
142     digest: Digest,
143 };