[Tolk] Struct PackOptions and UnpackOptions

Allow to control fromCell/toCell behavior

Author: tolk-vm

crypto/smartcont/tolk-stdlib/common.tolk

@@ -219,6 +219,32 @@ fun commitContractDataAndActions(): void
     Auto packing structures to/from cells.
 */
 
+/// PackOptions allows you to control behavior of `obj.toCell()` and similar functions.
+struct PackOptions {
+    /// when a struct has a field of type `bits128` and similar (it's a slice under the hood),
+    /// by default, compiler inserts runtime checks (get bits/refs count + compare with 128 + compare with 0);
+    /// these checks ensure that serialized binary data will be correct, but they cost gas;
+    /// however, if you guarantee that a slice is valid (for example, it comes from trusted sources),
+    /// set this option to true to disable runtime checks;
+    /// note: `int32` and other are always validated for overflow without any extra gas,
+    /// so this flag controls only rarely used `bytesN` / `bitsN` types
+    skipBitsNFieldsValidation: bool = false,
+}
+
+/// UnpackOptions allows you to control behavior of `MyStruct.fromCell(c)` and similar functions.
+struct UnpackOptions {
+    // after finished reading all fields from a cell/slice, call [slice.assertEnd] to ensure no remaining data left;
+    // it's the default behavior, it ensures that you've fully described data you're reading with a struct;
+    // example: `struct Point { x: int8; y: int8 }`, input "0102" is ok, "0102FF" will throw excno 9;
+    // note: setting this to false does not decrease gas (DROP from a stack and ENDS cost the same);
+    // note: this option controls [T.fromCell] and [T.fromSlice], but is ignored by [slice.loadAny]
+    assertEndAfterReading: bool = true,
+
+    /// this excNo is thrown if a prefix doesn't match, e.g. for `struct (0x01) A` given input "88...";
+    /// similarly, for a union type, this is thrown when none of the opcodes match
+    throwIfOpcodeDoesNotMatch: int = 63,
+}
+
 /// Convert anything to a cell (most likely, you'll call it for structures).
 /// Example:
 /// ```
@@ -228,7 +254,7 @@ fun commitContractDataAndActions(): void
 /// Internally, a builder is created, all fields are serialized one by one, and a builder is flushed
 /// (beginCell() + serialize fields + endCell()).
 @pure
-fun T.toCell(self): Cell<T>
+fun T.toCell(self, options: PackOptions = {}): Cell<T>
     builtin;
 
 /// Parse anything from a cell (most likely, you'll call it for structures).
@@ -239,7 +265,7 @@ fun T.toCell(self): Cell<T>
 /// Internally, a cell is unpacked to a slice, and that slice is parsed
 /// (packedCell.beginParse() + read from slice).
 @pure
-fun T.fromCell(packedCell: cell): T
+fun T.fromCell(packedCell: cell, options: UnpackOptions = {}): T
     builtin;
 
 /// Parse anything from a slice (most likely, you'll call it for structures).
@@ -252,7 +278,7 @@ fun T.fromCell(packedCell: cell): T
 /// Note, that a passed slice is NOT mutated, its internal pointer is NOT shifted.
 /// If you need to mutate it, like `cs.loadInt()`, consider calling `cs.loadAny<CounterIncrement>()`.
 @pure
-fun T.fromSlice(rawSlice: slice): T
+fun T.fromSlice(rawSlice: slice, options: UnpackOptions = {}): T
     builtin;
 
 /// Parse anything from a slice, shifting its internal pointer.
@@ -262,8 +288,10 @@ fun T.fromSlice(rawSlice: slice): T
 /// var st: MyStorage = cs.loadAny();     // or cs.loadAny<MyStorage>()
 /// ```
 /// Similar to `MyStorage.fromSlice(cs)`, but called as a slice method and mutates the slice.
+/// Note: [options.assertEndAfterReading] is ignored by this function, because it's actually intended
+/// to read data from the middle.
 @pure
-fun slice.loadAny<T>(mutate self): T
+fun slice.loadAny<T>(mutate self, options: UnpackOptions = {}): T
     builtin;
 
 /// Skip anything in a slice, shifting its internal pointer.
@@ -274,7 +302,7 @@ fun slice.loadAny<T>(mutate self): T
 /// cs.skipAny<TwoInts>();    // skips 64 bits
 /// ```
 @pure
