package tezos-sapling

  1. Overview
  2. Docs
package tezos-sapling
Legend:
Library
Module
Module type
Parameter
Class
Class type
include Rustzcash_sig.T
type ask
type ak
type nsk
type nk
type ovk
type diversifier
type pkd
type nullifier
type commitment
type epk
type symkey
type sighash
type spend_sig
type hash
type cv
type rk
type spend_proof
type binding_sig
type output_proof
type ivk
type ar
type rcm
type esk
type diversifier_index
val compare_diversifier_index : diversifier_index -> diversifier_index -> int
type expanded_spending_key = {
  1. ask : ask;
  2. nsk : nsk;
  3. ovk : ovk;
}
type zip32_expanded_spending_key = {
  1. depth : Bytes.t;
  2. parent_fvk_tag : Bytes.t;
  3. child_index : Bytes.t;
  4. chain_code : Bytes.t;
  5. expsk : expanded_spending_key;
  6. dk : Bytes.t;
}
type full_viewing_key = {
  1. ak : ak;
  2. nk : nk;
  3. ovk : ovk;
}
type zip32_full_viewing_key = {
  1. depth : Bytes.t;
  2. parent_fvk_tag : Bytes.t;
  3. child_index : Bytes.t;
  4. chain_code : Bytes.t;
  5. fvk : full_viewing_key;
  6. dk : Bytes.t;
}
val to_nk : Bytes.t -> nk
val to_ak : Bytes.t -> ak
val to_ask : Bytes.t -> ask
val to_nsk : Bytes.t -> nsk
val to_pkd : Bytes.t -> pkd
val to_ovk : Bytes.t -> ovk
val to_nullifier : Bytes.t -> nullifier
val to_commitment : Bytes.t -> commitment
val to_symkey : Bytes.t -> symkey
val to_epk : Bytes.t -> epk
val to_spend_sig : Bytes.t -> spend_sig
val to_hash : Bytes.t -> hash
val to_cv : Bytes.t -> cv
val to_rk : Bytes.t -> rk
val to_spend_proof : Bytes.t -> spend_proof
val to_output_proof : Bytes.t -> output_proof
val to_sighash : Bytes.t -> sighash
val to_binding_sig : Bytes.t -> binding_sig
val to_diversifier : Bytes.t -> diversifier option
val to_diversifier_index : Bytes.t -> diversifier_index
val to_ar : Bytes.t -> ar
val to_rcm : Bytes.t -> rcm
val to_esk : Bytes.t -> esk
val to_ivk : Bytes.t -> ivk
val to_expanded_spending_key : Bytes.t -> expanded_spending_key
val to_zip32_expanded_spending_key : Bytes.t -> zip32_expanded_spending_key
val to_full_viewing_key : Bytes.t -> full_viewing_key
val to_zip32_full_viewing_key : Bytes.t -> zip32_full_viewing_key
val of_nk : nk -> Bytes.t
val of_ak : ak -> Bytes.t
val of_ask : ask -> Bytes.t
val of_nsk : nsk -> Bytes.t
val of_pkd : pkd -> Bytes.t
val of_ovk : ovk -> Bytes.t
val of_nullifier : nullifier -> Bytes.t
val of_commitment : commitment -> Bytes.t
val of_symkey : symkey -> Bytes.t
val of_epk : epk -> Bytes.t
val of_spend_sig : spend_sig -> Bytes.t
val of_hash : hash -> Bytes.t
val of_cv : cv -> Bytes.t
val of_rk : rk -> Bytes.t
val of_spend_proof : spend_proof -> Bytes.t
val of_output_proof : output_proof -> Bytes.t
val of_sighash : sighash -> Bytes.t
val of_binding_sig : binding_sig -> Bytes.t
val of_diversifier : diversifier -> Bytes.t
val of_diversifier_index : diversifier_index -> Bytes.t
val of_ar : ar -> Bytes.t
val of_rcm : rcm -> Bytes.t
val of_esk : esk -> Bytes.t
val of_ivk : ivk -> Bytes.t
val of_expanded_spending_key : expanded_spending_key -> Bytes.t
val of_zip32_expanded_spending_key : zip32_expanded_spending_key -> Bytes.t
val of_full_viewing_key : full_viewing_key -> Bytes.t
val of_zip32_full_viewing_key : zip32_full_viewing_key -> Bytes.t
val hash_compare : hash -> hash -> int
val hash_of_commitment : commitment -> hash
val commitment_of_hash : hash -> commitment
val max_amount : int64
val valid_position : int64 -> bool

