zeth.core.mixer_client Namespace Reference

Classes
class	MixCallDescription
class	MixerClient
class	MixOutputEvents
class	MixParameters
class	MixResult

Functions
List[Any]	mix_parameters_to_contract_arguments (IZKSnarkProvider zksnark, PairingParameters pp, MixParameters mix_parameters)
bytes	mix_parameters_to_dispatch_parameters (MixParameters mix_parameters)
MixResult	event_args_to_mix_result (Any event_args)
api.JoinsplitInput	create_api_joinsplit_input (List[str] merkle_path, int address, api.ZethNote note, OwnershipSecretKey a_sk, bytes nullifier)
Tuple[int, api.ZethNote]	get_dummy_input_and_address (OwnershipPublicKey a_pk)
List[bytes]	encrypt_notes (List[Tuple[api.ZethNote, EncryptionPublicKey]] notes)
Optional[Tuple[bytes, api.ZethNote]]	receive_note (MixOutputEvents out_ev, EncryptionSecretKey receiver_k_sk)
Iterator[MixResult]	get_mix_results (Any web3, Any mixer_instance, int start_block, int end_block, Optional[int] batch_size=None)
int	joinsplit_sign (IZKSnarkProvider zksnark, PairingParameters pp, JoinsplitSigKeyPair signing_keypair, str sender_eth_address, List[bytes] ciphertexts, ExtendedProof extproof, List[int] public_data, bool for_dispatch_call=False)
bytes	compute_commitment (api.ZethNote zeth_note, PairingParameters pp)
bytes	compute_nullifier (api.ZethNote zeth_note, OwnershipSecretKey spending_authority_ask)
bytes	compute_h_sig (List[bytes] nullifiers, JoinsplitSigVerificationKey sign_vk)

Variables
string	ZERO_UNITS_HEX = "0000000000000000"
string	ZERO_ADDRESS = "0x0000000000000000000000000000000000000000"
	JoinsplitSigVerificationKey = signing.SigningVerificationKey
	JoinsplitSigSecretKey = signing.SigningSecretKey
	JoinsplitSigKeyPair = signing.SigningKeyPair
	ComputeHSigCB = Callable[[List[bytes], JoinsplitSigVerificationKey], bytes]

Function Documentation

compute_commitment()

bytes zeth.core.mixer_client.compute_commitment	(	api.ZethNote	zeth_note,
		PairingParameters	pp
	)

Used by the recipient of a payment to recompute the commitment and check
the membership in the tree to confirm the validity of a payment

Definition at line 701 of file mixer_client.py.

def compute_commitment(zeth_note: api.ZethNote, pp: PairingParameters) -> bytes:
    """
    Used by the recipient of a payment to recompute the commitment and check
    the membership in the tree to confirm the validity of a payment
    """
    # inner_k = blake2s(r || a_pk || rho || v)
    blake = blake2s()
    blake.update(bytes.fromhex(zeth_note.trap_r))
    blake.update(bytes.fromhex(zeth_note.apk))
    blake.update(bytes.fromhex(zeth_note.rho))
    blake.update(bytes.fromhex(zeth_note.value))
    cm = blake.digest()
 
    cm_field = int.from_bytes(cm, byteorder="big") % pp.scalar_field_mod()
    return cm_field.to_bytes(int(constants.DIGEST_LENGTH/8), byteorder="big")
 
 

Here is the caller graph for this function:

compute_h_sig()

bytes zeth.core.mixer_client.compute_h_sig	(	List[bytes]	nullifiers,
		JoinsplitSigVerificationKey	sign_vk
	)

Compute h_sig = sha256(nf_1 || ... || nf_{JS_INPUTS} || sign_vk)

Definition at line 734 of file mixer_client.py.

def compute_h_sig(
        nullifiers: List[bytes],
        sign_vk: JoinsplitSigVerificationKey) -> bytes:
    """
    Compute h_sig = sha256(nf_1 || ... || nf_{JS_INPUTS} || sign_vk)
    """
    h = sha256()
    for nf in nullifiers:
        h.update(nf)
    h.update(sign_vk.to_bytes())
    return h.digest()
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

compute_nullifier()