-fun slice.skipAny<T>(mutate self): self
+fun slice.skipAny<T>(mutate self, options: UnpackOptions = {}): self
     builtin;
 
 /// Store anything to a builder.
@@ -284,7 +312,19 @@ fun slice.skipAny<T>(mutate self): self
 /// var b = beginCell().storeUint(32).storeAny(msgBody).endCell();
 /// ```
 @pure
-fun builder.storeAny<T>(mutate self, v: T): self
+fun builder.storeAny<T>(mutate self, v: T, options: PackOptions = {}): self
+    builtin;
+
+/// Returns serialization prefix of a struct. Works at compile-time.
+/// Example: for `struct (0xF0) AssetRegular { ... }` will return `240`.
+@pure
+fun T.getDeclaredPackPrefix(): int
+    builtin;
+
+/// Returns serialization prefix length of a struct. Works at compile-time.
+/// Example: for `struct (0xF0) AssetRegular { ... }` will return `16`.
+@pure
+fun T.getDeclaredPackPrefixLen(): int
     builtin;
 
 /// Cell<T> represents a typed cell reference (as opposed to untyped `cell`).
@@ -316,7 +356,7 @@ struct Cell<T> {
 /// var extra = st.extra.load();   // it's ExtraData, unpacked from loaded ref
 /// ```
 @pure
-fun Cell<T>.load(self): T
+fun Cell<T>.load(self, options: UnpackOptions = {}): T
     builtin;
 
 /// Converts a typed cell into a slice.

tolk-tester/tests/invalid-symbol/err-2833.tolk

@@ -0,0 +1,13 @@
+struct Point {
+    x: int8;
+    y: int8;
+}
+
+fun main() {
+    return Point.getDeclaredPackPrefix();
+}
+
+/**
+@compilation_should_fail
+@stderr type `Point` does not have a serialization prefix
+ */

tolk-tester/tests/pack-unpack-1.tolk

@@ -48,7 +48,7 @@ fun test3() {
 @method_id(104)
 fun test4() {
     var s = stringHexToSlice("000000010000000200000003");
-    var p = Point.fromSlice(s);     // does not mutate s
+    var p = Point.fromSlice(s, {assertEndAfterReading: false});     // does not mutate s
     return (p, s.remainingBitsCount());
 }
 
@@ -114,11 +114,11 @@ fun main(c: cell) {
     32 STI                      //  b
     ENDC                        //  c
     CTOS                        //  s
-    32 PUSHINT                  //  s '12=32
+    32 PUSHINT                  //  s '15=32
     SDSKIPFIRST                 //  s
-    32 PUSHINT                  //  s '13=32
+    32 PUSHINT                  //  s '16=32
     SDSKIPFIRST                 //  s
-    SBITS                       //  '14
+    SBITS                       //  '17
   }>
 """
 

tolk-tester/tests/pack-unpack-4.tolk

@@ -92,7 +92,7 @@ fun invalid105_slice(): slice asm "b{1100} PUSHSLICE";  // prefix 0b11 doesn't e
 @method_id(105)
 fun test5() {
     try {
-        var u = U105.fromSlice(invalid105_slice());
+        var u = U105.fromSlice(invalid105_slice(), {throwIfOpcodeDoesNotMatch: 9});
         return (u is int8) ? 8 : -8;
     } catch (excode) {
         return excode;
@@ -125,37 +125,37 @@ fun main() {}
 """
   test6 PROC:<{                 //
     b{010000000000001111} PUSHSLICE     //  s
-    b{00} SDBEGINSQ             //  s '6
+    b{00} SDBEGINSQ             //  s '8
     IF:<{                       //  s
-      8 LDI                     //  '10 s
-      DROP                      //  '10
-      42 PUSHINT                //  'USlot1 'UTag=42
+      8 LDI                     //  '12 s
+      42 PUSHINT                //  'USlot1 s 'UTag=42
     }>ELSE<{                    //  s
-      b{01} SDBEGINSQ           //  s '6
+      b{01} SDBEGINSQ           //  s '8
       IF:<{                     //  s
-        16 LDI                  //  '15 s
-        DROP                    //  '15
-        44 PUSHINT              //  'USlot1 'UTag=44
+        16 LDI                  //  '17 s
+        44 PUSHINT              //  'USlot1 s 'UTag=44
       }>ELSE<{                  //  s
-        b{10} SDBEGINSQ         //  s '6
+        b{10} SDBEGINSQ         //  s '8
         IF:<{                   //  s
-          32 LDI                //  '20 s
-          DROP                  //  '20
-          46 PUSHINT            //  'USlot1 'UTag=46
+          32 LDI                //  '22 s
+          46 PUSHINT            //  'USlot1 s 'UTag=46
         }>ELSE<{                //  s
-          b{11} SDBEGINSQ       //  s '6
-          DROP                  //  s
-          64 LDI                //  '25 s
-          DROP                  //  '25
-          48 PUSHINT            //  'USlot1 'UTag=48
+          b{11} SDBEGINSQ       //  s '8
+          IFNOTJMP:<{           //  s
+            63 THROW
+          }>
+          64 LDI                //  '27 s
+          48 PUSHINT            //  'USlot1 s 'UTag=48
         }>
       }>
-    }>                          //  u.USlot1 u.UTag
-    44 EQINT                    //  u.USlot1 '27
+    }>
+    SWAP                        //  'USlot1 'UTag s
+    ENDS                        //  u.USlot1 u.UTag
+    44 EQINT                    //  u.USlot1 '29
     IFJMP:<{                    //  u.USlot1
     }>                          //  u.USlot1
     DROP                        //
-    -1 PUSHINT                  //  '29=-1
+    -1 PUSHINT                  //  '31=-1
   }>
 """
  */

tolk-tester/tests/pack-unpack-5.tolk

@@ -166,18 +166,38 @@ fun test9() {
     return (Test9_f1.estimatePackSize(), Test9_f2.estimatePackSize(), Test9_f3.estimatePackSize(), Test9_f4.estimatePackSize());
 }
 
+struct Test10_1 {
+    a: int32;
+    b: builder;     // unpredictable
+}
+
+type Test10_2 = (Test10_1, bool?, RemainingBitsAndRefs);
+
+@method_id(110)
+fun test10() {
+    return (Test10_1.estimatePackSize(), Test10_2.estimatePackSize());
+}
+
+@method_id(120)
+fun test20() {
+    return (Test7_1 .getDeclaredPackPrefixLen(), Test7_1 .getDeclaredPackPrefix(),
+        CellInner8_1.getDeclaredPackPrefixLen(), CellInner8_1.getDeclaredPackPrefix());
+}
+
 fun main() {
     __expect_type(int8.estimatePackSize(), "[int, int, int, int]");
 }
 
 /**
-@testcase | 101 | | [ 32 32 0 0 ] [ 64 64 0 0 ] [ 1 1 0 0 ] [ 1 1 0 0 ] [ 0 0 0 0 ] [ 4 124 0 0 ] [ 6 6 0 0 ] [ 64 64 0 0 ]
+@testcase | 101 | | [ 32 32 0 0 ] [ 64 64 0 0 ] [ 1 1 0 0 ] [ 1 1 0 0 ] [ 0 9999 0 4 ] [ 4 124 0 0 ] [ 6 6 0 0 ] [ 64 64 0 0 ]
 @testcase | 102 | | [ 32 32 0 0 ] [ 1 33 0 0 ] [ 1 33 0 0 ] [ 17 33 0 0 ]
 @testcase | 103 | | [ 67 199 0 0 ] [ 69 599 0 0 ]
 @testcase | 104 | | [ 4 534 0 0 ] [ 2 536 0 0 ] [ 6 1070 0 0 ]
-@testcase | 105 | | [ 2 2 2 4 ] [ 5 5 0 5 ] [ 4 152 1 4 ]
+@testcase | 105 | | [ 2 2 2 4 ] [ 5 9999 0 9 ] [ 4 152 1 4 ]
 @testcase | 106 | | [ 64 64 0 0 ] [ 5 37 1 1 ] [ 5 65 0 1 ]
 @testcase | 107 | | [ 16 16 0 0 ] [ 16 16 0 0 ]
 @testcase | 108 | | [ 10 275 0 0 ] [ 34 158 0 0 ] [ 47 1143 0 1 ]
 @testcase | 109 | | [ 34 130 0 0 ] [ 33 159 0 0 ] [ 4 8 0 0 ] [ 3 7 0 0 ]
+@testcase | 110 | | [ 32 9999 0 4 ] [ 33 9999 0 8 ]
+@testcase | 120 | | 16 4128 1 1
  */