feat(sol): set and consume bit distribution

Author: stuarttimwhite

solidity/src/base/Constants.sol

@@ -174,7 +174,7 @@ uint256 constant VK_TAU_HY_REAL = 0x2bad9a374aec49d329ec66e8f530f68509313450580c
 uint256 constant VK_TAU_HY_IMAG = 0x219edfceee1723de674f5b2f6fdb69d9e32dd53b15844956a630d3c7cdaa6ed9;
 
 /// @dev Size of the verification builder in bytes.
-uint256 constant VERIFICATION_BUILDER_SIZE = 0x20 * 13;
+uint256 constant VERIFICATION_BUILDER_SIZE = 0x20 * 14;
 /// @dev Offset of the pointer to the challenge queue in the verification builder.
 uint256 constant BUILDER_CHALLENGES_OFFSET = 0x20 * 0;
 /// @dev Offset of the pointer to the first round MLEs in the verification builder.
@@ -201,6 +201,8 @@ uint256 constant BUILDER_TABLE_CHI_EVALUATIONS_OFFSET = 0x20 * 10;
 uint256 constant BUILDER_FIRST_ROUND_COMMITMENTS_OFFSET = 0x20 * 11;
 /// @dev Offset of the pointer to the final round commitments in the verification builder.
 uint256 constant BUILDER_FINAL_ROUND_COMMITMENTS_OFFSET = 0x20 * 12;
+/// @dev Offset of the pointer to the final round bit distributions in the verification builder.
+uint256 constant BUILDER_FINAL_ROUND_BIT_DISTRIBUTIONS_OFFSET = 0x20 * 13;
 
 /// @dev The initial transcript state. This is the hash of the empty string.
 uint256 constant INITIAL_TRANSCRIPT_STATE = 0x7c26f909f37b2c61df0bb3b19f76296469cb4d07b582a215c4e2b1f7a05527c3;

solidity/src/builder/VerificationBuilder.pre.sol

@@ -23,6 +23,7 @@ library VerificationBuilder {
         uint256[] tableChiEvaluations;
         uint256 firstRoundCommitmentsPtr;
         uint256 finalRoundCommitmentsPtr;
+        uint256[] bitDistributions;
     }
 
     /// @notice Allocates and reserves a block of memory for a verification builder