bytes zeth.core.mixer_client.compute_nullifier	(	api.ZethNote	zeth_note,
		OwnershipSecretKey	spending_authority_ask
	)

Returns nf = blake2s(1110 || [a_sk]_252 || rho)

Definition at line 718 of file mixer_client.py.

def compute_nullifier(
        zeth_note: api.ZethNote,
        spending_authority_ask: OwnershipSecretKey) -> bytes:
    """
    Returns nf = blake2s(1110 || [a_sk]_252 || rho)
    """
    binary_ask = digest_to_binary_string(spending_authority_ask)
    first_252bits_ask = binary_ask[:252]
    left_leg_bin = "1110" + first_252bits_ask
    left_leg = int(left_leg_bin, 2).to_bytes(32, byteorder='big')
    blake_hash = blake2s()
    blake_hash.update(left_leg)
    blake_hash.update(bytes.fromhex(zeth_note.rho))
    return blake_hash.digest()
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

create_api_joinsplit_input()

api.JoinsplitInput zeth.core.mixer_client.create_api_joinsplit_input	(	List[str]	merkle_path,
		int	address,
		api.ZethNote	note,
		OwnershipSecretKey	a_sk,
		bytes	nullifier
	)

Definition at line 227 of file mixer_client.py.

def create_api_joinsplit_input(
        merkle_path: List[str],
        address: int,
        note: api.ZethNote,
        a_sk: OwnershipSecretKey,
        nullifier: bytes) -> api.JoinsplitInput:
    return api.JoinsplitInput(
        merkle_path=merkle_path,
        address=address,
        note=note,
        spending_ask=ownership_key_as_hex(a_sk),
        nullifier=nullifier.hex())
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

encrypt_notes()

List[bytes] zeth.core.mixer_client.encrypt_notes

(

List[Tuple[api.ZethNote, EncryptionPublicKey]]

notes

)

Encrypts a set of output notes to be decrypted by the respective receivers.
Returns the ciphertexts corresponding to each note.

Definition at line 601 of file mixer_client.py.

def encrypt_notes(
        notes: List[Tuple[api.ZethNote, EncryptionPublicKey]]) -> List[bytes]:
    """
    Encrypts a set of output notes to be decrypted by the respective receivers.
    Returns the ciphertexts corresponding to each note.
    """
 
    def _encrypt_note(
            out_note: api.ZethNote, pub_key: EncryptionPublicKey) -> bytes:
        out_note_bytes = proto_utils.zeth_note_to_bytes(out_note)
 
        return encrypt(out_note_bytes, pub_key)
 
    ciphertexts = [_encrypt_note(note, pk) for (note, pk) in notes]
    return ciphertexts
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

event_args_to_mix_result()

MixResult zeth.core.mixer_client.event_args_to_mix_result

(

Any

event_args

)

Definition at line 218 of file mixer_client.py.

def event_args_to_mix_result(event_args: Any) -> MixResult:
    mix_out_args = zip(event_args.commitments, event_args.ciphertexts)
    out_events = [MixOutputEvents(c, ciph) for (c, ciph) in mix_out_args]
    return MixResult(
        new_merkle_root=event_args.root,
        nullifiers=event_args.nullifiers,
        output_events=out_events)
 
 

Here is the caller graph for this function:

get_dummy_input_and_address()

Tuple[int, api.ZethNote] zeth.core.mixer_client.get_dummy_input_and_address

(

OwnershipPublicKey

a_pk

)

Create a zeth note and address, for use as circuit inputs where there is no
real input.

Definition at line 241 of file mixer_client.py.

def get_dummy_input_and_address(
        a_pk: OwnershipPublicKey) -> Tuple[int, api.ZethNote]:
    """
    Create a zeth note and address, for use as circuit inputs where there is no
    real input.
    """
    dummy_note = api.ZethNote(
        apk=ownership_key_as_hex(a_pk),
        value=ZERO_UNITS_HEX,
        rho=_get_dummy_rho(),
        trap_r=_trap_r_randomness())
    # Note that the Merkle path is not fully checked against the root by the
    # circuit since the note value is 0. Hence the address used here is
    # arbitrary.
    dummy_note_address = 0
    return (dummy_note_address, dummy_note)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

get_mix_results()

