Skip to content

Sending Secrets

In this article, you will see how to send secrets to the nodes in an MPC smart contract both on- and off-chain.

You can learn how to fetch secrets from an MPC smart contract in this article.

Sending Secrets to the Nodes

Secret inputs to MPC contracts are handled using secret sharing.

The goal is to distribute secret shares to the MPC nodes allocated to the specific MPC contract. We also want to keep the shares private, such that each node can only read the share specified for them.

There are two ways of sending a secret input to an MPC contract: on-chain and off-chain.

  1. On-chain: The secret shares are encrypted and included in a transaction to the MPC contract and stored on chain. Each node then reads and decrypts their share from the MPC state of the MPC contract.
  2. Off-chain: The secret shares are sent directly to the nodes. Additionally, a hash of each share is included in a transaction to the MPC contract and stored on chain. In this way, each node can validate their received share by comparing it to the hash.

In both cases, a transaction is sent to the chain. A common way to communicate with the chain is by sending HTTP-requests to a reader node endpoint.

If the secret input is sent off-chain, we must be able to communicate directly with the nodes. A common way to do so is by sending an HTTP-request to an MPC node endpoint.

Sending Secrets On-Chain

To input a secret on-chain, users must send a transaction containing encrypted secret shares, as illustrated by this model:

on-chain-simple.svg

The different methods for inputting secrets are all marked by on_secret_variable in the smart contract. A contract can have multiple actions for inputting secrets to the contract.

To send the secret, the sender must have access to the public keys of all the MPC nodes. Usually MPC contracts have four participating nodes.

In more detail, to send a secret on-chain the sender must:

  1. Create and encrypt a secret input:
    • Serialize the secret input to a CompactBitArray
    • Create one secret share for each node (usually four) from the secret using randomness for security.
    • Create an ephemeral (temporary) key pair.
    • For each node, generate a shared key from the node's public key and the private key of the ephemeral key pair.
    • Encrypt each share with AES encryption using the shared key. The private key is ephemeral such that two identical shares will be encrypted differently in order to prevent replay attacks.
  2. Create the public payload of the function call:
    • Include its shortname in the contract.
    • Include any public arguments.

The steps to create and encrypt the shares are illustrated in the image below:

./graphics/sending-secrets-on-chain-1.svg

  1. Create a transaction to send to the MPC contract with a payload consisting of:

    • 0x05 to indicate that this transaction is part of sending a secret input on-chain,
    • The public payload,
    • The encrypted secret shares,
    • The public key of the ephemeral key pair.

  2. Send the transaction to the blockchain.

    • This updates the MPC state of the MPC contract with a pending input containing the transaction payload, which the nodes can read.

The steps for creating and sending the transaction are shown in the image below:

./graphics/sending-secrets-on-chain-2.svg

Once the transaction has been sent, the MPC nodes can use the secrets. Here's a breakdown of how they do it:

  1. Read the pending input in the MPC state of the MPC contract.
  2. Compute the shared key using the public key of the ephemeral key and their own private key.
  3. Decrypt their share of the secret.
  4. Mask the share and send a transaction with the masked share to the MPC contract. When the contract has received 3 shares, it checks that the reconstructed masked secret is valid and calls the on_variable_inputted action in the MPC contract.

Tip

Blindings are random bytes which conceal the value of a secret share when hashed alongside the share. Maskings are blindings using some preprocessed material for the MPC contract.

Example in the terminal

You can send a secret input on-chain to an Average Salary MPC smart contract through your terminal.

You can also send a secret on-chain through Browser. The steps are the same as in the off-chain example, just toggle the 'Send input off-chain'-button.

Sending a secret input with CLI is similar to sending a public action transaction.

Requirements

To run this example, you will need:

  • To set up a Platform dev runner and connect the CLI with the config. Follow the local integration guide.
  • The ZKWA and ABI (or PBC) of an Average Salary MPC smart contract (learn how to generate it here).
  • A private key

1. Deploy the contract
Deploy the Average Salary contract using its ZKWA and ABI (or PBC), either in the Browser frontend or with the deploy command in the terminal:

cargo pbc transaction deploy path/to/average-salary.wasm path/to/average-salary.abi

Once you have deployed the contract and have its blockchain address averageSalaryAddress, you can interact with it in the command line of your terminal.

2. Input a secret
Send secret input 123456 to the add_salary function in the average salary contract with this command:

cargo pbc transaction action averageSalaryAddress add_salary 123456 --gas=10000 --privatekey path/to/private/key.txt

3. Verify secret input

Verify that the secret has been input by fetching it from the contract (read more about secret fetching here). Call the contract secret show command, where you supply the id and type of the secret (here: 1 and i32):

cargo pbc contract secret show averageSalaryAddress 1 i32 --privatekey path/to/private/key.txt

