zeth.core.mixer_client.MixerClient Class Reference

Public Member Functions
def	__init__ (self, Any web3, ProverConfiguration prover_config, Any mixer_instance)
str	deposit (self, ProverClient prover_client, MerkleTree mk_tree, ZethAddress zeth_address, str sender_eth_address, Optional[bytes] sender_eth_private_key, EtherValue eth_amount, Optional[List[Tuple[ZethAddressPub, EtherValue]]] outputs=None, Optional[EtherValue] tx_value=None)
str	joinsplit (self, ProverClient prover_client, MerkleTree mk_tree, OwnershipKeyPair sender_ownership_keypair, str sender_eth_address, Optional[bytes] sender_eth_private_key, List[Tuple[int, api.ZethNote]] inputs, List[Tuple[ZethAddressPub, EtherValue]] outputs, EtherValue v_in, EtherValue v_out, Optional[EtherValue] tx_value=None, Optional[ComputeHSigCB] compute_h_sig_cb=None)
str	mix (self, MixParameters mix_params, str sender_eth_address, Optional[bytes] sender_eth_private_key, EtherValue tx_value, Optional[int] call_gas=None)
bool	mix_call (self, MixParameters mix_params, str sender_eth_address, EtherValue tx_value, Optional[int] call_gas=None)
MixParameters	create_mix_parameters_from_proof (self, MixCallDescription mix_call_desc, api.ProofInputs prover_inputs, signing.SigningKeyPair signing_keypair, ExtendedProof ext_proof, List[int] public_data, str sender_eth_address, bool for_dispatch_call=False)
Tuple[MixParameters, JoinsplitSigKeyPair]	create_mix_parameters_and_signing_key (self, ProverClient prover_client, MerkleTree mk_tree, OwnershipKeyPair sender_ownership_keypair, str sender_eth_address, List[Tuple[int, api.ZethNote]] inputs, List[Tuple[ZethAddressPub, EtherValue]] outputs, EtherValue v_in, EtherValue v_out, Optional[ComputeHSigCB] compute_h_sig_cb=None, bool for_dispatch_call=False)

Static Public Member Functions
Tuple[MixerClient, contracts.InstanceDescription]	deploy (Any web3, ProverClient prover_client, str deployer_eth_address, Optional[bytes] deployer_eth_private_key, Optional[str] token_address=None, Optional[str] permitted_dispatcher=None, Optional[str] vk_hash=None, Optional[int] deploy_gas=None)
Tuple[api.ProofInputs, signing.SigningKeyPair]	create_prover_inputs (MixCallDescription mix_call_desc)

Public Attributes
	web3
	prover_config
	mixer_instance

Detailed Description

Interface to operations on the Mixer contract.

Definition at line 259 of file mixer_client.py.

Constructor & Destructor Documentation

__init__()

def zeth.core.mixer_client.MixerClient.__init__	(		self,
		Any	web3,
		ProverConfiguration	prover_config,
		Any	mixer_instance
	)

Definition at line 263 of file mixer_client.py.

    def __init__(
            self,
            web3: Any,
            prover_config: ProverConfiguration,
            mixer_instance: Any):
        self.web3 = web3
        self.prover_config = prover_config
        self.mixer_instance = mixer_instance
 

Member Function Documentation

create_mix_parameters_and_signing_key()

Tuple[MixParameters, JoinsplitSigKeyPair] zeth.core.mixer_client.MixerClient.create_mix_parameters_and_signing_key	(		self,
		ProverClient	prover_client,
		MerkleTree	mk_tree,
		OwnershipKeyPair	sender_ownership_keypair,
		str	sender_eth_address,
		List[Tuple[int, api.ZethNote]]	inputs,
		List[Tuple[ZethAddressPub, EtherValue]]	outputs,
		EtherValue	v_in,
		EtherValue	v_out,
		Optional[ComputeHSigCB]	compute_h_sig_cb = None,
		bool	for_dispatch_call = False
	)