Iterator[MixResult] zeth.core.mixer_client.get_mix_results	(	Any	web3,
		Any	mixer_instance,
		int	start_block,
		int	end_block,
		Optional[int]	batch_size = None
	)

Iterator for all events generated by 'mix' executions, over some block
range (inclusive of `end_block`). Batch eth RPC calls to avoid too many
calls, and holding huge lists of events in memory.

Definition at line 640 of file mixer_client.py.

def get_mix_results(
        web3: Any,
        mixer_instance: Any,
        start_block: int,
        end_block: int,
        batch_size: Optional[int] = None) -> Iterator[MixResult]:
    """
    Iterator for all events generated by 'mix' executions, over some block
    range (inclusive of `end_block`). Batch eth RPC calls to avoid too many
    calls, and holding huge lists of events in memory.
    """
    logs = contracts.get_event_logs(
        web3, mixer_instance, "LogMix", start_block, end_block, batch_size)
    for event_data in logs:
        yield event_args_to_mix_result(event_data.args)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

joinsplit_sign()

int zeth.core.mixer_client.joinsplit_sign	(	IZKSnarkProvider	zksnark,
		PairingParameters	pp,
		JoinsplitSigKeyPair	signing_keypair,
		str	sender_eth_address,
		List[bytes]	ciphertexts,
		ExtendedProof	extproof,
		List[int]	public_data,
		bool	for_dispatch_call = False
	)

Generate a signature on the hash of the ciphertexts, proofs and primary
inputs. This is used to solve transaction malleability. We chose to sign
the hash and not the values themselves for modularity (to use the same code
regardless of whether GROTH16 or PGHR13 proof system is chosen), and sign
the hash of the ciphers and inputs for consistency. If for_dispatch_call is
set, the parameters are to be passed to the Mixer's `dispatch` call in a
later operation (in which proof data is not available), hence proof is
omitted from the signature.

Definition at line 657 of file mixer_client.py.

def joinsplit_sign(
        zksnark: IZKSnarkProvider,
        pp: PairingParameters,
        signing_keypair: JoinsplitSigKeyPair,
        sender_eth_address: str,
        ciphertexts: List[bytes],
        extproof: ExtendedProof,
        public_data: List[int],
        for_dispatch_call: bool = False) -> int:
    """
    Generate a signature on the hash of the ciphertexts, proofs and primary
    inputs. This is used to solve transaction malleability. We chose to sign
    the hash and not the values themselves for modularity (to use the same code
    regardless of whether GROTH16 or PGHR13 proof system is chosen), and sign
    the hash of the ciphers and inputs for consistency. If for_dispatch_call is
    set, the parameters are to be passed to the Mixer's `dispatch` call in a
    later operation (in which proof data is not available), hence proof is
    omitted from the signature.
    """
    assert len(ciphertexts) == constants.JS_INPUTS
 
    # The message to sign consists of (in order):
    #   - senders Ethereum address
    #   - ciphertexts
    #   - proof elements (if for_dispatch_call is False)
    #   - public input elements
    h = sha256()
    h.update(eth_address_to_bytes32(sender_eth_address))
    for ciphertext in ciphertexts:
        h.update(ciphertext)
 
    proof_bytes, pub_inputs_bytes = _proof_and_inputs_to_bytes(
        zksnark, pp, extproof, public_data)
 
    # If for_dispatch_call is set, omit proof from the signature. See
    # AbstractMixer.sol.
    if not for_dispatch_call:
        h.update(proof_bytes)
 
    h.update(pub_inputs_bytes)
    message_digest = h.digest()
    return signing.sign(signing_keypair.sk, message_digest)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

mix_parameters_to_contract_arguments()

List[Any] zeth.core.mixer_client.mix_parameters_to_contract_arguments	(	IZKSnarkProvider	zksnark,
		PairingParameters	pp,
		MixParameters	mix_parameters
	)

Convert MixParameters to a list of eth ABI objects which can be passed to
the contract's mix method.

Definition at line 157 of file mixer_client.py.

