Attestations from MPC nodes
Attestations provide cryptographic proof that specific data has been generated according to an MPC contract's rules. In an MPC (Multi-Party Computation) system, each node signs both the data and the contract address, ensuring trust and transparency. Once all nodes have signed, the attested data can be securely shared with external parties.
For example, in an MPC auction contract, nodes can attest to the auction result, allowing anyone to verify the outcome without needing direct access to the computation.
In this article, we explore how attestations work.
- First, we explain how to make the MPC nodes attest to data in an MPC contract, and we show a hands-on example in Browser.
- We explain how to fetch and decode attestations in both TypeScript and Java.
- Finally, we show how to verify attestation signatures in TypeScript and Java.
Attesting data in an MPC contract
Attesting is a ZkStateChange. Therefore, for MPC nodes to attest to data, create an attestation
request with serialized data and add it to the ZK state changes.
MPC nodes can attest to any relevant contract data, depending on the use case. Once attested, the data is stored in the contract state, where nodes sign it and include the contract address.
The following example from the Second Price Auction MPC contract
demonstrates how nodes attest to an AuctionResult, which includes the winning bidder's ID and the final price.
This is executed after the auction result is computed.
In this type of auction, each participant submits a bid, with the highest bidder winning —
but only paying the amount of the second-highest bid.
Attesting in an MPC contract
/// Automatically called when the auction result is declassified. Updates state to contain result,
/// and requests attestation from nodes.
#[zk_on_variables_opened]
fn open_auction_variable(
context: ContractContext,
state: ContractState,
zk_state: ZkState<SecretVarMetadata>,
opened_variables: Vec<SecretVarId>,
) -> (ContractState, Vec<EventGroup>, Vec<ZkStateChange>) {
assert_eq!(
opened_variables.len(),
2,
"Unexpected number of output variables"
);
assert_eq!(
zk_state.data_attestations.len(),
0,
"Auction must have exactly zero data_attestations at this point"
);
let auction_result = AuctionResult {
winner: read_variable(&zk_state, opened_variables.first()),
second_highest_bid: read_variable(&zk_state, opened_variables.get(1)),
};
let attest_request = ZkStateChange::Attest {
data_to_attest: serialize_as_big_endian(&auction_result),
};
(state, vec![], vec![attest_request])
}
When the computation is complete, the result of the auction is revealed. The contract then orders the MPC nodes to attest to the result data.
When the MPC nodes have all attested to the data, it is added it to the state of the contract, as shown below.
We use the action hook zk_on_attestation_complete to do this.
Reading the attested data in an MPC contract
/// Automatically called when some data is attested
#[zk_on_attestation_complete]
fn auction_results_attested(
context: ContractContext,
mut state: ContractState,
zk_state: ZkState<SecretVarMetadata>,
attestation_id: AttestationId,
) -> (ContractState, Vec<EventGroup>, Vec<ZkStateChange>) {
assert_eq!(
zk_state.data_attestations.len(),
1,
"Auction must have exactly one attestation"
);
let attestation = zk_state.get_attestation(attestation_id).unwrap();
assert_eq!(attestation.signatures.len(), 4, "Must have four signatures");
assert!(
attestation.signatures.iter().all(|sig| sig.is_some()),
"Attestation must be complete"
);
let auction_result = AuctionResult::rpc_read_from(&mut attestation.data.as_slice());
state.auction_result = Some(auction_result);
(state, vec![], vec![ZkStateChange::ContractDone])
}
Example in Browser
As a practical illustration of attestations in action, consider their use in a deployed second price auction MPC contract in Browser. Once the winner of the second-price auction is determined, the MPC nodes attest to the correctness of the computation by verifying both the highest bid and the second-highest bid. To test this, you can deploy and interact with MPC contracts in Browser, check out this article.
Info
To run this example, follow the local deployment guide. This allows you to view the state of the blockchain and the contracts that you deploy and interact with.
-
Deploy a second price auction MPC contract by providing either the contract's PCB-file or its ABI and ZKWA files. Here is an example of a deployed second price auction contract.
-
Call the action 'register bidder' 3 times to register bidders, and wait until at least 3 bidders have given their bid (i.e. has sent secret input to the contract). We can see the amount of secret inputs in the contract's ZK state ('ZK data').
-
Call the action 'compute winner' to compute the winner of the second price auction.
-
Once the winner has been computed by the MPC nodes, go to 'Attestation' to see the signatures and the data that the MPC nodes has signed. In this case, the attestation data is a base64 encoding of the auction result.
In this example contract, the attested data - the auction result - is also stored in the contract state, such that everyone can read who the winner is.
Fetching and decoding attestations
Attestations are stored in the contract state. Each attestation is a key-value pair, where the key is the attestation ID and the value contains encoded data and signatures. The attestation value consists of a base64 encoding of the serialized attested data, together with a list of signatures from the MPC nodes.
The MPC nodes sign the encoded data and additional information:
- The string "ZK_REAL_ATTESTATION"
- The contract address
- The base64 encoded serialized attested data
This is how attestations are represented in the state:
Attestation in the contract state
"serializedContract": {
"attestations": [
{
"key": 1,
"value": {
"data": {
"data": "AAAAAgAAJxA="
},
"id": 1,
"signatures": [
"006c0f546209e83028bcb6c095c75a9552c52492fe5494ba640bed74837d68e3bf26b6238508e982e037466f8a53b2b6a17dfd9f4b6526913ef86f61a5d11789cc",
"0067a50ad74467cefb9b32efbc5661bb817ae0d8d650f8c42f8f6cd6a90078bc8102f0fc840deb17cdf0e3d6274e7b8b50033f431b18f88e4456ce76ff90bb3e9d",
"011c09ad0111c023050006a29feaece86c87be3d604fd6ecce8825badeb0c0c9a051aa6f4896d1b1fce173809d72ceaa97312cc87083dc432f833a35360684136f",
"01704843ce10f72bf524d8a2f099ff5dd504f4fe1496e9d6fc47903c66d1a1db81633d8f50c27ca8ad0296c6b1891df15972c25ad58784c1369b9dfa1dcc500e01"
]
}
}
],
...
}
To fetch an attestation, consisting of the encoded serialized data and the signatures, from the state,
use an HTTP-request to the chain: http://localhost:9432/blockchain/contracts/{contractAddress}.
To read the actual attested data, we have to decode and deserialize the data.
In this article's example, the data is an AuctionResult.
We can use the generated code of the MPC auction to deserialize the decoded data. We will see how
this is done in the Java and TypeScript examples below.
It's important to note that attested data consists of raw bytes and may not inherently have a known type.
If the attested data does have a defined type, such as a struct like AuctionResult,
you can use ABI codegen to create a method for decoding the data efficiently.
Otherwise, you can manually deserialize and decode the data.
To automate decoding, use these commands to generate Java or TypeScript code with an AuctionResult deserializer:
cargo pbc abi codegen --java (or --ts) --deserialize AuctionResult
path/to/zk_second_price.abi path/to/output/ZkSecondPrice.java (or .ts)
The most efficient way to fetch and decode attestation of an AuctionResult in a second price auction MPC contract is
to use a client to handle the HTTP-requests.
In Java and TypeScript, the zk-client is used for fetching attestations from the contract state. The zk-client is also used for handling secrets in MPC contracts. You can read more about how to send and fetch secrets with the zk-client.
We will see how to use it in the following examples.
Info
- The URL http://docker:9432 in the examples is used for local deployment.
- The contract address and private key in the examples are placeholders.
- Replace them with your own private key and deployed contract address for the examples to work.
Using TypeScript
To fetch an attestation from a contract, call the ZkClient's getAttestationWithSignatures method
and pass the MPC contract address and the attestation id as arguments.
In this example, there is only one attestation, so the id is 1.
We use the generated code in the TypeScript-class ZkSecondPrice implicitly to deserialize
the attested data into an AuctionResult, when we call the method deserializeSpecialAuctionResult.
Fetching attestations in TypeScript
async function attestationExample() {
// Blockchain address of the contract and the reader node URL
const secondPriceAuctionAddress = "000000000000000000000000000000000000000001";
const blockchainUrl = "http://docker:9432";
// Blockchain- and ZK-Client
const client = new Client(blockchainUrl, 0);
const realZkClient = await RealZkClient.create(secondPriceAuctionAddress, client);
// Private key for authentication
const privateKey = "myprivatekey";
const authentication = new SenderAuthenticationKeyPair(
CryptoUtils.privateKeyToKeypair(privateKey)
);
const attestation: Attestation =
await realZkClient.getAttestationWithSignatures(secondPriceAuctionAddress, 1);
// Decode and deserialize the secret
const decodedData = Buffer.from(attestation.data, "base64");
const auctionResult = deserializeSpecialAuctionResult(decodedData);
console.log(auctionResult.secondHighestBid);
}
This example logs the second-highest bid of the auction.
Using Java
To fetch an attestation from a contract, call the ZkClient's getAttestationWithSignatures method
and pass the MPC contract address and the attestation id as arguments.
In this example, there is only one attestation, so the id is 1.
We use the generated code in the Java-class ZkSecondPrice to deserialize the attested data into an AuctionResult.
Fetching attestations in Java
public static void main(final String[] args) {
// Address of a deployed second price auction contract
BlockchainAddress secondPriceAuctionAddress =
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(secondPriceAuctionAddress, webClient, blockchainClient);
String privateKey = "myprivatekey";
SenderAuthenticationKeyPair keyPair = SenderAuthenticationKeyPair.fromString(privateKey);
// The attestation contains the data and a list of the MPC nodes' signatures
RealZkClient.Attestation attestation =
zkClient.getAttestationWithSignatures(secondPriceAuctionAddress, 1);
// Decode and deserialize the attested data
byte[] decodedData = Base64.getDecoder().decode(attestation.data());
ZkSecondPrice.AuctionResult auctionResult = ZkSecondPrice.deserializeSpecialAuctionResult(decodedData);
System.out.println(auctionResult.secondHighestBid());
}
The above example prints the second-highest bid of the auction.
Verifying the signatures
When you have fetched an attestation consisting of data and signatures, you want to validate both that it comes from the correct contract, and that it was signed by the MPC nodes allocated to that contract.
The attestation contains:
- The attested data (serialized and base 64 encoded)
- Four signatures of a hash of the following:
- The string "ZK_REAL_ATTESTATION"
- The MPC contract address
- The attested data
Verify the attestation signatures by following these steps:
- Fetch the attestation from the contract state.
- Recreate the signed hash by hashing the same values:
- The string "ZK_REAL_ATTESTATION"
- The MPC contract address
- The attested data from the fetched attestation
- Use the hash to recover the signer's address and public key for each signature in the attestation.
- Compare each recovered address and public key to the known address and public key of each MPC nodes. If they all match, the signatures are genuine.
Using TypeScript
Verifying signatures in TypeScript
import { ec } from "elliptic";
async function attestationExample() {
// Blockchain address of the contract and the reader node URL
const secondPriceAuctionAddress = "037f0b5cc595b8cc4867fa5cb04ca0ab093d58aa5e";
const blockchainUrl: string = "https://node1.testnet.partisiablockchain.com";
// Blockchain- and ZK-Client
const client = new Client(blockchainUrl);
const realZkClient = RealZkClient.create(secondPriceAuctionAddress, client);
const attestation: Attestation = await realZkClient.getAttestationWithSignatures(
secondPriceAuctionAddress,
1
);
const zkContract = await client.getContractState(secondPriceAuctionAddress);
if (zkContract === undefined) {
throw new Error("Couldn't get contract data");
}
const nodes: Engine[] = zkContract.serializedContract.engines.engines;
const signatures: string[] = attestation.signatures;
const hashedData = CryptoUtils.hashBuffers([
Buffer.from("ZK_REAL_ATTESTATION", "utf-8"),
Buffer.from(secondPriceAuctionAddress, "hex"),
attestation.data,
]);
for (let i = 0; i < 4; i++) {
const signature = Buffer.from(signatures[i], "hex");
const node = nodes[i];
const address = node.identity;
const publicKey = node.publicKey;
const elliptic = new ec("secp256k1");
const recoveryParam = signature[0];
const recoveredKeyPoint = elliptic.recoverPubKey(
hashedData,
{
recoveryParam,
r: signature.subarray(1, 33),
s: signature.subarray(33, 65),
},
recoveryParam,
"hex"
);
const ecKeyPair = elliptic.keyFromPublic(recoveredKeyPoint);
const recoveredAddress = CryptoUtils.keyPairToAccountAddress(ecKeyPair);
const recoveredKey = Buffer.from(ecKeyPair.getPublic(true, "array")).toString("base64");
expect(address).toEqual(recoveredAddress);
expect(publicKey).toEqual(recoveredKey);
}
}
Using Java
Verifying signatures in Java
public static void main(final String[] args) {
// Address of a deployed second price auction contract
BlockchainAddress secondPriceAuctionAddress =
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(secondPriceAuctionAddress, webClient, blockchainClient);
// Use the zk client to get the attestation signatures
RealZkClient.Attestation attestation =
zkClient.getAttestationWithSignatures(secondPriceAuctionAddress, 1);
Hash signedData =
Hash.create(
stream -> {
stream.write("ZK_REAL_ATTESTATION".getBytes(StandardCharsets.UTF_8));
secondPriceAuctionAddress.write(stream);
stream.write(Base64.getDecoder().decode(attestation.data()));
});
// Verify the attestation signatures
assertThat(attestation.signatures().size()).isEqualTo(4);
JsonNode engines =
blockchainClient
.getContractState(secondPriceAuctionAddress)
.serializedContract()
.get("engines")
.get("engines");
for (int i = 0; i < 4; i++) {
JsonNode engine = engines.get(i);
String address = engine.get("identity").textValue();
String publicKey = engine.get("publicKey").textValue();
Signature signature = attestation.signatures().get(i);
assertThat(address).isEqualTo(signature.recoverSender(signedData).writeAsString());
assertThat(publicKey).isEqualTo(signature.recoverPublicKey(signedData).toString());
}
}