Convenience function around creation of MixCallDescription, ProofInputs,
Proof and MixParameters. 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 545 of file mixer_client.py.

    def create_mix_parameters_and_signing_key(
            self,
            prover_client: ProverClient,
            mk_tree: MerkleTree,
            sender_ownership_keypair: OwnershipKeyPair,
            sender_eth_address: str,
            inputs: List[Tuple[int, api.ZethNote]],
            outputs: List[Tuple[ZethAddressPub, EtherValue]],
            v_in: EtherValue,
            v_out: EtherValue,
            compute_h_sig_cb: Optional[ComputeHSigCB] = None,
            for_dispatch_call: bool = False
    ) -> Tuple[MixParameters, JoinsplitSigKeyPair]:
        """
        Convenience function around creation of MixCallDescription, ProofInputs,
        Proof and MixParameters. 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.
        """
        # Generate prover inputs and signing key
        mix_call_desc = MixCallDescription(
            mk_tree,
            sender_ownership_keypair,
            inputs,
            outputs,
            v_in,
            v_out,
            compute_h_sig_cb)
        assert len(mix_call_desc.inputs) == constants.JS_INPUTS
        assert len(mix_call_desc.outputs) == constants.JS_OUTPUTS
 
        prover_inputs, signing_keypair = MixerClient.create_prover_inputs(
            mix_call_desc)
 
        # pylint: disable=no-member
        assert len(prover_inputs.js_inputs) == constants.JS_INPUTS
        assert len(prover_inputs.js_outputs) == constants.JS_OUTPUTS
        # pylint: enable=no-member
 
        # Query the prover-server for the related proof
        ext_proof, public_data = prover_client.get_proof(prover_inputs)
 
        # Create the final MixParameters object
        mix_params = self.create_mix_parameters_from_proof(
            mix_call_desc,
            prover_inputs,
            signing_keypair,
            ext_proof,
            public_data,
            sender_eth_address,
            for_dispatch_call)
 
        return mix_params, signing_keypair
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

create_mix_parameters_from_proof()

MixParameters zeth.core.mixer_client.MixerClient.create_mix_parameters_from_proof	(		self,
		MixCallDescription	mix_call_desc,
		api.ProofInputs	prover_inputs,
		signing.SigningKeyPair	signing_keypair,
		ExtendedProof	ext_proof,
		List[int]	public_data,
		str	sender_eth_address,
		bool	for_dispatch_call = False
	)

Create the MixParameters from MixCallDescription, signing keypair, sender
address and derived data (prover inputs and proof). This includes
creating and encrypting the plaintext messages, and generating the
one-time signature.

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 500 of file mixer_client.py.

    def create_mix_parameters_from_proof(
            self,
            mix_call_desc: MixCallDescription,
            prover_inputs: api.ProofInputs,
            signing_keypair: signing.SigningKeyPair,
            ext_proof: ExtendedProof,
            public_data: List[int],
            sender_eth_address: str,
            for_dispatch_call: bool = False
    ) -> MixParameters:
        """
        Create the MixParameters from MixCallDescription, signing keypair, sender
        address and derived data (prover inputs and proof). This includes
        creating and encrypting the plaintext messages, and generating the
        one-time signature.
 
        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.
        """
 
        # Encrypt the notes
        outputs_and_notes = zip(mix_call_desc.outputs, prover_inputs.js_outputs) \
            # pylint: disable=no-member
        output_notes_with_k_pk: List[Tuple[api.ZethNote, EncryptionPublicKey]] = \
            [(note, zeth_addr.k_pk)
             for ((zeth_addr, _), note) in outputs_and_notes]
        ciphertexts = encrypt_notes(output_notes_with_k_pk)
 
        # Sign
        zksnark = get_zksnark_provider(self.prover_config.zksnark_name)
        signature = joinsplit_sign(
            zksnark,
            self.prover_config.pairing_parameters,
            signing_keypair,
            sender_eth_address,
            ciphertexts,
            ext_proof,
            public_data,
            for_dispatch_call)
 
        mix_params = MixParameters(
            ext_proof, public_data, signing_keypair.vk, signature, ciphertexts)
        return mix_params
 

