Device Methods#

cuPQC-Hash Hash Function Device Methods#

In the following method descriptions, HASH is used as a placeholder for the cuPQC-Hash descriptor object that is instantiated with a specific hash algorithm.

reset#

__device__ void HASH::reset()

Reset the hash state to the initial state. This should be called before the first call to update().

update#

__device__ void HASH::update(
const uint8_t *message,
const size_t message_length
)

Append a message into the hash state. This may be called multiple times to incrementally update a single message. This is for non-Poseidon2 hash functions.

Parameters:

  • message – Buffer containing the message.

  • message_length – Length of the message buffer.

__device__ void HASH::update(
const uint32_t *message,
const size_t message_length
)

Append a message into the hash state. This may be called multiple times to incrementally update a single message. This is only available for Poseidon2 hash functions.

Parameters:

  • message – Buffer containing the message.

  • message_length – Length of the message buffer.

finalize#

__device__ void HASH::finalize()

Finalizes the hash state. This should be called after the last call to update(), and before the first call to digest().

digest#

__device__ void HASH::digest(
uint8_t *digest,
const size_t digest_length
)

Extract the hash state into a digest. This may be called multiple times to incrementally digest a single message.

Parameters:

  • digest – Buffer to which the digest will be written. Must be of length digest_length, and 8-byte aligned.

  • digest_length – Length of the digest buffer.

__device__ void HASH::digest(
uint32_t *digest,
const size_t digest_length
)

Extract the hash state into a digest. This may be called multiple times to incrementally digest a single message. This is only available for Poseidon2 hash functions.

Parameters:

  • digest – Buffer to which the digest will be written. Must be of length digest_length, and 8-byte aligned.

  • digest_length – Length of the digest buffer.

cuPQC-Hash Merkle Tree Objects#

template<uin32_t N, class Hash, typename Precision>
class tree

A Merkle Tree object. This object is a convenience container for the Merkle Tree Data.

Parameters: - N: The number of leaves in the base of the tree. - HASH: The hash function used to generate the Merkle Tree. This will be a cuPQC-Hash hash object. - Precision: The data type of the leaves of the Merkle Tree.

Members: - size: The size of the Merkle Tree Data. This is 2 * N - 1 where N is the number of leaves in the base of the tree. - digest_size: The digest size of the hash function used to generate the Merkle Tree. This is the length of the Precision array that each node is. - nodes: A pointer to the Merkle Tree Data. This is a global memory array containing 2 * N - 1 nodes, where N is the number of leaves in the base of the tree. Each node is of type Precision, with length digest_size where digest_size is the digest size of the hash function used to generate the Merkle Tree. Note that for Hash functions that do not have a digest size, a hash output size is fixed and can be accessed via the digest_size member.

Functions: - allocate_tree: Allocates the Merkle Tree Data to global memory. This is a host function, and is not available on the device. - free_tree: Frees the Merkle Tree Data from global memory. This is a host function, and is not available on the device. - root: A function that returns a pointer to the root of the Merkle Tree.

template<uin32_t N, class Hash, typename Precision>
class proof

A Proof object generated from a Merkle Tree, used to verify a leaf in the Merkle Tree. This object is a convenience container for the Proof Data.

Parameters: - N: The number of leaves in the base of the tree. - HASH: The hash function used to generate the Merkle Tree. This is the same as the hash function used to generate the Merkle Tree Data. - Precision: The data type of the leaves of the Merkle Tree. This is the same as the data type of the leaves of the Merkle Tree Data.

Members: - size: The size of the Merkle Tree Data. This is log2(N) where N is the number of leaves in the base of the tree. - digest_size: The digest size of the hash function used to generate the Merkle Tree. This is the length of the Precision array that each node is. - nodes: A pointer to the Merkle Tree Proof Data. This is a global memory array containing log2(N) nodes, where N is the number of leaves in the base of the tree that the proof is generated from. Each node is of type Precision, with length digest_size where digest_size is the digest size of the hash function used to generate the Merkle Tree. Note that for Hash functions that do not have a digest size, a hash output size is fixed and can be accessed via the digest_size member. - indices: A global memory array of 32-bit unsigned integers containing log2(N) indices, these indices are the locations of the proof nodes in the original tree.

Functions: - allocate_proof: Allocates the Proof Data to global memory. This is a host function, and is not available on the device. - free_proof: Frees the Proof Data from global memory. This is a host function, and is not available on the device.

cuPQC-Hash Merkle Tree Device Methods#

In the following method descriptions, MERKLE is used as a placeholder for the cuPQC-Hash Merkle Tree descriptor object that is instantiated with a specific Merkle Tree size and precision.

create_leaf#

template<class HASH, typename Precision>
__device__ void MERKLE::create_leaf(
Precision *leaf,
const Precision *data,
HASH &hash,
const size_t inbuf_len
)

Create a leaf in the Merkle Tree.

generate_tree#

template<class HASH, typename Precision>
__device__ void MERKLE::generate_tree(
HASH &hash,
tree<N, HASH, Precision> &merkle_tree
)

Generate a Merkle Tree. This should be called after the last call to update(), and before the first call to digest().

Parameters:

  • hash – The hash function used to generate the Merkle Tree.

  • merkle_tree – The Merkle Tree object to generate.

generate_sub_tree#

template<class HASH, typename Precision>
__device__ void MERKLE::generate_sub_tree(
HASH &hash,
tree<N, HASH, Precision> &merkle_tree,
const size_t sub_tree_num
)#

Generate a sub tree of the Merkle Tree. This API function is defined by the SubMerkle Tree object, but operates on the larger tree. This can be used to generate a larger tree distributed across multiple blocks. This function will compute a blocks worth of the tree in a single call.

Parameters:

  • hash – The hash function used to generate the Merkle Tree.

  • merkle_tree – The Merkle Tree object to generate the sub tree of.

  • sub_tree_num – The number of the sub tree to generate.

generate_proof#

template<class HASH, typename Precision>
__device__ void MERKLE::generate_proof(
proof<N, HASH, Precision> &proof,
const Precision *leaf,
const uint32_t leaf_index,
const tree<N, HASH, Precision> &merkle_tree
)

Generate a proof for a leaf in the Merkle Tree.

Parameters:

  • proof – The proof object to generate.

  • leaf – The leaf to generate a proof for.

  • leaf_index – The index of the leaf to generate a proof for.

verify_proof#

template<class HASH, typename Precision>
__device__ bool MERKLE::verify_proof(
const proof<N, HASH, Precision> &proof,
const Precision *leaf,
const uint32_t leaf_index,
const Precision *root,
HASH &hash
)

Verify a proof for a leaf in the Merkle Tree.

Parameters:

  • proof – The proof object to verify.

  • leaf – The leaf to verify a proof for.

  • leaf_index – The index of the leaf to verify a proof for.