In principle the definition of a valid position depends on the data structure that holds it, so it should be defined in storage.ml. However librustzcash imposes a particular tree structure of depth 32, so we hardcode it here.

val valid_amount : int64 -> bool
val valid_balance : int64 -> bool
exception Params_not_found of string list

Raised by init_params if it failed to find parameters.

The string list is the list of locations where they were looked up.

type parameter_files = {
  1. spend_path : string;
  2. output_path : string;
}

Location of parameter files for our instance of Groth16.

We are only using and loading sapling parameters.

val find_params : ?getenv_opt:(string -> string option) -> ?getcwd:(unit -> string) -> ?file_exists:(string -> bool) -> unit -> parameter_files

Find parameter files.

The parameters are searched in:

  • $XDG_DATA_HOME/.local/share/zcash-params;
  • $XDG_DATA_DIRS/zcash-params (splitting on the : character);
  • $OPAM_SWITCH_PREFIX/share/zcash-params;
  • _opam/share/zcash-params;
  • $HOME/.zcash-params;
  • $HOME/.local/share/zcash-params;
  • /usr/local/share/zcash-params;
  • /usr/share/zcash-params; in this order.

This function uses getenv_opt, getcwd and file_exists from the Sys module. You can use the corresponding optional arguments to override their behavior, for instance with a mock for testing purposes.

  • raises [Params_not_found]

    if parameters could not be found at any of those locations.

val init_params : unit -> unit

Load parameter files.

  • raises [Params_not_found]

    if parameters could not be found (see find_params for information regarding how parameter files are looked up).

val nsk_to_nk : nsk -> nk

Derives the nullifier pk corresponding to a nullifier sk

val ask_to_ak : ask -> ak

Derives the spending/signing pk corresponding to a secret spending/signing sk

val crh_ivk : ak -> nk -> ivk

Derives the incoming viewing key

val check_diversifier : diversifier -> bool

Checks that a potential diversifier respects the needed properties

val ivk_to_pkd : ivk -> diversifier -> pkd

Computes a diversified pk that the payee gives to the payer offline.

  • raises [Assert_failure]

    if the underlying binding in rust indicates a failure, which only happens if the arguments are not valid representations for their expected type, which can only happen if there's an error in the constructors for these abstract types.

val generate_r : unit -> Bytes.t

Gives a random scalar

val compute_nf : diversifier -> pkd -> amount:int64 -> rcm -> ak -> nk -> position:int64 -> nullifier

Computes a nullifier. The first int64 is the amount of the note, the second is the position you want it inserted in. The rcm should be the same as the one to compute cm and the spend or output proof, and should be generated using generate_r.

  • raises [Assert_failure]

    if the underlying binding in rust indicates a failure, which only happens if the arguments are not valid representations for their expected type, which can only happen if there's an error in the constructors for these abstract types.

val compute_cm : diversifier -> pkd -> amount:int64 -> rcm -> commitment

Computes a commitment. The int64 is the amount, and the rcm is the same than for the nullifier and output or spend proof. It should be generated at random using generate_r.

  • raises [Assert_failure]

    if the underlying binding in rust indicates a failure, which only happens if the arguments are not valid representations for their expected type, which can only happen if there's an error in the constructors for these abstract types.

val ka_agree_sender : pkd -> esk -> symkey

Computes the shared secret of a Diffie Hellman key exchange (on the JubJub curve) with base depending on the diversifier. For the sender the epk is the pkd of the receiver, the esk was generated by him using generate_r. For the receiver the epk is the one published by the sender, and the secret is his ivk.

  • raises [Assert_failure]

    if the underlying binding in rust indicates a failure, which only happens if the arguments are not valid representations for their expected type, which can only happen if there's an error in the constructors for these abstract types.