This will output the secret salary you sent, for example 123456.

Tip

You can see all interactions with the contract, the contract state and the ZK state in the Browser frontend at http://docker:8300/contracts/averageSalaryAddress.

Sending Secrets Off-Chain

To input a secret off-chain users must send a transaction containing a hash of the blinded shares to the chain, as illustrated by this model:

sending-secrets-off-chain.svg

In more detail, to send a secret off-chain the sender must:

  1. Create secret input commitments:

    • Serialize it to a CompactBitArray.
    • Create one secret share for each node (usually four) from the secret using randomness for security.
    • Apply blindings to the shares using randomness. Otherwise the shares could easily be guessed for small input sizes, since hashes of the shares are stored directly on the blockchain.
    • Create a share commitment (i.e., a hash of the blinded share) for each blinded share.

  2. Create the public payload of the function call:

    • Include its shortname in the contract.
    • Include any public arguments.

The steps to create commitments (hash) the secret shares are illustrated in the image below:

./graphics/sending-secrets-off-chain-1.svg

  1. Create a transaction to send to the MPC contract with a payload consisting of:
    • 0x04 to indicate that this transaction is part of sending a secret input off-chain
    • The public payload
    • The share commitments (hashed of secret shares).
  2. Send the transaction to the blockchain.
    • This updates the MPC state of the MPC contract with a pending input containing the transaction payload, which the nodes can read.
  3. Send the blinded shares to the nodes together with a transaction hash.
    • The transaction hash allows the nodes to identify the associated pending input in the MPC state.

The steps for creating and sending the transaction and sending the shares to the MPC nodes are illustrated in the figure below:

./graphics/sending-secrets-off-chain-2.svg

Once the transaction and the blinded shares have been sent, the MPC nodes can open the secret shares. Here's a breakdown of how they do it:

  1. Read the pending input in the MPC state of the MPC contract.
  2. Receive a blinded share and a transaction hash matching the pending input.
  3. Compute a hash of the received blinded share and compare it to the one from the pending input.
  4. If the hashes are equal, unblind and then mask the share.
  5. Send a transaction with the blinded share to the MPC contract. When the contract has received 3 masked shares, it checks that the reconstructed masked secret is valid, and calls the on_variable_inputted action in the MPC contract.

Tip

Blindings are random bytes which conceals the value of a secret share when hashed alongside the share. Maskings are blindings using some preprocessed material for the MPC contract.

Example in Browser

You can use the Browser frontend of your local deployment to send secrets both off-chain and on-chain. This method is a quick way to test that your MPC contract is running correctly and is able to receive secrets.

Requirements

To follow this example you need to have a running local deployment. This should make your Browser accessible at http://docker:8300/.

We use an Average Salary MPC smart contract in this example.

To deploy an MPC smart contract, you have to provide the contract's ABI- and ZKWA-files or its PBC-file. For example, to deploy an average salary contract, we use average_salary.abi and average_salary.zkwa. You can read more about deploying smart contracts and generating the PBC-, ABI- and ZKWA-files in this article.

Here's a walkthrough of how to deploy the average salary contract in Browser using screenshots. You can click on the images to expand them.

1. Deploy the Contract

Read here how to deploy the contract. After you have successfully deployed the MPC contract, you can see an overview of it:

./graphics/deployed-zk-browser.png

2. Input a Secret

The average salary contract has one action, add_salary, which takes a secret input. The secret input is an integer (i32) representing the sender's salary.

Click on the Add salary secret interaction to give a secret input:

./graphics/interact-secret-browser.png

Type the secret input (here we chose 123456) and click ADD SALARY:

Tip

To send the secret off-chain instead of on-chain, untoggle the 'Send input off-chain'-button.

./graphics/add-salary-browser.png

3. Verify secret input

Click on "ZK data" to verify that a secret input has been sent to the contract:

./graphics/zk-data-browser.png

Sending secrets in your application

You can send secrets programmatically in Java and TypeScript, both on-chain and off-chain. Additionally, you can send secrets with your terminal using Partisia CLI.

The Partisia Platform provides a library to interact with the nodes and the blockchain. This contains a Java and a TypeScript zk-client which facilitates communication with the MPC nodes (HTTP-request to an MPC node endpoints) and the chain (HTTP-request to a reader node endpoint).

To use the following code examples, update the following fields with appropriate values:

  • privateKey – Use your own private key.
  • averageSalaryAddress – Provide the address of a deployed contract. Read more about deploying contracts here.
  • blockchainUrl – We provide http://docker:9432 as the blockchain URL. You can use this if you have a running local deployment, as described here.

Tip

You can see the transactions you send to the contract at http://docker:8300/contracts/averageSalaryAddress. This also shows you all interactions with the contract, the contract state and the ZK state.

