|
|
# Binary format for R1CS
---eip:title: r1cs binary formatauthor: Jordi Baylina <jordi@baylina.cat>discussions-to:status: drafttype: Standards Trackcategory: ERCcreated: 2019-09-24requires:---
## Simple Summary
This standard defines a standard format for a binery representation of a r1cs constraint system.
## Abstract
## Motivation
The zero knowledge primitives, requires the definition of a statment that wants to be proved. This statment can be expressed as a deterministric program or an algebraic circuit. Lots of primitives like zkSnarks, bulletProofs or aurora, requires to convert this statment to a rank-one constraint system.
This standard specifies a format for a r1cs and allows the to connect a set of tools that compiles a program or a circuit to r1cs that can be used for the zksnarks or bulletproofs primitives.
## Specification
### General considerations
All integers are represented in Little Endian Fix size format
The standard extension is `.r1cs`
The constraint is in the form
$$\left\{ \begin{array}{rclclcl}(a_{0,0}s_0 + a_{0,1}s_1 + ... + a_{0,n-1}s_{n-1}) &\cdot& (b_{0,0} s_0 + b_{0,1} s_1 + ... + b_{0,n-1} s_{n-1}) &-& (c_{0,0} s_0 + c_{0,1} s_1 + ... + c_{0,n-1}s_{n-1}) &=& 0 \\(a_{1,0}s_0 + a_{1,1}s_1 + ... + a_{1,n-1}s_{n-1}) &\cdot& (b_{1,0} s_0 + b_{1,1} s_1 + ... + b_{1,n-1} s_{n-1}) &-& (c_{1,0} s_0 + c_{1,1}s_1 + ... + c_{1,n-1}s_{n-1}) &=& 0 \\...\\(a_{m-1,0}s_0 + a_{m-1,1}s_1 + ... + a_{m-1,n-1}s_{n-1}) &\cdot& (b_{m-1,0} s_0 + b_{m-1,1} s_1 + ... + b_{m-1,n-1} s_{n-1}) &-& (c_{m-1,0} s_0 + c_{m-1,1}s_1 + ... + c_{m-1,n-1}s_{n-1}) &=& 0 \end{array} \right.$$
### Format
````
┏━━━━┳━━━━━━━━━━━━━━━━━┓ ┃ 4 │ 72 31 63 73 ┃ Magic "r1cs" ┗━━━━┻━━━━━━━━━━━━━━━━━┛ ┏━━━━┳━━━━━━━━━━━━━━━━━┓ ┃ 4 │ 01 00 00 00 ┃ Version 1 ┗━━━━┻━━━━━━━━━━━━━━━━━┛
┏━━━━┳━━━━━━━━━━━━━━━━━┓ ┃ 4 │ nW ┃ ┗━━━━┻━━━━━━━━━━━━━━━━━┛
┏━━━━┳━━━━━━━━━━━━━━━━━┓ ┃ nW │ 01 00 00 00 ┃ nWires ┗━━━━┻━━━━━━━━━━━━━━━━━┛ ┏━━━━┳━━━━━━━━━━━━━━━━━┓ ┃ nW │ 01 00 00 00 ┃ nPubOut ┗━━━━┻━━━━━━━━━━━━━━━━━┛ ┏━━━━┳━━━━━━━━━━━━━━━━━┓ ┃ nW │ 01 00 00 00 ┃ nPubIn ┗━━━━┻━━━━━━━━━━━━━━━━━┛ ┏━━━━┳━━━━━━━━━━━━━━━━━┓ ┃ nW │ 01 00 00 00 ┃ nPrvIn ┗━━━━┻━━━━━━━━━━━━━━━━━┛
┏━━━━┳━━━━━━━━━━━━━━━━━┓ ┃ nW │m := NConstraints┃ ┗━━━━┻━━━━━━━━━━━━━━━━━┛
┏━━━━┳━━━━━━━━━━━━━━━━━┓ ╲ ┃ nW │ nA ┃ ╲ ┣━━━━╋━━━━━━━━━━━━━━━━━╋━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓ ╲ ┃ nW │ idx_1 ┃ V │ a_{0,idx_1} ┃ │ ┣━━━━╋━━━━━━━━━━━━━━━━━╋━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━┫ │ ┃ nW │ idx_2 ┃ V │ a_{0,idx_2} ┃ │ ┗━━━━┻━━━━━━━━━━━━━━━━━┻━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━┛ │ ... ... │ ┏━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓ │ ┃ nW │ idx_nA ┃ V │ a_{0,idx_nA} ┃ │ ┗━━━━┻━━━━━━━━━━━━━━━━━┻━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━┛ │ ┏━━━━┳━━━━━━━━━━━━━━━━━┓ │ ┃ nW │ nB ┃ │ ┣━━━━╋━━━━━━━━━━━━━━━━━╋━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓ │ ┃ nW │ idx_1 ┃ V │ b_{0,idx_1} ┃ │ ┣━━━━╋━━━━━━━━━━━━━━━━━╋━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━┫ ╲ ┃ nW │ idx_2 ┃ V │ b_{0,idx_2} ┃ ╲ ┗━━━━┻━━━━━━━━━━━━━━━━━┻━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━┛ ╱ Constraint_0 ... ... ╱ ┏━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓ │ ┃ nW │ idx_nB ┃ V │ b_{0,idx_nB} ┃ │ ┗━━━━┻━━━━━━━━━━━━━━━━━┻━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━┛ │ ┏━━━━┳━━━━━━━━━━━━━━━━━┓ │ ┃ nW │ nC ┃ │ ┣━━━━╋━━━━━━━━━━━━━━━━━╋━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓ │ ┃ nW │ idx_1 ┃ V │ c_{0,idx_1} ┃ │ ┣━━━━╋━━━━━━━━━━━━━━━━━╋━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━┫ │ ┃ nW │ idx_2 ┃ V │ c_{0,idx_2} ┃ │ ┗━━━━┻━━━━━━━━━━━━━━━━━┻━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━┛ │ ... ... │ ┏━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓ │ ┃ nW │ idx_nB ┃ V │ c_{0,idx_nC} ┃ ╱ ┗━━━━┻━━━━━━━━━━━━━━━━━┻━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━┛ ╱ ╱
┏━━━━┳━━━━━━━━━━━━━━━━━┓ ╲ ┃ nW │ nA ┃ ╲ ┣━━━━╋━━━━━━━━━━━━━━━━━╋━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓ ╲ ┃ nW │ idx_1 ┃ V │ a_{1,idx_1} ┃ │ ┣━━━━╋━━━━━━━━━━━━━━━━━╋━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━┫ │ ┃ nW │ idx_2 ┃ V │ a_{1,idx_2} ┃ │ ┗━━━━┻━━━━━━━━━━━━━━━━━┻━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━┛ │ ... ... │ ┏━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓ │ ┃ nW │ idx_nA ┃ V │ a_{1,idx_nA} ┃ │ ┗━━━━┻━━━━━━━━━━━━━━━━━┻━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━┛ │ ┏━━━━┳━━━━━━━━━━━━━━━━━┓ │ ┃ nW │ nB ┃ │ ┣━━━━╋━━━━━━━━━━━━━━━━━╋━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓ │ ┃ nW │ idx_1 ┃ V │ b_{1,idx_1} ┃ │ ┣━━━━╋━━━━━━━━━━━━━━━━━╋━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━┫ ╲ ┃ nW │ idx_2 ┃ V │ b_{1,idx_2} ┃ ╲ ┗━━━━┻━━━━━━━━━━━━━━━━━┻━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━┛ ╱ Constraint_1 ... ... ╱ ┏━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓ │ ┃ nW │ idx_nB ┃ V │ b_{1,idx_nB} ┃ │ ┗━━━━┻━━━━━━━━━━━━━━━━━┻━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━┛ │ ┏━━━━┳━━━━━━━━━━━━━━━━━┓ │ ┃ nW │ nC ┃ │ ┣━━━━╋━━━━━━━━━━━━━━━━━╋━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓ │ ┃ nW │ idx_1 ┃ V │ c_{1,idx_1} ┃ │ ┣━━━━╋━━━━━━━━━━━━━━━━━╋━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━┫ │ ┃ nW │ idx_2 ┃ V │ c_{1,idx_2} ┃ │ ┗━━━━┻━━━━━━━━━━━━━━━━━┻━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━┛ │ ... ... │ ┏━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓ │ ┃ nW │ idx_nB ┃ V │ c_{1,idx_nC} ┃ ╱ ┗━━━━┻━━━━━━━━━━━━━━━━━┻━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━┛ ╱ ╱
... ... ...
┏━━━━┳━━━━━━━━━━━━━━━━━┓ ╲ ┃ nW │ nA ┃ ╲ ┣━━━━╋━━━━━━━━━━━━━━━━━╋━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓ ╲ ┃ nW │ idx_1 ┃ V │ a_{m-1,idx_1} ┃ │ ┣━━━━╋━━━━━━━━━━━━━━━━━╋━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━┫ │ ┃ nW │ idx_2 ┃ V │ a_{m-1,idx_2} ┃ │ ┗━━━━┻━━━━━━━━━━━━━━━━━┻━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━┛ │ ... ... │ ┏━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓ │ ┃ nW │ idx_nA ┃ V │ a_{m-1,idx_nA} ┃ │ ┗━━━━┻━━━━━━━━━━━━━━━━━┻━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━┛ │ ┏━━━━┳━━━━━━━━━━━━━━━━━┓ │ ┃ nW │ nB ┃ │ ┣━━━━╋━━━━━━━━━━━━━━━━━╋━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓ │ ┃ nW │ idx_1 ┃ V │ b_{m-1,idx_1} ┃ │ ┣━━━━╋━━━━━━━━━━━━━━━━━╋━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━┫ ╲ ┃ nW │ idx_2 ┃ V │ b_{m-1,idx_2} ┃ ╲ ┗━━━━┻━━━━━━━━━━━━━━━━━┻━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━┛ ╱ Constraint_{m-1} ... ... ╱ ┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓ │ ┃ nW idx_nB ┃ V │ b_{m-1,idx_nB} ┃ │ ┗━━━━━━━━━━━━━━━━━━━━━━┻━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━┛ │ ┏━━━━┳━━━━━━━━━━━━━━━━━┓ │ ┃ nW │ nC ┃ │ ┣━━━━╋━━━━━━━━━━━━━━━━━╋━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓ │ ┃ nW │ idx_1 ┃ V │ c_{m-1,idx_1} ┃ │ ┣━━━━╋━━━━━━━━━━━━━━━━━╋━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━┫ │ ┃ nW │ idx_2 ┃ V │ c_{m-1,idx_2} ┃ │ ┗━━━━┻━━━━━━━━━━━━━━━━━┻━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━┛ │ ... ... │ ┏━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┓ │ ┃ nW │ idx_nB ┃ V │ c_{m-1,idx_nC} ┃ ╱ ┗━━━━┻━━━━━━━━━━━━━━━━━┻━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━┛ ╱ ╱ ╱````
### Magic Number
Size: 4 bytesThe file start with a constant 4 byts (magic number) "r1cs"
```0x72 0x31 0x63 0x73```
### Version
Size: 4 bytesFormat: Little-Endian
For this standard it's fixed to
```0x01 0x00 0x00 0x00```
### Word With (nW)
Size: 4 bytesFormat: Little-Endian
This is the standard word size in bytes used to specify lenghts and indexes in the file.
The format of this field is little endian.
In most of the cases this will be 4 (32bit values)
Example:```0x04 0x00 0x00 0x00```
### Number of wires
Size: nW bytesFormat: Little-Endian
Total Number of wires including ONE signal (Index 0).
### Number of public outputs
Size: nW bytesFormat: Little-Endian
Total Number of wires public output wires. They should be starting at idx 1
### Number of public inputs
Size: nW bytesFormat: Little-Endian
Total Number of wires public input wires. They should be starting just after the public output
### Number of private inputs
Size: nW bytesFormat: Little-Endian
Total Number of wires private input wires. They should be starting just after the public inputs
### Number of constraints
Size: nW bytesFormat: Little-Endian
Total Number of constraints
### Constraints
Each constraint contains 3 linear combinations A, B, C.
The constraint is such that:```A*B-C = 0```
### Linear combination
Each linear combination is of the form:
$$a_{0,0}s_0 + a_{0,1}s_1 + ... + a_{0,n-1}s_{n-1}$$
### Number of nonZero Factors
Size: nW bytesFormat: Little-Endian
Total number of non Zero factors in the linear compination.
The factors MUST be sorted in ascending order.
### Factor
For each factor we have the index of the factor and the value of the factor.
### Index of the factor
Size: nW bytesFormat: Little-Endian
Index of the nonZero Factor
### Value of the factor
The first byte indicate the length N in bytes of the number in the upcoming bytes.
The next N bytes represent the value in Little Endian format.
For example, to represent the linear combination:
$$5s_4 +8s_5 + 260s_886$$
The linear combination would be represented as:
```` ┏━━━━━━━━━━━━━━━━━┓ ┃ 03 00 00 00 ┃ ┣━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━┓ ┃ 04 00 00 00 ┃ 01 05 ┃ ┣━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━┫ ┃ 05 00 00 00 ┃ 01 08 ┃ ┣━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━┫ ┃ 76 03 00 00 ┃ 02 04 01 ┃ ┗━━━━━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━━━┛````## Rationale
Variable size for field elements allows to shrink the size of the file and allows to work with any field.
Version allows to update the format.
Have a very good comprasion ratio for sparse r1cs as it's the normal case.
## Backward Compatibility
N.A.
## Test Cases
### Example
Given this r1cs in a 256 bit Field:
$$\left\{ \begin{array}{rclclcl}(3s_5 + 8s_6) &\cdot& (2s_0 + 20s_2 + 12s_3) &-& (5s_0 + 7s_9) &=& 0 \\(4s_1 + 8s_5 + 3s_9) &\cdot& (6s_6 + 44s_3) && &=& 0 \\(4s_6) &\cdot& (6s_0 + 5s_3 + 11s_9) &-& (600s_700) &=& 0\end{array} \right.$$
The format will be:
````
┏━━━━━━━━━━━━━━┓ ┃ 72 31 63 77 ┃ Magic ┣━━━━━━━━━━━━━━┫ ┃ 01 00 00 00 ┃ Version ┣━━━━━━━━━━━━━━┫ ┃ 04 00 00 00 ┃ nW ┣━━━━━━━━━━━━━━┫ ┃ 04 23 45 00 ┃ # of wires ┣━━━━━━━━━━━━━━┫ ┃ 01 00 00 00 ┃ # Public Outs ┣━━━━━━━━━━━━━━┫ ┃ 02 00 00 00 ┃ # Public Ins ┣━━━━━━━━━━━━━━┫ ┃ 05 00 00 00 ┃ # Private Ins ┗━━━━━━━━━━━━━━┛
┏━━━━━━━━━━━━━━┓ ┃ 03 00 00 00 ┃ # of constraints ┗━━━━━━━━━━━━━━┛
┏━━━━━━━━━━━━━━┓ Constraint 0: (3s_5 + 8s_6) * (2s_0 + 20s_2 + 12s_3) - (5s_0 + 7s_9) = 0 ┃ 02 00 00 00 ┃ ┣━━━━━━━━━━━━━━╋━━━━━━━━┓ ┃ 05 00 00 00 ┃ 01 03 ┃ ┣━━━━━━━━━━━━━━╋━━━━━━━━┫ ┃ 06 00 00 00 ┃ 01 08 ┃ ┗━━━━━━━━━━━━━━┻━━━━━━━━┛ ┏━━━━━━━━━━━━━━┓ ┃ 03 00 00 00 ┃ ┣━━━━━━━━━━━━━━╋━━━━━━━━┓ ┃ 00 00 00 00 ┃ 01 02 ┃ ┣━━━━━━━━━━━━━━╋━━━━━━━━┫ ┃ 02 00 00 00 ┃ 01 14 ┃ ┣━━━━━━━━━━━━━━╋━━━━━━━━┫ ┃ 03 00 00 00 ┃ 01 0C ┃ ┗━━━━━━━━━━━━━━┻━━━━━━━━┛ ┏━━━━━━━━━━━━━━┓ ┃ 02 00 00 00 ┃ ┣━━━━━━━━━━━━━━╋━━━━━━━━┓ ┃ 00 00 00 00 ┃ 01 05 ┃ ┣━━━━━━━━━━━━━━╋━━━━━━━━┫ ┃ 09 00 00 00 ┃ 01 07 ┃ ┗━━━━━━━━━━━━━━┻━━━━━━━━┛
┏━━━━━━━━━━━━━━┓ Constraint 1: (4s_1 + 8s_5 + 3s_9) * (6s_6 + 44s_3) = 0 ┃ 03 00 00 00 ┃ ┣━━━━━━━━━━━━━━╋━━━━━━━━━┓ ┃ 01 00 00 00 ┃ 01 04 ┃ ┣━━━━━━━━━━━━━━╋━━━━━━━━━┫ ┃ 05 00 00 00 ┃ 01 08 ┃ ┣━━━━━━━━━━━━━━╋━━━━━━━━━┫ ┃ 09 00 00 00 ┃ 01 03 ┃ ┗━━━━━━━━━━━━━━┻━━━━━━━━━┛ ┏━━━━━━━━━━━━━━┓ ┃ 02 00 00 00 ┃ ┣━━━━━━━━━━━━━━╋━━━━━━━━━┓ ┃ 03 00 00 00 ┃ 01 2C ┃ ┣━━━━━━━━━━━━━━╋━━━━━━━━━┫ ┃ 06 00 00 00 ┃ 01 06 ┃ ┗━━━━━━━━━━━━━━┻━━━━━━━━━┛ ┏━━━━━━━━━━━━━━┓ ┃ 00 00 00 00 ┃ ┗━━━━━━━━━━━━━━┛
┏━━━━━━━━━━━━━━┓ Constraint 2: (4s_6) * (6s_0 + 5s_3 + 11s_9) - (600s_700) = 0 ┃ 01 00 00 00 ┃ ┣━━━━━━━━━━━━━━╋━━━━━━━━━┓ ┃ 06 00 00 00 ┃ 01 04 ┃ ┗━━━━━━━━━━━━━━┻━━━━━━━━━┛ ┏━━━━━━━━━━━━━━┓ ┃ 03 00 00 00 ┃ ┣━━━━━━━━━━━━━━╋━━━━━━━━━┓ ┃ 00 00 00 00 ┃ 01 06 ┃ ┣━━━━━━━━━━━━━━╋━━━━━━━━━┫ ┃ 03 00 00 00 ┃ 01 05 ┃ ┣━━━━━━━━━━━━━━╋━━━━━━━━━┫ ┃ 09 00 00 00 ┃ 01 0B ┃ ┗━━━━━━━━━━━━━━┻━━━━━━━━━┛ ┏━━━━━━━━━━━━━━┓ ┃ 01 00 00 00 ┃ ┣━━━━━━━━━━━━━━╋━━━━━━━━━━━━━┓ ┃ BC 02 00 00 ┃ 02 58 02 ┃ ┗━━━━━━━━━━━━━━┻━━━━━━━━━━━━━┛````
And the binary representation in Hex:
````72 31 63 7701 00 00 0004 00 00 0004 23 45 0001 00 00 0002 00 00 0005 00 00 0003 00 00 0002 00 00 0005 00 00 00 01 0306 00 00 00 01 0803 00 00 0000 00 00 00 01 0202 00 00 00 01 1403 00 00 00 01 0C02 00 00 0000 00 00 00 01 0509 00 00 00 01 0703 00 00 0001 00 00 00 01 0405 00 00 00 01 0809 00 00 00 01 0302 00 00 0003 00 00 00 01 2C06 00 00 00 01 0600 00 00 0001 00 00 0006 00 00 00 01 0403 00 00 0000 00 00 00 01 0603 00 00 00 01 0509 00 00 00 01 0B01 00 00 00BC 02 00 00 02 58 02````
## Implementation
circom will output this format.
## Copyright
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
|
