docs(bb): add initial cli reference #17244
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,239 @@ | ||||||
| --- | ||||||
| title: Barretenberg CLI Reference | ||||||
| description: Reference for the bb command-line interface, including commands, options, and usage examples. | ||||||
| keywords: [bb, CLI, barretenberg, command line, zero-knowledge proofs, proving, verification] | ||||||
| sidebar_position: 1000000 | ||||||
| --- | ||||||
|
|
||||||
| # Barretenberg CLI Reference | ||||||
|
|
||||||
| [Barretenberg](https://github.com/AztecProtocol/barretenberg) is Aztec's cryptography backend. This page covers `bb`, the command-line interface for Barretenberg. | ||||||
|
|
||||||
| Usage: `bb [OPTIONS] [SUBCOMMAND]` | ||||||
|
|
||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
Not sure exactly where on this page this should go, but early on seems sensible. It's where I'd want to go if I got stuck. |
||||||
| ## Installation | ||||||
|
|
||||||
| To install `bb`, use `bbup`: | ||||||
|
|
||||||
| ```bash | ||||||
| curl -L https://raw.githubusercontent.com/AztecProtocol/aztec-packages/master/barretenberg/bbup/install | bash | ||||||
| bbup | ||||||
| ``` | ||||||
|
|
||||||
|
Contributor
There was a problem hiding this comment. For more bbup commands, see: https://github.com/AztecProtocol/aztec-packages/tree/next/barretenberg/bbup |
||||||
| ## Global options | ||||||
|
|
||||||
| These options can be used with any `bb` command: | ||||||
|
|
||||||
| - `-h, --help` - Print help message and exit. | ||||||
| - `-v, --verbose, --verbose_logging` - Output all logs to stderr. | ||||||
| - `-d, --debug_logging` - Output debug logs to stderr. | ||||||
| - `-c, --crs_path` - Path to Common Reference String (CRS) directory. CRS files will be downloaded automatically as needed. | ||||||
| - `--version` - Prints the version string. | ||||||
|
|
||||||
| ## Subcommands | ||||||
|
Contributor
There was a problem hiding this comment. What's the expected workflow? In what order would a dev typically run these commands? It seems like usage of Noir is implied. What kind of Noir commands do I need to run, in order to generate the files needed for some of the below commands?
Collaborator
There was a problem hiding this comment. I can either help figuring this out, or just handle this ask |
||||||
|
|
||||||
| ### `check` | ||||||
|
|
||||||
| **Usage:** `bb check [OPTIONS]` | ||||||
|
|
||||||
| A debugging tool for checking whether a witness satisfies a circuit. The tool constructs the execution trace and iterates through it row by row, applying the polynomial relations defining the gate types. For client IVC, the tool checks the VKs in the folding stack. | ||||||
|
|
||||||
| #### Options | ||||||
| - `-s, --scheme [BB_SCHEME]` - The type of proof to be constructed. Specifies a proving system, an accumulation scheme, or a type of circuit to be constructed and proven for some implicit scheme. Options: `{client_ivc`, `avm`, `ultra_honk}` | ||||||
| - `-b, --bytecode_path` - Path to ACIR bytecode generated by Noir. | ||||||
| - `-w, --witness_path` - Path to partial witness generated by Noir. | ||||||
| - `--ivc_inputs_path` - For IVC, path to input stack with bytecode and witnesses. | ||||||
|
|
||||||
| #### Example | ||||||
| ```bash | ||||||
| bb check -s ultra_honk -b ./circuit.acir -w ./witness.gz | ||||||
| ``` | ||||||
|
|
||||||
| For common flags like verbosity and help, see [Global options](#global-options). | ||||||
|
|
||||||
| ### `gates` | ||||||
|
|
||||||
| **Usage:** `bb gates [OPTIONS]` | ||||||
|
|
||||||
| Constructs a circuit from the specified bytecode (expanding black-box functions) and returns gate count information. | ||||||
|
|
||||||
| #### Options | ||||||
| - `-s, --scheme [BB_SCHEME]` - The type of proof to be constructed. Specifies a proving system, an accumulation scheme, or a type of circuit to be constructed and proven for some implicit scheme. Options: `{client_ivc`, `avm`, `ultra_honk}` | ||||||
| - `-b, --bytecode_path` - Path to ACIR bytecode generated by Noir. | ||||||
| - `--honk_recursion` - Informs the prover that this circuit will be recursively verified with UltraHonk (`1`) or with UltraRollupHonk (`2`). Ensures that a pairing point accumulator is added to the public inputs of the proof. (For UltraRollupHonk, an IPA claim is also added.) | ||||||
| - `--include_gates_per_opcode` - Adds a detailed `gates_per_opcode` breakdown to the output. | ||||||
|
|
||||||
| For common flags like verbosity and help, see [Global options](#global-options). | ||||||
|
|
||||||
| #### Example | ||||||
| ```bash | ||||||
| bb gates -s ultra_honk -b ./circuit.acir --include_gates_per_opcode | ||||||
|
Contributor
There was a problem hiding this comment. How do I get a circuit.acir file? |
||||||
| ``` | ||||||
|
|
||||||
| ### `prove` | ||||||
|
|
||||||
| Generates a proof. | ||||||
|
|
||||||
| **Usage:** `bb prove [OPTIONS]` | ||||||
|
|
||||||
| #### Options | ||||||
|
|
||||||
| - `-s, --scheme [BB_SCHEME]` - The type of proof to be constructed. Specifies a proving system, an accumulation scheme, or a type of circuit to be constructed and proven for some implicit scheme. Options: `{client_ivc`, `avm`, `ultra_honk}` | ||||||
|
Contributor
There was a problem hiding this comment. Consider making these suboptions a consistent format to others in this list: i.e. an indented list of bullet points.
Collaborator
There was a problem hiding this comment. Any AVM mentions should reference an AVM stub document that explains that for now the AVM is not user-facing and used with our yarn packages, maybe |
||||||
| - `-b, --bytecode_path` - Path to ACIR bytecode generated by Noir. | ||||||
| - `-w, --witness_path` - Path to partial witness generated by Noir. | ||||||
|
Comment on lines
+82
to
+83
Contributor
There was a problem hiding this comment. What kind of files are these? What are their file extensions? What's the default name of the file?
Collaborator
There was a problem hiding this comment. for posterity (possibly for myself if I do a pass):
Witnesses can be
|
||||||
| - `-o, --output_path` - Directory to write to or path of file to write. | ||||||
|
Contributor
There was a problem hiding this comment. Does it just output one file, or can it output multiple files into a directory (depending on the options provided)?
Collaborator
There was a problem hiding this comment. output path is always a directory iirc |
||||||
| - `--ivc_inputs_path` - For IVC, path to input stack with bytecode and witnesses. | ||||||
| - `--oracle_hash` - Hash function used by the prover as a random oracle standing in for a verifier's challenge generation: | ||||||
| - `poseidon2` - For in-circuit verification. | ||||||
| - `keccak` - For Ethereum smart contract verification (uses EVM precompile). | ||||||
| - `starknet` - For Starknet smart contract verification (use with Garaga library). | ||||||
| - `--output_format` - Output data format. Suboptions: | ||||||
| - `bytes` - Raw bytes with header information. | ||||||
| - `fields` - String representation of array of field elements. | ||||||
| - `bytes_and_fields` - Both `bytes` and `fields`. | ||||||
| - `fields_msgpack` - MessagePack buffer of `Fr` elements. | ||||||
| - `--write_vk` - Writes the circuit's verification key. | ||||||
|
Contributor
There was a problem hiding this comment. Does it write it to a separate file? What name does it give the file?
Collaborator
There was a problem hiding this comment. its written to /vk. This is written as 32 byte field chunks, except if using the keccak oracle then it is optimized for solidity consumption |
||||||
| - `--zk` - Uses a zero-knowledge version of the specified `--scheme`, if available. | ||||||
|
Contributor
There was a problem hiding this comment. Does it throw if not available? Hopefully it does.
Collaborator
There was a problem hiding this comment. I'm not actually sure what 'if available' means here, but there's some combinations that don't make sense and likely should error out. the most problematic right now is --ipa_accumulation that single handedly makes other options ignored and is the bundle of rollup defaults. that one is awkward |
||||||
| - `--init_kzg_accumulator` - Initializes pairing point accumulator. | ||||||
| - `--ipa_accumulation` - Accumulates/aggregates Inner Product Argument (IPA) claims. | ||||||
| - `--recursive` - Enables recursive verification and KZG features. | ||||||
| - `--honk_recursion` - Informs the prover that this circuit will be recursively verified with UltraHonk (`1`) or with UltraRollupHonk (`2`). Ensures that a pairing point accumulator is added to the public inputs of the proof. (For UltraRollupHonk, an IPA claim is also added.) | ||||||
| - `--verify` - Verifies the proof after generation (useful for testing). | ||||||
|
|
||||||
| For common flags like verbosity and help, see [Global options](#global-options). | ||||||
|
|
||||||
| #### Example | ||||||
| ```bash | ||||||
| bb prove -s ultra_honk -b ./circuit.acir -w ./witness.gz -o ./proof | ||||||
|
Contributor
There was a problem hiding this comment. How do I get a circuit.acir and witness.gz file? |
||||||
| ``` | ||||||
|
|
||||||
| ### `verify` | ||||||
|
|
||||||
| Verifies a proof. | ||||||
|
|
||||||
| **Usage:** `bb verify [OPTIONS]` | ||||||
|
|
||||||
| #### Options | ||||||
| - `-i, --public_inputs_path` - Path to public inputs. | ||||||
| - `-p, --proof_path` - Path to a proof. | ||||||
| - `-k, --vk_path` - Path to a verification key. | ||||||
| - `-s, --scheme [BB_SCHEME]` - The type of proof to be constructed. Specifies a proving system, an accumulation scheme, or a type of circuit to be constructed and proven for some implicit scheme. Options: `{client_ivc`, `avm`, `ultra_honk}` | ||||||
| - `--oracle_hash` - Hash function used by the prover as a random oracle standing in for a verifier's challenge generation: | ||||||
| - `poseidon2` - For in-circuit verification. | ||||||
| - `keccak` - For Ethereum smart contract verification (uses EVM precompile). | ||||||
| - `starknet` - For Starknet smart contract verification (use with Garaga library). | ||||||
| - `--zk` - Uses a zero-knowledge version of the specified `--scheme`, if available. | ||||||
| - `--ipa_accumulation` - Accumulates/aggregates Inner Product Argument (IPA) claims. | ||||||
|
Contributor
There was a problem hiding this comment. Probably needs a more detailed explanation of what this means |
||||||
| - `--init_kzg_accumulator` - Initializes pairing point accumulator. | ||||||
|
Contributor
There was a problem hiding this comment. Probably needs a more detailed explanation of what this means
Collaborator
There was a problem hiding this comment. This is probably best explained in use cases and show the prover and verifier commands for both use cases. the AVM and starknet use cases should explain that one is beyond scope, another is in experimental dev and not turned on by default |
||||||
| - `--honk_recursion` - Informs the prover that this circuit will be recursively verified with UltraHonk (`1`) or with UltraRollupHonk (`2`). Ensures that a pairing point accumulator is added to the public inputs of the proof. (For UltraRollupHonk, an IPA claim is also added.) | ||||||
| - `--recursive` - Enables recursive verification and KZG features. | ||||||
|
Contributor
There was a problem hiding this comment. I'm not sure what this means
Collaborator
There was a problem hiding this comment. Recursive and honk recursion shouldnt be a part of --help, I wonder how this got picked up? I nuked them, quite confused how they got into the source material or prompt or whatever |
||||||
|
|
||||||
| For common flags like verbosity and help, see [Global options](#global-options). | ||||||
|
|
||||||
| #### Example | ||||||
| ```bash | ||||||
| bb verify -s ultra_honk -p ./proof -k ./vk -i ./public_inputs | ||||||
|
Contributor
There was a problem hiding this comment. Where do the proof and public_inputs come from? Are they directories or files without a file extension? What's inside those directories? |
||||||
| ``` | ||||||
|
|
||||||
| ### `write_vk` | ||||||
|
|
||||||
| Writes the verification key of a circuit. This command uses dummy witness data to expand ACIR black-box opcodes (no proof constructed). | ||||||
|
|
||||||
| **Usage:** `bb write_vk [OPTIONS]` | ||||||
|
|
||||||
| #### Options | ||||||
|
|
||||||
| - `-s, --scheme [BB_SCHEME]` - The type of proof to be constructed. Specifies a proving system, an accumulation scheme, or a type of circuit to be constructed and proven for some implicit scheme. Options: `{client_ivc`, `avm`, `ultra_honk}` | ||||||
| - `-b, --bytecode_path` - Path to ACIR bytecode generated by Noir. | ||||||
| - `-o, --output_path` - Directory to write to. | ||||||
| - `--ivc_inputs_path` - For IVC, path to input stack with bytecode and witnesses. | ||||||
| - `--output_format` - Output data format. Options: | ||||||
| - `bytes` - Raw bytes with header information. | ||||||
| - `fields` - String representation of array of field elements. | ||||||
| - `bytes_and_fields` - Both `bytes` and `fields`. | ||||||
| - `fields_msgpack` - MessagePack buffer of `Fr` elements. | ||||||
| - `--init_kzg_accumulator` - Initializes pairing point accumulator. | ||||||
| - `--oracle_hash` - Hash function used by the prover as a random oracle standing in for a verifier's challenge generation: | ||||||
| - `poseidon2` - For in-circuit verification. | ||||||
| - `keccak` - For Ethereum smart contract verification (uses EVM precompile). | ||||||
| - `starknet` - For Starknet smart contract verification (use with Garaga library). | ||||||
| - `--ipa_accumulation` - Accumulates/aggregates Inner Product Argument (IPA) claims. | ||||||
| - `--honk_recursion` - Informs the prover that this circuit will be recursively verified with UltraHonk (`1`) or with UltraRollupHonk (`2`). Ensures that a pairing point accumulator is added to the public inputs of the proof. (For UltraRollupHonk, an IPA claim is also added.) | ||||||
| - `--recursive` - Enables recursive verification and KZG features. | ||||||
| - `--verifier_type` - Indicates the type of verifier to use with this verification key: | ||||||
| - `standalone` - For standalone single circuits (for example, a SNARK or folding recursive verifier), including cases where an IVC scheme is manually constructed via recursive UltraHonk proof verification. | ||||||
| - `ivc` - For verifying the stack of run through a dedicated IVC verifier (currently, only ClientIVC is supported). | ||||||
|
|
||||||
| For common flags like verbosity and help, see [Global options](#global-options). | ||||||
|
|
||||||
| #### Example | ||||||
| ```bash | ||||||
| bb write_vk -s ultra_honk -b ./circuit.acir -o ./vk | ||||||
| ``` | ||||||
| ### `write_solidity_verifier` | ||||||
| Generates a Solidity verifier contract for proofs of circuit satisfiability. Due to gas efficiency constraints, not all hash types are supported. | ||||||
|
|
||||||
| **Usage:** `bb write_solidity_verifier [OPTIONS]` | ||||||
|
|
||||||
| #### Options | ||||||
| - `-s, --scheme [BB_SCHEME]` - The type of proof to be constructed. Specifies a proving system, an accumulation scheme, or a type of circuit to be constructed and proven for some implicit scheme. Options: `{client_ivc`, `avm`, `ultra_honk}` | ||||||
| - `-k, --vk_path` - Path to the verification key for the circuit to be verified. | ||||||
| - `-o, --output_path` - Directory to write to or path of file to write. | ||||||
| - `--zk` - Uses a zero-knowledge version of the specified `--scheme`, if available. | ||||||
|
|
||||||
| For common flags like verbosity and help, see [Global options](#global-options). | ||||||
|
|
||||||
| #### Example | ||||||
| ```bash | ||||||
| bb write_solidity_verifier -s ultra_honk -k ./vk -o ./Verifier.sol | ||||||
| ``` | ||||||
|
|
||||||
| ## OLD_API commands | ||||||
|
|
||||||
| These legacy commands are maintained for backward compatibility. | ||||||
|
|
||||||
| ### `OLD_API gates_for_ivc` | ||||||
|
|
||||||
| #### Options | ||||||
| - `-b, --bytecode_path` - Path to ACIR bytecode generated by Noir. | ||||||
|
|
||||||
| ### `OLD_API gates_mega_honk` | ||||||
|
|
||||||
| #### Options | ||||||
| - `-b, --bytecode_path` - Path to ACIR bytecode generated by Noir. | ||||||
| - `--recursive` - Enables recursive verification features. | ||||||
| - `--honk_recursion` - Sets recursion type: UltraHonk (`1`) or UltraRollupHonk (`2`). | ||||||
|
|
||||||
| ### `OLD_API write_arbitrary_valid_client_ivc_proof_and_vk_to_file` | ||||||
|
|
||||||
| #### Options | ||||||
| - `-o, --output_path` - Path of file to write. | ||||||
|
|
||||||
| ### `bb OLD_API write_recursion_inputs_ultra_honk` | ||||||
|
|
||||||
| #### Options | ||||||
| - `-b, --bytecode_path` - Path to ACIR bytecode generated by Noir. | ||||||
| - `-o, --output_path` - Directory to write to. | ||||||
| - `--ipa_accumulation` - Accumulates/aggregates Inner Product Argument (IPA) claims. | ||||||
| - `--recursive` - Enables recursive verification features. | ||||||
|
|
||||||
| ### `bb OLD_API gates` | ||||||
|
|
||||||
| #### Options | ||||||
| - `-b, --bytecode_path` - Path to ACIR bytecode generated by Noir. | ||||||
| - `--recursive` - Enables recursive verification features. | ||||||
| - `--honk_recursion` - Sets recursion type: UltraHonk (`1`) or UltraRollupHonk (`2`). | ||||||
|
|
||||||
| ### `bb OLD_API verify` | ||||||
|
|
||||||
| #### Options | ||||||
| - `-b, --bytecode_path` - Path to ACIR bytecode generated by Noir. | ||||||
| - `-p, --proof_path` - Path to a proof. | ||||||
| - `-k, --vk_path` - Path to a verification key. | ||||||
| - `--recursive` - Enables recursive verification features. | ||||||
|
|
||||||
| ### `bb OLD_API prove_and_verify` | ||||||
|
|
||||||
| #### Options | ||||||
| - `-b, --bytecode_path` - Path to ACIR bytecode generated by Noir. | ||||||
| - `--recursive` - Enables recursive verification features. | ||||||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I was going to suggest perhaps this could live in a section within the barretenberg readme: https://github.com/AztecProtocol/aztec-packages/blob/master/barretenberg/README.md#usage <-- that's the master branch, and you can see an incomplete "usage" section.
But then I switched to the
nextbranch (which is where development happens) and there is no "Usage" section anymore https://github.com/AztecProtocol/aztec-packages/blob/next/barretenberg/README.md. Not sure what the team's plan is.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Our team has not paid enough attention here; I'm willing to spend some time here. Thanks for the suggestions Mike