circuit: add input assumptions to docs

packages/circuits/README.md

@@ -125,7 +125,9 @@ Base64Decode: Decodes a base64 encoded string into binary data.
 </details>
 
 ## Utils
-This section provides an overview of utility circom templates available in the `@zk-email/circuits/utils` directory. These templates assist in the construction of zk circuits for various applications beyond the core ZK Email functionalities.
+This section provides an overview of utility circom templates available in the `@zk-email/circuits/utils` directory. These templates assist in the construction of ZK circuits for various applications beyond the core ZK Email functionalities.
+
+> Important: When using these templates outside of zk-email, please ensure you read the assumptions on the input signals that are documented above each template source code. You would need to constrain the inputs accordingly before you pass them to these utility circuits.
 
 ### `utils/array.circom`
 

packages/circuits/lib/rsa.circom

@@ -51,7 +51,9 @@ template RSAVerifier65537(n, k) {
 /// @dev Does not necessarily reduce fully mod modulus (the answer could be too big by a multiple of modulus)
 /// @param n Number of bits per chunk the modulus is split into.
 /// @param k Number of chunks the modulus is split into.
-/// @input base The base to exponentiate.
+/// @input base The base to exponentiate; assumes to consist of `k` limbs, each of which must fit in `n` bits
+/// @input modulus The modulus; assumes to consist of `k` limbs, each of which must fit in `n` bits
+/// @output out The result of the exponentiation.
 template FpPow65537Mod(n, k) {
     signal input base[k];
     signal input modulus[k];

packages/circuits/lib/sha.circom

@@ -11,7 +11,7 @@ include "../utils/functions.circom";
 
 /// @title Sha256Bytes
 /// @notice Computes the SHA256 hash of input bytes
-/// @input paddedIn Message to hash, padded as per the SHA256 specification
+/// @input paddedIn Message to hash, padded as per the SHA256 specification; assumes to consist of bytes
 /// @input paddedInLength Length of the padded message; assumes to be in `ceil(log2(8 * maxByteLength))` bits
 /// @output out The 256-bit hash of the input message
 template Sha256Bytes(maxByteLength) {
@@ -40,7 +40,7 @@ template Sha256Bytes(maxByteLength) {
 
 /// @title Sha256BytesPartial
 /// @notice Computes the SHA256 hash of input bytes with a precomputed state
-/// @input paddedIn Message to hash padded as per the SHA256 specification
+/// @input paddedIn Message to hash padded as per the SHA256 specification; assumes to consist of bytes
 /// @input paddedInLength Length of the padded message; assumes to be in `ceil(log2(8 * maxByteLength))` bits
 /// @input preHash The precomputed state of the hash
 /// @output out SHA hash the input message with the precomputed state
@@ -82,7 +82,7 @@ template Sha256BytesPartial(maxByteLength) {
 /// @title Sha256General
 /// @notice A modified version of the SHA256 circuit that allows specified length messages up to a 
 ///         max to all work via array indexing on the SHA256 compression circuit.
-/// @input paddedIn Message to hash padded as per the SHA256 specification
+/// @input paddedIn Message to hash padded as per the SHA256 specification; assumes to consist of bits
 /// @input paddedInLength Length of the padded message; assumes to be in `ceil(log2(maxBitLength))` bits
 /// @output out The 256-bit hash of the input message
 template Sha256General(maxBitLength) {
@@ -204,9 +204,9 @@ template Sha256General(maxBitLength) {
 
 /// @title Sha256Partial
 /// @notice Calculates the SHA256 hash of a message with a precomputed state
-/// @input paddedIn Message to hash padded as per the SHA256 specification
+/// @input paddedIn Message to hash padded as per the SHA256 specification; assumes to consist of bits
 /// @input paddedInLength Length of the padded message; assumes to be in `ceil(log2(maxBitLength))` bits
-/// @input preHash The precomputed state of the hash
+/// @input preHash The precomputed state of the hash; assumes to consist of bits
 /// @output out The 256-bit hash of the input message
 template Sha256Partial(maxBitLength) {
     // maxBitLength must be a multiple of 512, and the bit circuits in this file are limited to 15 so must be raised if the message is longer.

packages/circuits/utils/array.circom

@@ -46,7 +46,7 @@ template ItemAtIndex(maxArrayLen) {
 /// @title CalculateTotal
 /// @notice Calculate the sum of an array
 /// @param n The number of elements in the array
-/// @input nums The input array
+/// @input nums The input array; assumes elements are small enough that their sum does not overflow the field
 /// @output sum The sum of the input array
 template CalculateTotal(n) {
     signal input nums[n];
@@ -146,8 +146,8 @@ template VarShiftLeft(maxArrayLen, maxOutArrayLen) {
 /// @title AssertZeroPadding
 /// @notice Assert that the input array is zero-padded from the given `startIndex`
 /// @param maxArrayLen The maximum number of elements in the input array
-/// @input in The input array
-/// @input startIndex The index from which the array should be zero-padded
+/// @input in The input array;
+/// @input startIndex The index from which the elements should be 0; assumes `startIndex - 1` to fit in `ceil(log2(maxArrayLen))` bits
 template AssertZeroPadding(maxArrayLen) {
     var bitLength = log2Ceil(maxArrayLen);
     assert(maxArrayLen <= (1 << bitLength));

packages/circuits/utils/bytes.circom

@@ -23,7 +23,7 @@ function computeIntChunkLength(byteLength) {
 /// @title PackBytes
 /// @notice Pack an array of bytes to numbers that fit in the field
 /// @param maxBytes: the maximum number of bytes in the input array
-/// @input in: the input byte array
+/// @input in: the input byte array; assumes elements to be bytes
 /// @output out: the output integer array
 template PackBytes(maxBytes) {
     var packSize = MAX_BYTES_IN_FIELD();
@@ -65,9 +65,9 @@ template PackBytes(maxBytes) {
 /// @notice This is not used in ZK-Email circuits anywhere
 /// @param maxArrayLen: the maximum number of elements in the input array
 /// @param maxSubArrayLen: the maximum number of elements in the sub array
-/// @input in: the input byte array
-/// @input startIndex: the start index of the sub array
-/// @input length: the length of the sub array
+/// @input in: the input byte array; assumes elements to be bytes
+/// @input startIndex: the start index of the sub array; assumes to be a valid index
+/// @input length: the length of the sub array; assumes to fit in `ceil(log2(maxSubArrayLen))` bits
 /// @output out: the output integer array
 template PackByteSubArray(maxArrayLen, maxSubArrayLen) {
     assert(maxSubArrayLen < maxArrayLen);
@@ -96,9 +96,9 @@ template PackByteSubArray(maxArrayLen, maxSubArrayLen) {
 /// @title DigitBytesToInt
 /// @notice Converts a byte array representing digits to an integer
 /// @notice Assumes the output number fits in the field
-/// @param n: the number of bytes in the input array
-/// @input in: the input byte array - big-endtian digit string of `out`
-/// @output out: the output integer
+/// @param n The number of bytes in the input array
+/// @input in The input byte array; assumes elements are between 48 and 57 (ASCII numbers)
+/// @output out The output integer; assumes to fit in the field
 template DigitBytesToInt(n) {
     signal input in[n];
 

packages/circuits/utils/regex.circom

@@ -9,8 +9,8 @@ include "./bytes.circom";
 /// @notice Verifies data before and after (maxRevealLen) reveal part is zero
 /// @param maxArrayLen Maximum length of the input array
 /// @param maxRevealLen Maximum length of the reveal part
-/// @input in Input array
-/// @input startIndex Index of the start of the reveal part
+/// @input in Input array; assumes elements to be bytes
+/// @input startIndex The index of the start of the reveal part; assumes a valid index
 /// @output out Revealed data array
 template SelectRegexReveal(maxArrayLen, maxRevealLen) {
     signal input in[maxArrayLen];
@@ -54,8 +54,8 @@ template SelectRegexReveal(maxArrayLen, maxRevealLen) {
 /// @notice Packs reveal data from a regex match into int[]
 /// @param maxArrayLen Maximum length of the input array
 /// @param maxRevealLen Maximum length of the reveal part
-/// @input in Input array
-/// @input startIndex Index of the start of the reveal part
+/// @input in Input array; assumes elements to be bytes
+/// @input startIndex Index of the start of the reveal part; assumes a valid index
 /// @output out Packed int array
 template PackRegexReveal(maxArrayLen, maxRevealLen) {
     var chunkSize = computeIntChunkLength(maxRevealLen);