`ZkScriptBuilder` (Class)¶

A staged builder for RISC Zero zk-to-script locking scripts.

Build flow

ZkScriptBuilder.new_r0(...) — unbounded.
commit_to_groth16(image_id) or commit_to_succinct(image_id, control_id, hash_fn_id=None) — bounded.
finalize_with_groth16_proof(receipt, journal_hash) or finalize_with_succinct_proof(receipt, journal) — a FinalizedR0Script.

Calling a method in the wrong state raises ZkError. The lower-level fragment methods (add_data, push_*, append_*) operate on the builder in any state, for composing scripts by hand.

repr ¶

__repr__() -> str

The detailed string representation.

RETURNS	DESCRIPTION
`str`	The ZkScriptBuilder as a repr string. TYPE: `str`

add_data ¶

add_data(data: Binary) -> None

Push raw data (canonical encoding) onto the builder.

Use this to push the caller-owned journal / journal hash or a redeem script when composing a script from fragments.

PARAMETER	DESCRIPTION
`data`	Data bytes as hex, bytes, or list of ints. TYPE: `Binary`

RAISES	DESCRIPTION
`ZkError`	If the data cannot be added (or the builder is consumed).

append_r0_groth16_verifier ¶

append_r0_groth16_verifier(image_id: Binary) -> None

Append the r0-over-groth16 verifier fragment for the given 32-byte image id. Expects [..., journal_hash, compressed_proof] on the stack.

PARAMETER	DESCRIPTION
`image_id`	The 32-byte RISC Zero image id, as hex, bytes, or list. TYPE: `Binary`

RAISES	DESCRIPTION
`ZkError`	If `image_id` is malformed or the fragment cannot be appended.

append_r0_groth16_verifier_with_fixed_journal ¶

append_r0_groth16_verifier_with_fixed_journal(image_id: Binary, journal_hash: Binary) -> None

Append a fixed-journal r0-over-groth16 verifier fragment, binding verification to journal_hash baked into the script. Expects only [..., compressed_proof] on the stack.

PARAMETER	DESCRIPTION
`image_id`	The 32-byte RISC Zero image id, as hex, bytes, or list. TYPE: `Binary`
`journal_hash`	The 32-byte journal hash, as hex, bytes, or list. TYPE: `Binary`

RAISES	DESCRIPTION
`ZkError`	If an argument is malformed or the fragment cannot be appended.

append_r0_succinct_verifier ¶

append_r0_succinct_verifier(image_id: Binary, control_id: Binary, hash_fn_id: Optional[str] = None) -> None

Append the r0 succinct verifier fragment for the given image id, control id and hash function. Expects [..., claim, control_index, control_digests, seal, journal].

PARAMETER	DESCRIPTION
`image_id`	The 32-byte RISC Zero image id, as hex, bytes, or list. TYPE: `Binary`
`control_id`	The 32-byte control id, as hex, bytes, or list. TYPE: `Binary`
`hash_fn_id`	The hash function id; currently only "poseidon2" (also the default when omitted). TYPE: `Optional[str]` DEFAULT: `None`

RAISES	DESCRIPTION
`ZkError`	If an argument is malformed or the fragment cannot be appended.

append_r0_succinct_verifier_with_fixed_journal ¶

append_r0_succinct_verifier_with_fixed_journal(image_id: Binary, control_id: Binary, hash_fn_id: Optional[str] = None, *, journal: Binary) -> None

Append a fixed-journal r0 succinct verifier fragment, binding verification to journal baked into the script. Expects only [..., claim, control_index, control_digests, seal].

PARAMETER	DESCRIPTION
`image_id`	The 32-byte RISC Zero image id, as hex, bytes, or list. TYPE: `Binary`
`control_id`	The 32-byte control id, as hex, bytes, or list. TYPE: `Binary`
`hash_fn_id`	The hash function id; currently only "poseidon2" (also the default when omitted). TYPE: `Optional[str]` DEFAULT: `None`
`journal`	The 32-byte journal, as hex, bytes, or list. TYPE: `Binary`

RAISES	DESCRIPTION
`ZkError`	If an argument is malformed or the fragment cannot be appended.

commit_to_groth16 ¶

commit_to_groth16(image_id: Binary) -> None

Commit the script to unlocking only on a valid Groth16 proof for the given 32-byte image id. Transitions an unbounded builder into the Groth16-bounded state.

PARAMETER	DESCRIPTION
`image_id`	The 32-byte RISC Zero image id, as hex, bytes, or list. TYPE: `Binary`

RAISES	DESCRIPTION
`ZkError`	If the builder is not unbounded or `image_id` is malformed.

commit_to_succinct ¶

commit_to_succinct(image_id: Binary, control_id: Binary, hash_fn_id: Optional[str] = None) -> None

Commit the script to unlocking only on a valid succinct proof for the given image id and control id. Transitions an unbounded builder into the succinct-bounded state.