Here is the call graph for this function:

Here is the caller graph for this function:

create_prover_inputs()

Tuple[api.ProofInputs, signing.SigningKeyPair] zeth.core.mixer_client.MixerClient.create_prover_inputs ( MixCallDescription   mix_call_desc )

static

Given the basic parameters for a mix call, compute the input to the prover
server, and the signing key pair.

Definition at line 439 of file mixer_client.py.

    def create_prover_inputs(
            mix_call_desc: MixCallDescription
    ) -> Tuple[api.ProofInputs, signing.SigningKeyPair]:
        """
        Given the basic parameters for a mix call, compute the input to the prover
        server, and the signing key pair.
        """
 
        # Compute Merkle paths
        mk_tree = mix_call_desc.mk_tree
        sender_ask = mix_call_desc.sender_ownership_keypair.a_sk
 
        def _create_api_input(
                input_address: int,
                input_note: api.ZethNote) -> api.JoinsplitInput:
            mk_path = compute_merkle_path(input_address, mk_tree)
            input_nullifier = compute_nullifier(input_note, sender_ask)
            return create_api_joinsplit_input(
                mk_path,
                input_address,
                input_note,
                sender_ask,
                input_nullifier)
 
        inputs = mix_call_desc.inputs
        api_inputs = [_create_api_input(addr, note) for addr, note in inputs]
 
        mk_root = mk_tree.get_root()
 
        # Extract (<ownership-address>, <value>) tuples
        outputs_with_a_pk = \
            [(zeth_addr.a_pk, to_zeth_units(value))
             for (zeth_addr, value) in mix_call_desc.outputs]
 
        # Public input and output values as Zeth units
        public_in_value_zeth_units = to_zeth_units(mix_call_desc.v_in)
        public_out_value_zeth_units = to_zeth_units(mix_call_desc.v_out)
 
        # Generate the signing key
        signing_keypair = signing.gen_signing_keypair()
 
        # Use the specified or default h_sig computation
        compute_h_sig_cb = mix_call_desc.compute_h_sig_cb or compute_h_sig
        h_sig = compute_h_sig_cb(
            [bytes.fromhex(input.nullifier) for input in api_inputs],
            signing_keypair.vk)
        phi = _phi_randomness()
 
        # Create the api.ZethNote objects
        api_outputs = _create_api_zeth_notes(phi, h_sig, outputs_with_a_pk)
 
        proof_inputs = api.ProofInputs(
            mk_root=mk_root.hex(),
            js_inputs=api_inputs,
            js_outputs=api_outputs,
            pub_in_value=int64_to_hex(public_in_value_zeth_units),
            pub_out_value=int64_to_hex(public_out_value_zeth_units),
            h_sig=h_sig.hex(),
            phi=phi.hex())
        return (proof_inputs, signing_keypair)
 

Here is the call graph for this function:

deploy()

Tuple[MixerClient, contracts.InstanceDescription] zeth.core.mixer_client.MixerClient.deploy ( Any  web3, ProverClient  prover_client, str  deployer_eth_address, Optional[bytes]  deployer_eth_private_key, Optional[str]   token_address = None, Optional[str]   permitted_dispatcher = None, Optional[str]   vk_hash = None, Optional[int]   deploy_gas = None  )

static

Deploy Zeth contracts.