def mix_parameters_to_contract_arguments(
        zksnark: IZKSnarkProvider,
        pp: PairingParameters,
        mix_parameters: MixParameters) -> List[Any]:
    """
    Convert MixParameters to a list of eth ABI objects which can be passed to
    the contract's mix method.
    """
    proof_contract_params = zksnark.proof_to_contract_parameters(
        mix_parameters.extended_proof.proof, pp)
    return [
        proof_contract_params,
        signing.verification_key_as_mix_parameter(mix_parameters.signature_vk),
        signing.signature_as_mix_parameter(mix_parameters.signature),
        mix_parameters.public_data,
        mix_parameters.ciphertexts,
    ]
 
 

Here is the caller graph for this function:

mix_parameters_to_dispatch_parameters()

bytes zeth.core.mixer_client.mix_parameters_to_dispatch_parameters

(

MixParameters

mix_parameters

)

Encode parameters from mix_parameters into an array of uint256 values,
compatible with the `dispatch` method on Mixer. This conforms to the
`IZecaleApplication` solidity interface of Zecale
(https://github.com/clearmatics/zecale)

Definition at line 176 of file mixer_client.py.

def mix_parameters_to_dispatch_parameters(mix_parameters: MixParameters) -> bytes:
    """
    Encode parameters from mix_parameters into an array of uint256 values,
    compatible with the `dispatch` method on Mixer. This conforms to the
    `IZecaleApplication` solidity interface of Zecale
    (https://github.com/clearmatics/zecale)
    """
    vk_param = signing.verification_key_as_mix_parameter(
        mix_parameters.signature_vk)
    sigma_param = signing.signature_as_mix_parameter(mix_parameters.signature)
    public_data = mix_parameters.public_data
    ciphertexts = mix_parameters.ciphertexts
    return eth_abi.encode_abi(
        ['uint256[4]', 'uint256', 'uint256[]', 'bytes[]'],
        [vk_param, sigma_param, public_data, ciphertexts])  # type: ignore
 
 

receive_note()

Optional[Tuple[bytes, api.ZethNote]] zeth.core.mixer_client.receive_note	(	MixOutputEvents	out_ev,
		EncryptionSecretKey	receiver_k_sk
	)

Given the receivers secret key, and the event data from a transaction
(encrypted notes), decrypt any that are intended for the receiver. Return
tuples `(<address-in-merkle-tree>, ZethNote)`. Callers should record the
address-in-merkle-tree along with ZethNote information, for convenience
when spending the notes.

Definition at line 618 of file mixer_client.py.

def receive_note(
        out_ev: MixOutputEvents,
        receiver_k_sk: EncryptionSecretKey
) -> Optional[Tuple[bytes, api.ZethNote]]:
    """
    Given the receivers secret key, and the event data from a transaction
    (encrypted notes), decrypt any that are intended for the receiver. Return
    tuples `(<address-in-merkle-tree>, ZethNote)`. Callers should record the
    address-in-merkle-tree along with ZethNote information, for convenience
    when spending the notes.
    """
    try:
        plaintext = decrypt(out_ev.ciphertext, receiver_k_sk)
        return (
            out_ev.commitment,
            proto_utils.zeth_note_from_bytes(plaintext))
    except InvalidSignature:
        return None
    except ValueError:
        return None
 
 

Here is the call graph for this function:

Variable Documentation

ComputeHSigCB

zeth.core.mixer_client.ComputeHSigCB = Callable[[List[bytes], JoinsplitSigVerificationKey], bytes]

Definition at line 46 of file mixer_client.py.

JoinsplitSigKeyPair

zeth.core.mixer_client.JoinsplitSigKeyPair = signing.SigningKeyPair

Definition at line 44 of file mixer_client.py.

JoinsplitSigSecretKey

zeth.core.mixer_client.JoinsplitSigSecretKey = signing.SigningSecretKey

Definition at line 43 of file mixer_client.py.

JoinsplitSigVerificationKey

zeth.core.mixer_client.JoinsplitSigVerificationKey = signing.SigningVerificationKey

Definition at line 42 of file mixer_client.py.

ZERO_ADDRESS

string zeth.core.mixer_client.ZERO_ADDRESS = "0x0000000000000000000000000000000000000000"

Definition at line 39 of file mixer_client.py.

ZERO_UNITS_HEX

string zeth.core.mixer_client.ZERO_UNITS_HEX = "0000000000000000"

Definition at line 38 of file mixer_client.py.