PARAMETER	DESCRIPTION
`image_id`	The 32-byte RISC Zero image id, as hex, bytes, or list. TYPE: `Binary`
`control_id`	The 32-byte control id, as hex, bytes, or list. TYPE: `Binary`
`hash_fn_id`	The hash function id; currently only "poseidon2" (also the default when omitted). TYPE: `Optional[str]` DEFAULT: `None`

RAISES	DESCRIPTION
`ZkError`	If the builder is not unbounded, an id is malformed, or the hash function id is unsupported.

drain ¶

drain() -> str

Drain the builder: return the accumulated script bytes and consume the builder. Matching the WASM SDK (and the native builder's move semantics) — and unlike ScriptBuilder.drain — the builder is not reusable afterwards: subsequent mutating calls raise ZkError.

RETURNS	DESCRIPTION
`str`	The script bytes, hex-encoded. TYPE: `str`

finalize_with_groth16_proof ¶

finalize_with_groth16_proof(receipt: Binary, journal_hash: Binary) -> FinalizedR0Script

Finalize a Groth16-bounded builder with a receipt and journal hash.

Consumes the builder and returns the spending script and inner redeem script, ready to unlock a zk-locked UTXO.

PARAMETER	DESCRIPTION
`receipt`	A borsh-encoded `Groth16Receipt<ReceiptClaim>`, as hex, bytes, or list. TYPE: `Binary`
`journal_hash`	The 32-byte journal hash, as hex, bytes, or list. TYPE: `Binary`

RETURNS	DESCRIPTION
`FinalizedR0Script`	The sig script and redeem script. TYPE: `FinalizedR0Script`

RAISES	DESCRIPTION
`ZkError`	If the builder is not Groth16-bounded, the receipt cannot be decoded, or `journal_hash` is malformed.

finalize_with_succinct_proof ¶

finalize_with_succinct_proof(receipt: Binary, journal: Binary) -> FinalizedR0Script

Finalize a succinct-bounded builder with a receipt and journal digest.

Consumes the builder and returns the spending script and inner redeem script, ready to unlock a zk-locked UTXO.

PARAMETER	DESCRIPTION
`receipt`	A borsh-encoded `SuccinctReceipt<ReceiptClaim>`, as hex, bytes, or list. TYPE: `Binary`
`journal`	The 32-byte journal digest, as hex, bytes, or list. TYPE: `Binary`

RETURNS	DESCRIPTION
`FinalizedR0Script`	The sig script and redeem script. TYPE: `FinalizedR0Script`

RAISES	DESCRIPTION
`ZkError`	If the builder is not succinct-bounded, the receipt cannot be decoded, or `journal` is malformed.

new_r0 `staticmethod` ¶

new_r0(covenants_enabled: bool = True, sigop_script_units: Optional[int] = None) -> ZkScriptBuilder

Construct a new ZkScriptBuilder for the RISC Zero proving flow.

Exposed as a static factory (not a constructor) — matching the WASM SDK — so future non-R0 backends can add their own factories without a breaking change.

PARAMETER	DESCRIPTION
`covenants_enabled`	Use the post-Toccata script limits (default: True). The zk proof pushes exceed the pre-Toccata 520-byte element limit, so finalizing always fails when this is False; only pass False to build fragments under pre-Toccata rules. TYPE: `bool` DEFAULT: `True`
`sigop_script_units`	Script units charged per signature operation. Defaults to the native engine default when omitted. TYPE: `Optional[int]` DEFAULT: `None`

RETURNS	DESCRIPTION
`ZkScriptBuilder`	A new unbounded builder. TYPE: `ZkScriptBuilder`

push_r0_groth16_proof ¶

push_r0_groth16_proof(receipt: Binary) -> None

Decode a Groth16 receipt and push the compressed proof bytes onto the builder.

Typically called while building a signature script; the script that invokes append_r0_groth16_verifier is responsible for placing journal_hash under this proof so the verifier sees [..., journal_hash, compressed_proof].

PARAMETER	DESCRIPTION
`receipt`	A borsh-encoded `Groth16Receipt<ReceiptClaim>`, as hex, bytes, or list. TYPE: `Binary`

RAISES	DESCRIPTION
`ZkError`	If the receipt cannot be decoded or the proof cannot be added.

push_r0_succinct_witness ¶

push_r0_succinct_witness(receipt: Binary) -> None

Decode a succinct receipt and push its witness material (claim, control index, control digests, seal) onto the builder.

The caller-owned journal is pushed afterwards (on top) to form the verifier's pre-stack.

PARAMETER	DESCRIPTION
`receipt`	A borsh-encoded `SuccinctReceipt<ReceiptClaim>`, as hex, bytes, or list. TYPE: `Binary`

RAISES	DESCRIPTION
`ZkError`	If the receipt cannot be decoded or the witness cannot be added.

script ¶

script() -> str

The current script bytes as a hex string.

RETURNS	DESCRIPTION
`str`	The script built so far, hex-encoded. TYPE: `str`

ZkScriptBuilder (Class)¶

__repr__ ¶