RuntimeTable: make backwards compatible, deprecating old functions

Author: querolita

CHANGELOG.md

@@ -23,7 +23,13 @@ This project adheres to
 - Updated Rust nightly version from `2024-06-13` to `2024-09-05` to match the
   version used in Mina proof-systems repository.
 
-- Updated the runtime table API with less abstract function names.
+- Improved the runtime table API with a `RuntimeTable` class with better 
+  readability.
+
+### Deprecated
+
+- Deprecate the `Gates.addRuntimeTableConfig` and `Gadgets.inTable` functions in favor
+  of the `RuntimeTable` class API. 
 
 ### Fixed
 

src/lib/provable/gadgets/gadgets.ts

@@ -33,7 +33,7 @@ import { divMod32, addMod32, divMod64, addMod64 } from './arithmetic.js';
 import { SHA2 } from './sha2.js';
 import { SHA256 } from './sha256.js';
 import { BLAKE2B } from './blake2b.js';
-import { rangeCheck3x12 } from './lookup.js';
+import { rangeCheck3x12, inTable } from './lookup.js';
 import { arrayGet, arrayGetGeneric } from './basic.js';
 import { sliceField3 } from './bit-slices.js';
 
@@ -586,6 +586,31 @@ const Gadgets = {
     return rangeCheck3x12(v0, v1, v2);
   },
 
+  /**
+   * In-circuit check that up to 3 pairs of index and value are in the runtime
+   * table given by the identifier. Each given pair is a tuple composed of a
+   * bigint and a Field.
+   *
+   * Internally, it creates a lookup gate for the three pairs. If fewer pairs are
+   * given, the remaining pairs are duplicates of the first one.
+   *
+   * @param id
+   * @param pair0
+   * @param pair1
+   * @param pair2
+   *
+   * @deprecated {@link inTable} is deprecated in favor of RuntimeTable class, 
+   * which provides a more ergonomic API.
+   */
+  inTable(
+    id: number,
+    pair0: [bigint, Field],
+    pair1?: [bigint, Field] | undefined,
+    pair2?: [bigint, Field] | undefined
+  ) {
+    return inTable(id, pair0, pair1, pair2);
+  },
+
   /**
    * Gadgets for foreign field operations.
    *

src/lib/provable/gadgets/lookup.ts

@@ -1,7 +1,7 @@
 import { Field } from '../field.js';
 import { Gates } from '../gates.js';
 
-export { rangeCheck3x12 };
+export { rangeCheck3x12, inTable };
 
 function rangeCheck3x12(v0: Field, v1: Field, v2: Field) {
   // Checks that all three input values exist in the RANGE_CHECK_TABLE (tableId: 1)
@@ -17,4 +17,34 @@ function rangeCheck3x12(v0: Field, v1: Field, v2: Field) {
     v2,
     Field.from(0)
   );
-}
+}
+
+/**
+ * In-circuit check that up to 3 pairs of index and value are in the runtime
+ * table given by the identifier. Each given pair is a tuple composed of a
+ * bigint and a Field.
+ *
+ * **Note**: The runtime table must be configured before calling this function.
+ *
+ * **Note**: Table id 0 and 1 are reserved values, do not use them.
+ *
+ * @param id
+ * @param pair0
+ * @param pair1
+ * @param pair2
+ * 
+ * @deprecated {@link inTable} is deprecated in favor of {@link RuntimeTable} class, 
+ * which provides a more ergonomic API.
+ */
+function inTable(
+  id: number,
+  pair0: [bigint, Field],
+  pair1?: [bigint, Field] | undefined,
+  pair2?: [bigint, Field] | undefined
+) {
+  let [idx0, v0] = pair0;
+  let [idx1, v1] = pair1 === undefined ? pair0 : pair1;
+  let [idx2, v2] = pair2 === undefined ? pair0 : pair2;
+
+  Gates.lookup(Field.from(id), Field.from(idx0), v0, Field.from(idx1), v1, Field.from(idx2), v2);
+}

src/lib/provable/gadgets/runtime-table.ts

@@ -91,4 +91,4 @@ class RuntimeTable {
             this.pairs = [];
         }
     }
-}
+}

src/lib/provable/gates.ts