@@ -771,15 +772,49 @@ library VerificationBuilder {
     /// @param __builder The builder struct
     /// @param __values The bit distributions array
     function __setBitDistributions(Builder memory __builder, uint256[] memory __values) internal pure {
+        assembly {
+            function builder_set_bit_distributions(builder_ptr, values_ptr) {
+                mstore(add(builder_ptr, BUILDER_FINAL_ROUND_BIT_DISTRIBUTIONS_OFFSET), values_ptr)
+            }
+            builder_set_bit_distributions(__builder, __values)
+        }
+    }
+
+    /// @notice Consumes a final round bit distribution from the verification builder
+    /// @custom:as-yul-wrapper
+    /// #### Wrapped Yul Function
+    /// ##### Signature
+    /// ```yul
+    /// builder_consume_bit_distribution(builder_ptr) -> vary_mask, leading_bit_mask
+    /// ```
+    /// ##### Parameters
+    /// * `builder_ptr` - memory pointer to the builder struct region
+    /// ##### Return Values
+    /// * `vary_mask` - the vary mask of the bit distribution
+    /// * `leading_bit_mask` - the leading bit mask of the bit distribution
+    /// @dev Dequeues and returns a final round bit distribution. Reverts with Errors.EmptyQueue if no values remain
+    /// @param __builder The builder struct
+    /// @return __varyMask the vary mask of the consumed bit distribution
+    /// @return __leadingBitMask the leading bit mask of the consumed bit distribution
+    function __consumeBitDistribution(Builder memory __builder)
+        internal
+        pure
+        returns (uint256 __varyMask, uint256 __leadingBitMask)
+    {
         assembly {
             // IMPORT-YUL ../base/Errors.sol
             function err(code) {
                 revert(0, 0)
             }
-            function builder_set_bit_distributions(builder_ptr, values_ptr) {
-                if mload(values_ptr) { err(ERR_UNSUPPORTED_PROOF) }
+            // IMPORT-YUL ../base/Queue.pre.sol
+            function dequeue(queue_ptr) -> value {
+                revert(0, 0)
             }
-            builder_set_bit_distributions(__builder, __values)
+            function builder_consume_bit_distribution(builder_ptr) -> vary_mask, leading_bit_mask {
+                vary_mask := dequeue(add(builder_ptr, BUILDER_FINAL_ROUND_BIT_DISTRIBUTIONS_OFFSET))
+                leading_bit_mask := dequeue(add(builder_ptr, BUILDER_FINAL_ROUND_BIT_DISTRIBUTIONS_OFFSET))
+            }
+            __varyMask, __leadingBitMask := builder_consume_bit_distribution(__builder)
         }
     }
 

solidity/test/base/Constants.t.sol

@@ -85,7 +85,7 @@ contract ConstantsTest is Test {
     }
 
     function testVerificationBuilderOffsetsAreValid() public pure {
-        uint256[13] memory offsets = [
+        uint256[14] memory offsets = [
             BUILDER_CHALLENGES_OFFSET,
             BUILDER_FIRST_ROUND_MLES_OFFSET,
             BUILDER_FINAL_ROUND_MLES_OFFSET,
@@ -98,7 +98,8 @@ contract ConstantsTest is Test {
             BUILDER_COLUMN_EVALUATIONS_OFFSET,
             BUILDER_TABLE_CHI_EVALUATIONS_OFFSET,
             BUILDER_FIRST_ROUND_COMMITMENTS_OFFSET,
-            BUILDER_FINAL_ROUND_COMMITMENTS_OFFSET
+            BUILDER_FINAL_ROUND_COMMITMENTS_OFFSET,
+            BUILDER_FINAL_ROUND_BIT_DISTRIBUTIONS_OFFSET
         ];
         uint256 offsetsLength = offsets.length;
         assert(VERIFICATION_BUILDER_SIZE == offsetsLength * WORD_SIZE);

solidity/test/builder/VerificationBuilder.t.pre.sol

@@ -851,27 +851,38 @@ contract VerificationBuilderTest is Test {
         assert(VerificationBuilder.__getFinalRoundCommitments(builder) == valuesPtr);
     }
 
-    /// forge-config: default.allow_internal_expect_revert = true
-    function testSetBitDistributions() public {
+    function testSetBitDistributions() public pure {
         VerificationBuilder.Builder memory builder = VerificationBuilder.__builderNew();
         uint256[] memory emptyValues = new uint256[](0);
         // Empty array should not revert
         VerificationBuilder.__setBitDistributions(builder, emptyValues);
 
         uint256[] memory values = new uint256[](1);
         values[0] = 0x12345678;
-        vm.expectRevert(Errors.UnsupportedProof.selector);
+        // Populated array should not revert
         VerificationBuilder.__setBitDistributions(builder, values);
     }
 
-    /// forge-config: default.allow_internal_expect_revert = true
-    function testFuzzSetBitDistributions(uint256[] memory values) public {
+    function testFuzzSetBitDistributions(uint256[] memory values) public pure {
         vm.assume(values.length > 0);
         VerificationBuilder.Builder memory builder = VerificationBuilder.__builderNew();
-        vm.expectRevert(Errors.UnsupportedProof.selector);
         VerificationBuilder.__setBitDistributions(builder, values);
     }
 
+    function testConsumeBitDistributions() public pure {
+        VerificationBuilder.Builder memory builder = VerificationBuilder.__builderNew();
+        uint256[] memory values = new uint256[](2);
+        values[0] = 0x12345678;
+        values[1] = 0x12345677;
+        // Populated array should not revert
+        VerificationBuilder.__setBitDistributions(builder, values);
+        uint256 varyMask;
+        uint256 leadingBitMask;
+        (varyMask, leadingBitMask) = VerificationBuilder.__consumeBitDistribution(builder);
+        assert(varyMask == 0x12345678);
+        assert(leadingBitMask == 0x12345677);
+    }
+
     function testGetChiEvaluations() public pure {
         VerificationBuilder.Builder memory builder;
         uint256[] memory values = new uint256[](3);