Sending Secrets On-chain

These code examples demonstrate how to send on-chain the secret input 123456 (of type i32) to the add_salary action within the Average Salary MPC smart contract.

The zk-client facilitates building a transaction with the serialized secret, which is sent to the chain.

Using Typescript

The code initializes a Typescript ZkClient instance with the contract address of the Average Salary contract. This client is then used to build the transaction payload as described here. Subsequently, a BlockchainTransactionClient signs and sends the signed transaction to the blockchain, which is described here.

Sending on-chain input in TypeScript 
async function averageSalaryExample() {

  // Blockchain address of the contract and the reader node URL
  const averageSalaryAddress = "000000000000000000000000000000000000000001";
  const blockchainUrl = "http://docker:9432";

  // Blockchain- and ZK-Client
  const client = new Client(blockchainUrl, 0);
  const realZkClient = await RealZkClient.create(averageSalaryAddress, client);

  // Private key for authentication
  const privateKey = "myprivatekey";
  const authentication = new SenderAuthenticationKeyPair(
     CryptoUtils.privateKeyToKeypair(privateKey)
  );

  // Create and serialize the secret input
  const secretInput = 123456;
  const serializedSecretInput: CompactBitArray = BitOutput.serializeBits((out) =>
     out.writeSignedNumber(secretInput, 32)
  );

  // Public RPC of the action; here it is the shortname of the add_salary action.
  const addSalaryPublicRpc = Buffer.of(0x40);

  // Build the on-chain input transaction
  const onChainTransaction: Transaction = realZkClient.buildOnChainInputTransaction(
     authentication.getAddress(),
     serializedSecretInput,
     addSalaryPublicRpc
  );

  // Create the client - creates signatures and communicates with the chain
  const transactionClient = BlockchainTransactionClient.create(blockchainUrl, authentication);

  // Sign and send the transaction
  const gasCost = 10000;
  await transactionClient.signAndSend(
     {
        address: averageSalaryAddress,
        rpc: onChainTransaction.rpc,
     },
     gasCost
  );
}

Using Java

The code initializes a Java ZkClient instance with the contract address of the Average Salary contract. This client is then used to build the transaction payload as described here. Subsequently, a BlockchainTransactionClient signs and sends the signed transaction to the blockchain, which is described here.

Sending on-chain input in Java 
public final class ZkAverageSalaryTestDocumentation {

    public static void main(final String[] args) {

         // Address of a deployed average salary contract
         BlockchainAddress averageSalaryAddress =
              BlockchainAddress.fromString("000000000000000000000000000000000000000001");

         // Create a blockchain client. Provide the reader node URL and number of shards.
         BlockchainClient blockchainClient = BlockchainClient.create("http://docker:9432", 0);

         // Create a webclient for communicating with the nodes
         Client client =
             ClientBuilder.newBuilder()
                 .connectTimeout(30L, TimeUnit.SECONDS)
                 .readTimeout(30L, TimeUnit.SECONDS)
                 .build();
         WebClient webClient = new JerseyWebClient(client);

         // Create the zk client with the contract address, a webclient, and a blockchain client.
         RealZkClient zkClient = RealZkClient.create(averageSalaryAddress, webClient, blockchainClient);

         String privateKey = "myprivatekey";
         SenderAuthenticationKeyPair keyPair = SenderAuthenticationKeyPair.fromString(privateKey);

        // Create and serialize the secret input
        int secretInput = 123456;
        CompactBitArray serializedSecretInput =
            BitOutput.serializeBits(output -> output.writeSignedInt(123456, 32));

        // Public RPC of the action; here it is the shortname of the add_salary action.
        byte[] addSalaryPublicRpc = new byte[] {0x40};

        // Build the on-chain input transaction
        Transaction transaction =
            zkClient.buildOnChainInputTransaction(
                keyPair.getAddress(), serializedSecretInput, addSalaryPublicRpc);

        // Create a blockchain transaction client - creates signatures and communicates with the chain
        BlockchainTransactionClient transactionClient =
            BlockchainTransactionClient.create(blockchainClient, keyPair);

        // Sign and send the transaction to the chain
        int gasCost = 10000;
        transactionClient.signAndSend(transaction, gasCost);
    }
}

Sending Secrets Off-chain

These code examples demonstrate how to send off-chain the secret input 123456 (of type i32) to the add_salary action within the Average Salary MPC smart contract.

The zk-client facilitates building a transaction with the hashes of the serialized secret, which is sent to the chain. Afterward, the zk-client sends the blinded shares to the nodes off-chain.

Using Typescript

