github/darkfi
1
1
Fork 0
mirror of https://github.com/darkrenaissance/darkfi.git synced 2026-04-28 03:00:18 -04:00
Code Issues Packages Projects Releases Wiki Activity

book/zkas/bincode: Add magic bytes and remove STACK_INDEX from .contract

Browse Source
This commit is contained in:
parazyd
2022-01-07 14:00:51 +01:00
parent 9d898b507f
commit cf02fd2f4e
1 changed files with 48 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

75
book/src/zkas/bincode.md
View File

@@ -1,50 +1,68 @@
Bincode
=======
zkas bincode
============
The bincode design for zkas is the compiled code in the form of a
binary blob, that can be read by a program and fed into the VM.
Our programs consist of three sections: `constant`, `contract`, and
`circuit`. Our bincode represents the same. Additionally, there is an
optional section called `.debug` which can hold debug info related to
the binary.
`circuit`. Our bincode represents the same. Additionally, there is
an optional section called `.debug` which can hold debug info related
to the binary.
We currently keep everything on the same stack, so we avoid having to
deal with different types. Instead, we rely that the compiler does a
proper parse and analysis of the source code, so we are sure that in
the VM, when referenced, the types shall be correct.
deal with different types. Instead, we rely that the compiler does
a proper parse and analysis of the source code, so we are sure that
in the VM, when referenced, the types shall be correct.
The compiled binary blob has the following layout:
```
MAGIC_BYTES
.constant
CONSTANT_TYPE STACK_INDEX CONSTANT_NAME
CONSTANT_TYPE STACK_INDEX CONSTANT_NAME
...
.contract
WITNESS_TYPE STACK_INDEX
WITNESS_TYPE STACK_INDEX
WITNESS_TYPE
WITNESS_TYPE
...
.circuit
STATEMENT_TYPE OPCODE ARG_NUM STACK_INDEX ... STACK_INDEX
STATEMENT_TYPE OPCODE ARG_NUM STACK_INDEX ... STACK_INDEX
OPCODE ARG_NUM STACK_INDEX ... STACK_INDEX
OPCODE ARG_NUM STACK_INDEX ... STACK_INDEX
...
.debug
TBD
```
## `MAGIC_BYTES`
The magic bytes are the file signature consisting of four bytes used
to identify the zkas binary code. It also contains the binary version
to allow parsing potential different formats in the future.
They consist of:
> `0xf3` `0x42` `0x69` `BINARY_VERSION`
Where binary version is the byte representing the format version.
## `.constant`
The constants in the `.constant` section are declared with their type
stack index, and name, so that the VM knows how to search for the
builtin constant and add it to the stack.
The constants in the `.constant` section are declared with their
type stack index, and name, so that the VM knows how to search for
the builtin constant and add it to the stack.
## `.contract`
The `.contract` section holds the circuit witness values in the form
of `WITNESS_TYPE` and `STACK_INDEX`. The witnesses that are of the same
type as the circuit itself (typically `Base`) will be loaded into the
circuit as _private values_ using the Halo2 `load_private` API.
of `WITNESS_TYPE`. Their stack index is incremented for each witness
as they're kept in order like in the source file. The witnesses
that are of the same type as the circuit itself (typically `Base`)
will be loaded into the circuit as _private values_ using the Halo2
`load_private` API.
## `.circuit`
@@ -53,19 +71,22 @@ In here we have statements with opcodes that are executed as
understood by the VM. The statements are in the form of:
```
STATEMENT_TYPE OPCODE ARG_NUM STACK_INDEX ... STACK_INDEX
OPCODE ARG_NUM STACK_INDEX ... STACK_INDEX
```
where:
* `STATEMENT_TYPE` - Where we currently support an assignment, and a
call without an assignment.
* `OPCODE` - The opcode we wish to execute
* `ARG_NUM` - The number of arguments given to this opcode.
(Note, the VM should be checking the correctness of this as well
before executing the opcode)
* `STACK_INDEX` - The location of the argument on the stack. This is
supposed to be repeated `ARG_NUM` times.
| Element | Description |
|---------------|------------------------------------------------------------------|
| `OPCODE` | The opcode we wish to execute |
| `ARG_NUM` | The number of arguments given to this opcode |
| | (Note the VM should be checking the correctness of this as well) |
| `STACK_INDEX` | The location of the argument on the stack. |
| | (This is supposed to be repeated `ARG_NUM` times) |
In case an opcode has a return value, the value shall be pushed to
the stack and become available for later references.
## `.debug`