Definition at line 273 of file mixer_client.py.

    def deploy(
            web3: Any,
            prover_client: ProverClient,
            deployer_eth_address: str,
            deployer_eth_private_key: Optional[bytes],
            token_address: Optional[str] = None,
            permitted_dispatcher: Optional[str] = None,
            vk_hash: Optional[str] = None,
            deploy_gas: Optional[int] = None
    ) -> Tuple[MixerClient, contracts.InstanceDescription]:
        """
        Deploy Zeth contracts.
        """
        prover_config = prover_client.get_configuration()
        vk = prover_client.get_verification_key()
 
        contracts_dir = get_contracts_dir()
        zksnark = get_zksnark_provider(prover_config.zksnark_name)
        pp = prover_config.pairing_parameters
        mixer_name = zksnark.get_contract_name(pp)
        mixer_src = os.path.join(contracts_dir, mixer_name + ".sol")
        vk_hash_evm = list(hex_to_uint256_list(vk_hash)) if vk_hash else [0, 0]
        assert len(vk_hash_evm) == 2
 
        # Constructor parameters have the form:
        #   uint256 mk_depth
        #   address token
        #   ... snark-specific key data ...
        constructor_parameters: List[Any] = [
            constants.ZETH_MERKLE_TREE_DEPTH,  # mk_depth
            token_address or ZERO_ADDRESS,     # token
            zksnark.verification_key_to_contract_parameters(vk, pp),  # vk
            permitted_dispatcher or ZERO_ADDRESS,  # permitted_dispatcher
            vk_hash_evm  # vk_hash
        ]
        mixer_description = contracts.InstanceDescription.deploy(
            web3,
            mixer_src,
            mixer_name,
            deployer_eth_address,
            deployer_eth_private_key,
            deploy_gas,
            compiler_flags={},
            args=constructor_parameters)
        mixer_instance = mixer_description.instantiate(web3)
        client = MixerClient(web3, prover_config, mixer_instance)
        return client, mixer_description
 

Here is the call graph for this function:

deposit()

str zeth.core.mixer_client.MixerClient.deposit	(		self,
		ProverClient	prover_client,
		MerkleTree	mk_tree,
		ZethAddress	zeth_address,
		str	sender_eth_address,
		Optional[bytes]	sender_eth_private_key,
		EtherValue	eth_amount,
		Optional[List[Tuple[ZethAddressPub, EtherValue]]]	outputs = None,
		Optional[EtherValue]	tx_value = None
	)

Definition at line 321 of file mixer_client.py.

    def deposit(
            self,
            prover_client: ProverClient,
            mk_tree: MerkleTree,
            zeth_address: ZethAddress,
            sender_eth_address: str,
            sender_eth_private_key: Optional[bytes],
            eth_amount: EtherValue,
            outputs: Optional[List[Tuple[ZethAddressPub, EtherValue]]] = None,
            tx_value: Optional[EtherValue] = None
    ) -> str:
        if not outputs or len(outputs) == 0:
            outputs = [(zeth_address.addr_pk, eth_amount)]
        return self.joinsplit(
            prover_client,
            mk_tree,
            sender_ownership_keypair=zeth_address.ownership_keypair(),
            sender_eth_address=sender_eth_address,
            sender_eth_private_key=sender_eth_private_key,
            inputs=[],
            outputs=outputs,
            v_in=eth_amount,
            v_out=EtherValue(0),
            tx_value=tx_value)
 

Here is the call graph for this function:

joinsplit()

str zeth.core.mixer_client.MixerClient.joinsplit	(		self,
		ProverClient	prover_client,
		MerkleTree	mk_tree,
		OwnershipKeyPair	sender_ownership_keypair,
		str	sender_eth_address,
		Optional[bytes]	sender_eth_private_key,
		List[Tuple[int, api.ZethNote]]	inputs,
		List[Tuple[ZethAddressPub, EtherValue]]	outputs,
		EtherValue	v_in,
		EtherValue	v_out,
		Optional[EtherValue]	tx_value = None,
		Optional[ComputeHSigCB]	compute_h_sig_cb = None
	)