The code initializes a Typescript ZkClient instance with the contract address of the Average Salary contract. This client is then used to build the transaction payload and send the blinded shares directly to the nodes, as described here. Subsequently, a BlockchainTransactionClient signs and sends the signed transaction to the blockchain, which is described here.

Sending off-chain input in TypeScript 
async function averageSalaryExampleOffChain() {

  // Blockchain address of the contract and the reader node URL
  const averageSalaryAddress = "000000000000000000000000000000000000000001";
  const blockchainUrl = "http://docker:9432";

  // Blockchain- and ZK-Client
  const client = new Client(blockchainUrl, 0);
  const realZkClient = await RealZkClient.create(averageSalaryAddress, client);

  // Private key for authentication
  const privateKey = "myprivatekey";
  const authentication = new SenderAuthenticationKeyPair(
     CryptoUtils.privateKeyToKeypair(privateKey)
  );

  // Create and serialize the secret input
  const secretInput = 123456;
  const serializedSecretInput: CompactBitArray = BitOutput.serializeBits((out) =>
    out.writeSignedNumber(secretInput, 32)
  );

  // Public RPC of the action; here it is the shortname of the add_salary action.
  const addSalaryPublicRpc = Buffer.from([0x40]);

  // Build the transaction from the secret and the additional RPC
  const offChainInputTransaction: OffChainInput = realZkClient.buildOffChainInputTransaction(
    serializedSecretInput,
    addSalaryPublicRpc
  );

  // Create the client - creates signatures and communicates with the chain
  const transactionClient = BlockchainTransactionClient.create(blockchainUrl, authentication);

  // Sign and send the transaction to the chain
  const gasCost = 10000;
  const sentTransaction: SentTransaction = await transactionClient.signAndSend(
    {
      address: averageSalaryAddress,
      rpc: offChainInputTransaction.transaction.rpc,
    },
    gasCost
  );

  // Recursively wait for the inclusion of the transaction and its spawned events
  await transactionClient.waitForSpawnedEvents(sentTransaction);

  // Send the blinded shares and the transaction identifier  to the nodes
  await realZkClient.sendOffChainInputToNodes(
    averageSalaryAddress,
    authentication.getAddress(),
    sentTransaction.signedTransaction.identifier(),
    offChainInputTransaction.blindedShares
  );
}

Using Java

The code initializes a Java ZkClient instance with the contract address of the Average Salary contract. This client is then used to build the transaction payload and send the blinded shares directly to the nodes, as described here. Subsequently, a BlockchainTransactionClient signs and sends the signed transaction to the blockchain, which is described here.

Sending off-chain input in Java 
public static void main(final String[] args) {

    // Address of a deployed average salary contract
    BlockchainAddress averageSalaryAddress =
         BlockchainAddress.fromString("000000000000000000000000000000000000000001");

    // Create a blockchain client. Provide the reader node URL and number of shards.
    BlockchainClient blockchainClient = BlockchainClient.create("http://docker:9432", 0);

    // Create a webclient for communicating with the nodes
    Client client =
        ClientBuilder.newBuilder()
            .connectTimeout(30L, TimeUnit.SECONDS)
            .readTimeout(30L, TimeUnit.SECONDS)
            .build();
    WebClient webClient = new JerseyWebClient(client);

    // Create the zk client with the contract address, a webclient, and a blockchain client.
    RealZkClient zkClient = RealZkClient.create(averageSalaryAddress, webClient, blockchainClient);

    String privateKey = "myprivatekey";
    SenderAuthenticationKeyPair keyPair = SenderAuthenticationKeyPair.fromString(privateKey);

    // Create and serialize the secret input
    int secretInput = 123456;
    CompactBitArray serializedSecretInput =
            BitOutput.serializeBits(output -> output.writeSignedInt(123456, 32));

    // Public RPC of the action; here it is the shortname of the add_salary action.
    byte[] addSalaryPublicRpc = new byte[] {0x40};

    // Build the off-chain input transaction
    RealZkClient.OffChainInput offChainInputTransaction =
            zkClient.buildOffChainInputTransaction(serializedSecretInput, addSalaryPublicRpc);

    // Create a blockchain transaction client
    BlockchainTransactionClient transactionClient =
            BlockchainTransactionClient.create(blockchainClient, keyPair);

    // Send the transaction to the chain
    int gasCost = 10000;
    SentTransaction sentTransaction =
            transactionClient.signAndSend(offChainInputTransaction.transaction(), gasCost);

    // Recursively wait for the inclusion of the transaction and its spawned events
    transactionClient.waitForSpawnedEvents(sentTransaction);

    // Send the blinded shares and the transaction identifier to the nodes
    zkClient.sendOffChainInputToNodes(
            averageSalaryAddress,
            keyPair.getAddress(),
            sentTransaction.transactionPointer().identifier(),
            offChainInputTransaction.shares());
}