val ka_agree_receiver : epk -> ivk -> symkey
val ka_derivepublic : diversifier -> esk -> epk

Computes the ephemeral pk from the ephemeral sk for a Diffie Hellman key exchange. This is used by the sender. The esk should be generated using generate_r

  • raises [Assert_failure]

    if the underlying binding in rust indicates a failure, which only happens if the arguments are not valid representations for their expected type, which can only happen if there's an error in the constructors for these abstract types.

val spend_sig : ask -> ar -> sighash -> spend_sig

Creates the spend sig for an input. The sighash argument is the hash of the input ie. cv,cm,... This has to be generated using generate_r

  • raises [Assert_failure]

    if the underlying binding in rust indicates a failure, which only happens if the arguments are not valid representations for their expected type, which can only happen if there's an error in the constructors for these abstract types.

type proving_ctx
val proving_ctx_init : unit -> proving_ctx

Creates and frees a proving context. The proving context has to be created before creating proofs for inputs and outputs. It is then used to create the binding sig, and freed. It is a rust pointer to a scalar and an elliptic curve point

val proving_ctx_free : proving_ctx -> unit
val with_proving_ctx : (proving_ctx -> 'a) -> 'a

Evaluates a function that needs a proving context. This function takes care of allocating and freeing it. The context should not escape the scope of the given function and should not be freed during its execution.

val make_binding_sig : proving_ctx -> balance:int64 -> sighash -> binding_sig

Creates the binding signature for a transaction. It is effectively a zk proof that the sum of the amounts of a list of inputs and outputs is the same as the given balance. The necessary information is stored in the proving context when creating the proofs for inputs and outputs. The proving context has to be freed after calling this function.

  • raises [Assert_failure]

    if the underlying binding in rust indicates a failure, which only happens if the arguments are not valid representations for their expected type, which can only happen if there's an error in the constructors for these abstract types.

val output_proof : proving_ctx -> esk -> diversifier -> pkd -> rcm -> amount:int64 -> cv * output_proof

Creates proof and sig for an output

  • raises [Assert_failure]

    if the underlying binding in rust indicates a failure, which only happens if the arguments are not valid representations for their expected type, which can only happen if there's an error in the constructors for these abstract types.

val spend_proof : proving_ctx -> ak -> nsk -> diversifier -> rcm -> ar -> amount:int64 -> root:hash -> witness:Bytes.t -> cv * rk * spend_proof

Creates the zk proof and sig for an input. The first is the same as the one for the commitment and nullifier. The second one is the same as for the binding sig. This function can panic (e.g. if the arguments are not coherent).

  • raises [Assert_failure]

    if the underlying binding in rust indicates a failure, which only happens if the arguments are not valid representations for their expected type, which can only happen if there's an error in the constructors for these abstract types.

val to_scalar : Bytes.t -> Bytes.t

Reduces mod r_j, takes a 64 bytes input

type verification_ctx
val verification_ctx_init : unit -> verification_ctx

Creates and frees a verifying context. The proving context has to be created before verifying proofs the inputs and outputs. It is then used to verify the binding sig, and freed. It is a rust pointer to an elliptic curve point

val verification_ctx_free : verification_ctx -> unit
val with_verification_ctx : (verification_ctx -> 'a) -> 'a

Evaluates a function that needs a verification context. This function takes care of allocating and freeing it. The context should not escape the scope of the given function and should not be freed during its execution.

val check_output : verification_ctx -> cv -> commitment -> epk -> output_proof -> bool
val check_spend : verification_ctx -> cv -> hash -> nullifier -> rk -> spend_proof -> spend_sig -> sighash -> bool
val merkle_hash : height:int -> hash -> hash -> hash
val tree_uncommitted : hash
val final_check : verification_ctx -> int64 -> binding_sig -> sighash -> bool
val zip32_xsk_master : Bytes.t -> zip32_expanded_spending_key
val zip32_xfvk_address : zip32_full_viewing_key -> diversifier_index -> (diversifier_index * diversifier * pkd) option