Create and broadcast a transactions that calls the mixer with the given
parameters. Requires a ProverClient for proof generation.

Definition at line 346 of file mixer_client.py.

    def joinsplit(
            self,
            prover_client: ProverClient,
            mk_tree: MerkleTree,
            sender_ownership_keypair: OwnershipKeyPair,
            sender_eth_address: str,
            sender_eth_private_key: Optional[bytes],
            inputs: List[Tuple[int, api.ZethNote]],
            outputs: List[Tuple[ZethAddressPub, EtherValue]],
            v_in: EtherValue,
            v_out: EtherValue,
            tx_value: Optional[EtherValue] = None,
            compute_h_sig_cb: Optional[ComputeHSigCB] = None) -> str:
        """
        Create and broadcast a transactions that calls the mixer with the given
        parameters. Requires a ProverClient for proof generation.
        """
        mix_params, _ = self.create_mix_parameters_and_signing_key(
            prover_client,
            mk_tree,
            sender_ownership_keypair,
            sender_eth_address,
            inputs,
            outputs,
            v_in,
            v_out,
            compute_h_sig_cb)
        return self.mix(
            mix_params,
            sender_eth_address,
            sender_eth_private_key,
            tx_value or v_in)
 

Here is the call graph for this function:

Here is the caller graph for this function:

mix()

str zeth.core.mixer_client.MixerClient.mix	(		self,
		MixParameters	mix_params,
		str	sender_eth_address,
		Optional[bytes]	sender_eth_private_key,
		EtherValue	tx_value,
		Optional[int]	call_gas = None
	)

Given a MixParameters object, create and broadcast a transaction
performing the appropriate mix call.

Definition at line 379 of file mixer_client.py.

    def mix(
            self,
            mix_params: MixParameters,
            sender_eth_address: str,
            sender_eth_private_key: Optional[bytes],
            tx_value: EtherValue,
            call_gas: Optional[int] = None) -> str:
        """
        Given a MixParameters object, create and broadcast a transaction
        performing the appropriate mix call.
        """
        mixer_call = self._create_mix_call(mix_params)
        tx_hash = contracts.send_contract_call(
            self.web3,
            mixer_call,
            sender_eth_address,
            sender_eth_private_key,
            tx_value,
            call_gas)
        return tx_hash.hex()
 

Here is the call graph for this function:

Here is the caller graph for this function:

mix_call()

bool zeth.core.mixer_client.MixerClient.mix_call	(		self,
		MixParameters	mix_params,
		str	sender_eth_address,
		EtherValue	tx_value,
		Optional[int]	call_gas = None
	)

Call the mix method (executes on the RPC host without creating a
transaction). Returns True if the call succeeds. False, otherwise.

Definition at line 400 of file mixer_client.py.

    def mix_call(
            self,
            mix_params: MixParameters,
            sender_eth_address: str,
            tx_value: EtherValue,
            call_gas: Optional[int] = None) -> bool:
        """
        Call the mix method (executes on the RPC host without creating a
        transaction). Returns True if the call succeeds. False, otherwise.
        """
        mixer_call = self._create_mix_call(mix_params)
        try:
            contracts.local_contract_call(
                mixer_call,
                sender_eth_address,
                tx_value,
                call_gas)
            return True
 
        except ValueError:
            print("error executing mix call:")
            traceback.print_exc()
 
        return False
 

Here is the call graph for this function:

Member Data Documentation

mixer_instance

zeth.core.mixer_client.MixerClient.mixer_instance

Definition at line 266 of file mixer_client.py.

prover_config

zeth.core.mixer_client.MixerClient.prover_config

Definition at line 265 of file mixer_client.py.

web3

zeth.core.mixer_client.MixerClient.web3

Definition at line 264 of file mixer_client.py.

---

The documentation for this class was generated from the following file:

• /home/runner/work/zeth/zeth/client/zeth/core/mixer_client.py