@@ -17,6 +17,7 @@ export {
   foreignFieldAdd,
   foreignFieldMul,
   KimchiGateType,
+  addRuntimeTableConfig,
 };
 
 export { fieldVar };
@@ -292,6 +293,9 @@ function raw(kind: KimchiGateType, values: Field[], coefficients: bigint[]) {
  *
  * @param id
  * @param firstColumn
+ * 
+ * @deprecated {@link addRuntimeTableConfig} is deprecated in favor of RuntimeTable
+ * class, which provides a more ergonomic API.
  */
 function addRuntimeTableConfig(id: number, firstColumn: bigint[]) {
   Snarky.gates.addRuntimeTableConfig(

src/lib/provable/test/lookup.unit-test.ts

@@ -4,7 +4,10 @@ import { Spec, boolean, equivalentAsync, fieldWithRng } from '../../testing/equi
 import { Random } from '../../testing/property.js';
 import { assert } from '../gadgets/common.js';
 import { Gadgets } from '../gadgets/gadgets.js';
+import { Gates } from '../gates.js';
 import { constraintSystem, contains } from '../../testing/constraint-system.js';
+import { FeatureFlags } from '../../proof-system/feature-flags.js';
+import { Cache } from '../../proof-system/cache.js';
 
 let uint = (n: number | bigint): Spec<bigint, Field> => {
   return fieldWithRng(Random.bignat((1n << BigInt(n)) - 1n));
@@ -45,3 +48,56 @@ let uint = (n: number | bigint): Spec<bigint, Field> => {
     }
   );
 }
+
+// Runtime table tests
+{
+  let RuntimeTable = ZkProgram({
+    name: 'runtime-table',
+    methods: {
+      runtimeTable: {
+        privateInputs: [Field, Field, Field],
+        async method(v0: Field, v1: Field, v2: Field) {
+          let tableId = 2;
+          let indices = [0n, 1n, 2n, 3n, 4n, 5n, 6n, 7n, 8n, 9n];
+          Gates.addRuntimeTableConfig(tableId, indices);
+          // values are inserted into the table in the given positions
+          Gadgets.inTable(tableId, [5n, v0], [6n, v1], [7n, v2]);
+          // a second time can be used to check more values in more positions
+          Gadgets.inTable(tableId, [2n, v0]);
+          // can ask for the same index asked previously
+          Gadgets.inTable(tableId, [6n, v1]);
+          // even multiple times in the same call
+          Gadgets.inTable(tableId, [6n, v1], [6n, v1]);
+        },
+      },
+    },
+  });
+
+  // constraint system sanity check
+
+  constraintSystem.fromZkProgram(RuntimeTable, 'runtimeTable', contains(['Lookup']));
+
+  // check feature flags are set up correctly
+  const featureFlags = await FeatureFlags.fromZkProgram(RuntimeTable, true);
+  assert(featureFlags.lookup === true);
+  assert(featureFlags.runtimeTables === true);
+
+  await RuntimeTable.compile({
+    cache: Cache.None,
+    forceRecompile: true,
+    withRuntimeTables: true,
+  });
+
+  await equivalentAsync({ from: [uint(12), uint(12), uint(12)], to: boolean }, { runs: 1 })(
+    (x, y, z) => {
+      assert(x < 1n << 12n);
+      assert(y < 1n << 12n);
+      assert(z < 1n << 12n);
+      return true;
+    },
+    async (x, y, z) => {
+      let { proof } = await RuntimeTable.runtimeTable(x, y, z);
+      return await RuntimeTable.verify(proof);
+    }
+  );
+}

src/lib/provable/test/runtime-table.unit-test.ts

@@ -5,7 +5,8 @@ import { Random } from '../../testing/property.js';
 import { assert } from '../gadgets/common.js';
 import { RuntimeTable } from '../gadgets/runtime-table.js';
 import { constraintSystem, contains } from '../../testing/constraint-system.js';
-import { FeatureFlags, Cache } from 'o1js';
+import { FeatureFlags } from '../../proof-system/feature-flags.js';
+import { Cache } from '../../proof-system/cache.js';
 
 let uint = (n: number | bigint): Spec<bigint, Field> => {
   return fieldWithRng(Random.bignat((1n << BigInt(n)) - 1n));