Elements Functions

int wally_asset_generator_from_bytes(const unsigned char *asset, size_t asset_len, const unsigned char *abf, size_t abf_len, unsigned char *bytes_out, size_t len)

Create an Asset Generator from an either an asset commitment or asset tag plus blinding factor.

Parameters:

  • asset – Asset Commitment or Tag to create a generator for.

  • asset_len – Length of asset in bytes. Must be ASSET_COMMITMENT_LEN or ASSET_TAG_LEN.

  • abf – Asset Blinding Factor (Random entropy to blind with). Must be NULL when asset is a commitment.

  • abf_len – Length of abf in bytes. Must be BLINDING_FACTOR_LEN if abf is non-NULL.

  • bytes_out – Destination for the resulting Asset Generator.

  • len – Size of bytes_out. Must be ASSET_GENERATOR_LEN.

Returns:

See Error Codes

int wally_ecdh_nonce_hash(const unsigned char *pub_key, size_t pub_key_len, const unsigned char *priv_key, size_t priv_key_len, unsigned char *bytes_out, size_t len)

Generate a rangeproof nonce hash via SHA256(ECDH(pub_key, priv_key).

Parameters:

  • pub_key – Public blinding key.

  • pub_key_len – Length of pub_key in bytes. Must be EC_PUBLIC_KEY_LEN

  • priv_key – Ephemeral (randomly generated) private key.

  • priv_key_len – Length of priv_key in bytes. Must be EC_PRIVATE_KEY_LEN.

  • bytes_out – Destination for the resulting nonce hash.

  • len – Size of bytes_out. Must be SHA256_LEN.

Note

The public blinding key can be retrieved from a confidential address using wally_confidential_addr_to_ec_public_key. If priv_key is invalid, then WALLY_ERROR is returned.

Note

The computation can also be performed with the private key corresponding to pub_key and the public key corresponding to priv_key giving the same result.

Returns:

See Error Codes

int wally_asset_final_vbf(const uint64_t *values, size_t num_values, size_t num_inputs, const unsigned char *abf, size_t abf_len, const unsigned char *vbf, size_t vbf_len, unsigned char *bytes_out, size_t len)

Generate the final value blinding factor required for blinding a confidential transaction.

Parameters:

  • values – Array of values in satoshi

  • num_values – Length of values, also the number of elements in all three of the input arrays, which is equal to num_inputs plus the number of outputs.

  • num_inputs – Number of elements in the input arrays that represent inputs. The number of outputs is implicitly num_values - num_inputs.

  • abf – Array of bytes representing num_values asset blinding factors.

  • abf_len – Length of abf in bytes. Must be num_values * BLINDING_FACTOR_LEN.

  • vbf – Array of bytes representing (num_values - 1) value blinding factors.

  • vbf_len – Length of vbf in bytes. Must be (num_values - 1) * BLINDING_FACTOR_LEN.

  • bytes_out – Buffer to receive the final value blinding factor.

  • len – Size of bytes_out. Must be BLINDING_FACTOR_LEN.

Returns:

See Error Codes

int wally_asset_scalar_offset(uint64_t value, const unsigned char *abf, size_t abf_len, const unsigned char *vbf, size_t vbf_len, unsigned char *bytes_out, size_t len)

Compute the scalar offset used for blinding a confidential transaction.

Parameters:

  • value – The value in satoshi.

  • abf – Asset blinding factor.

  • abf_len – Length of abf. Must be BLINDING_FACTOR_LEN.

  • vbf – Value blinding factor.

  • vbf_len – Length of vbf. Must be BLINDING_FACTOR_LEN.

  • bytes_out – Destination to receive the scalar offset.

  • len – Size of bytes_out. Must be EC_SCALAR_LEN.

Returns:

See Error Codes

int wally_asset_value_commitment(uint64_t value, const unsigned char *vbf, size_t vbf_len, const unsigned char *generator, size_t generator_len, unsigned char *bytes_out, size_t len)

Calculate a value commitment.

Parameters:
Returns:

See Error Codes

int wally_asset_rangeproof_get_maximum_len(uint64_t value, int min_bits, size_t *written)

Calculate the maximum size of a rangeproof.

Parameters:

  • value – The maximum possible value of the output in satoshi.

  • min_bits – The min_bits value that will be passed to wally_asset_rangeproof.

  • written – Destination for the maximum rangeproof size in bytes.

Returns:

See Error Codes

int wally_asset_rangeproof_with_nonce(uint64_t value, const unsigned char *nonce_hash, size_t nonce_hash_len, const unsigned char *asset, size_t asset_len, const unsigned char *abf, size_t abf_len, const unsigned char *vbf, size_t vbf_len, const unsigned char *commitment, size_t commitment_len, const unsigned char *extra, size_t extra_len, const unsigned char *generator, size_t generator_len, uint64_t min_value, int exp, int min_bits, unsigned char *bytes_out, size_t len, size_t *written)

Generate a rangeproof using a nonce.

Parameters:

  • value – Value of the output in satoshi.

  • nonce_hash – Nonce for rangeproof generation, usually from wally_ecdh_nonce_hash.

  • nonce_hash_len – Length of nonce_hash. Must be SHA256_LEN.

  • asset – Asset id of output.

  • asset_len – Length of asset. Must be ASSET_TAG_LEN.

  • abf – Asset blinding factor. Randomly generated for each output.

  • abf_len – Length of abf. Must be BLINDING_FACTOR_LEN.

  • vbf – Value blinding factor. Randomly generated for each output except the last, which is generate by calling wally_asset_final_vbf.

  • vbf_len – Length of vbf. Must be BLINDING_FACTOR_LEN.

  • commitment – Value commitment from wally_asset_value_commitment.

  • commitment_len – Length of commitment. Must be ASSET_COMMITMENT_LEN.

  • extra – Set this to the scriptPubkey of the output.

  • extra_len – Length of extra, i.e. scriptPubkey.

  • generator – Asset generator from wally_asset_generator_from_bytes.

  • generator_len – Length of generator. Must be ASSET_GENERATOR_LEN.

  • min_value – Recommended value 1.

  • exp – Exponent value. -1 >= exp >= 18. Recommended value 0.

  • min_bits – 0 >= min_bits >= 64. Recommended value 52.

  • bytes_out – Buffer to receive rangeproof.

  • len – Size of bytes_out. Passing ASSET_RANGEPROOF_MAX_LEN will ensure the buffer is large enough.

  • written – Number of bytes actually written to bytes_out.

Returns:

See Variable Length Output Buffers

int wally_asset_rangeproof(uint64_t value, const unsigned char *pub_key, size_t pub_key_len, const unsigned char *priv_key, size_t priv_key_len, const unsigned char *asset, size_t asset_len, const unsigned char *abf, size_t abf_len, const unsigned char *vbf, size_t vbf_len, const unsigned char *commitment, size_t commitment_len, const unsigned char *extra, size_t extra_len, const unsigned char *generator, size_t generator_len, uint64_t min_value, int exp, int min_bits, unsigned char *bytes_out, size_t len, size_t *written)

Generate a rangeproof.

This convenience function generates a nonce hash with wally_ecdh_nonce_hash and then calls wally_asset_rangeproof_with_nonce.

Parameters:
Returns:

See Variable Length Output Buffers

int wally_explicit_rangeproof(uint64_t value, const unsigned char *nonce, size_t nonce_len, const unsigned char *vbf, size_t vbf_len, const unsigned char *commitment, size_t commitment_len, const unsigned char *generator, size_t generator_len, unsigned char *bytes_out, size_t len, size_t *written)

Generate an explicit value rangeproof.

The nonce for this function should be randomly generated. See wally_asset_rangeproof_with_nonce.

Parameters:
Returns:

See Variable Length Output Buffers

int wally_explicit_rangeproof_verify(const unsigned char *rangeproof, size_t rangeproof_len, uint64_t value, const unsigned char *commitment, size_t commitment_len, const unsigned char *generator, size_t generator_len)

Verify an explicit value rangeproof proves a given value.

Parameters:
Returns:

See Error Codes

int wally_asset_surjectionproof_size(size_t num_inputs, size_t *written)

Return the required buffer size for receiving a surjection proof

Parameters:

  • num_inputs – Number of inputs.

  • written – Destination for the surjection proof size.

Returns:

See Error Codes

int wally_asset_surjectionproof_len(const unsigned char *output_asset, size_t output_asset_len, const unsigned char *output_abf, size_t output_abf_len, const unsigned char *output_generator, size_t output_generator_len, const unsigned char *bytes, size_t bytes_len, const unsigned char *asset, size_t asset_len, const unsigned char *abf, size_t abf_len, const unsigned char *generator, size_t generator_len, size_t *written)

Compute the length of an asset surjection proof.

Parameters:

  • output_asset – asset id for the output.

  • output_asset_len – Length of asset. Must be ASSET_TAG_LEN.

  • output_abf – Asset blinding factor for the output. Generated randomly for each output.

  • output_abf_len – Length of output_abf. Must be BLINDING_FACTOR_LEN.

  • output_generator – Asset generator from wally_asset_generator_from_bytes.

  • output_generator_len – Length of output_generator. Must be ASSET_GENERATOR_LEN.

  • bytes – Must be generated randomly for each output.

  • bytes_len – Length of bytes. Must be 32.

  • asset – Array of input asset tags.

  • asset_len – Length of asset. Must be ASSET_TAG_LEN * number of inputs.

  • abf – Array of input asset blinding factors.

  • abf_len – Length of abf. Must be BLINDING_FACTOR_LEN * number of inputs.

  • generator – Array of input asset generators.

  • generator_len – Length of generator. Must be ASSET_GENERATOR_LEN * number of inputs.

  • written – Number of bytes actually written to bytes_out.

Returns:

See Error Codes

int wally_asset_surjectionproof(const unsigned char *output_asset, size_t output_asset_len, const unsigned char *output_abf, size_t output_abf_len, const unsigned char *output_generator, size_t output_generator_len, const unsigned char *bytes, size_t bytes_len, const unsigned char *asset, size_t asset_len, const unsigned char *abf, size_t abf_len, const unsigned char *generator, size_t generator_len, unsigned char *bytes_out, size_t len, size_t *written)

Generate an asset surjection proof.

Parameters:

  • output_asset – asset id for the output.

  • output_asset_len – Length of asset. Must be ASSET_TAG_LEN.

  • output_abf – Asset blinding factor for the output. Generated randomly for each output.

  • output_abf_len – Length of output_abf. Must be BLINDING_FACTOR_LEN.

  • output_generator – Asset generator from wally_asset_generator_from_bytes.

  • output_generator_len – Length of output_generator. Must be ASSET_GENERATOR_LEN.

  • bytes – Must be generated randomly for each output.

  • bytes_len – Length of bytes. Must be 32.

  • asset – Array of input asset tags.

  • asset_len – Length of asset. Must be ASSET_TAG_LEN * number of inputs.

  • abf – Array of input asset blinding factors.

  • abf_len – Length of abf. Must be BLINDING_FACTOR_LEN * number of inputs.

  • generator – Array of input asset generators.

  • generator_len – Length of generator. Must be ASSET_GENERATOR_LEN * number of inputs.

  • bytes_out – Buffer to receive surjection proof.

  • len – Length of bytes_out. See wally_asset_surjectionproof_len.

  • written – Number of bytes actually written to bytes_out.

Returns:

See Variable Length Output Buffers

int wally_explicit_surjectionproof(const unsigned char *output_asset, size_t output_asset_len, const unsigned char *output_abf, size_t output_abf_len, const unsigned char *output_generator, size_t output_generator_len, unsigned char *bytes_out, size_t len)

Generate an explicit asset surjection proof.

Parameters:
Returns:

See Error Codes

int wally_explicit_surjectionproof_verify(const unsigned char *surjectionproof, size_t surjectionproof_len, const unsigned char *output_asset, size_t output_asset_len, const unsigned char *output_generator, size_t output_generator_len)

Verify an explicit asset surjection proof proves a given asset.

Parameters:

  • surjectionproof – The explicit asset surjection proof.

  • surjectionproof_len – Length of surjectionproof.

  • output_asset – The unblinded asset we expect surjectionproof to prove.

  • output_asset_len – Length of asset. Must be ASSET_TAG_LEN.

  • output_generator – Asset generator from wally_asset_generator_from_bytes.

  • output_generator_len – Length of output_generator. Must be ASSET_GENERATOR_LEN.

Returns:

See Error Codes

int wally_asset_unblind_with_nonce(const unsigned char *nonce_hash, size_t nonce_hash_len, const unsigned char *proof, size_t proof_len, const unsigned char *commitment, size_t commitment_len, const unsigned char *extra, size_t extra_len, const unsigned char *generator, size_t generator_len, unsigned char *asset_out, size_t asset_out_len, unsigned char *abf_out, size_t abf_out_len, unsigned char *vbf_out, size_t vbf_out_len, uint64_t *value_out)

Unblind a confidential transaction output.

Parameters:

  • nonce_hash – SHA-256 hash of the generated nonce.

  • nonce_hash_len – Length of nonce_hash. Must be SHA256_LEN.

  • proof – Rangeproof from wally_tx_get_output_rangeproof.

  • proof_len – Length of proof.

  • commitment – Value commitment from wally_tx_get_output_value.

  • commitment_len – Length of commitment.

  • extra – scriptPubkey from wally_tx_get_output_script.

  • extra_len – Length of extra.

  • generator – Asset generator from wally_tx_get_output_asset.

  • generator_len – Length of generator. Must be ASSET_GENERATOR_LEN.

  • asset_out – Buffer to receive unblinded asset id.

  • asset_out_len – Size of asset_out. Must be ASSET_TAG_LEN.

  • abf_out – Buffer to receive asset blinding factor.

  • abf_out_len – Size of abf_out. Must be BLINDING_FACTOR_LEN.

  • vbf_out – Buffer to receive asset blinding factor.

  • vbf_out_len – Size of vbf_out. Must be BLINDING_FACTOR_LEN.

  • value_out – Destination for unblinded transaction output value.

Returns:

See Error Codes

int wally_asset_unblind(const unsigned char *pub_key, size_t pub_key_len, const unsigned char *priv_key, size_t priv_key_len, const unsigned char *proof, size_t proof_len, const unsigned char *commitment, size_t commitment_len, const unsigned char *extra, size_t extra_len, const unsigned char *generator, size_t generator_len, unsigned char *asset_out, size_t asset_out_len, unsigned char *abf_out, size_t abf_out_len, unsigned char *vbf_out, size_t vbf_out_len, uint64_t *value_out)

Unblind a confidential transaction output.

Parameters:

  • pub_key – From wally_tx_get_output_nonce.

  • pub_key_len – Length of pub_key. Must be EC_PUBLIC_KEY_LEN.

  • priv_key – Private blinding key corresponding to public blinding key used to generate destination address. See wally_asset_blinding_key_to_ec_private_key.

  • proof – Rangeproof from wally_tx_get_output_rangeproof.

  • proof_len – Length of proof.

  • commitment – Value commitment from wally_tx_get_output_value.

  • commitment_len – Length of commitment.

  • extra – scriptPubkey from wally_tx_get_output_script.

  • extra_len – Length of extra.

  • generator – Asset generator from wally_tx_get_output_asset.

  • generator_len – Length of generator. Must be ASSET_GENERATOR_LEN.

  • asset_out – Buffer to receive unblinded asset id.

  • asset_out_len – Size of asset_out. Must be ASSET_TAG_LEN.

  • abf_out – Buffer to receive asset blinding factor.

  • abf_out_len – Size of abf_out. Must be BLINDING_FACTOR_LEN.

  • vbf_out – Buffer to receive asset blinding factor.

  • vbf_out_len – Size of vbf_out. Must be BLINDING_FACTOR_LEN.

  • value_out – Destination for unblinded transaction output value.

Returns:

See Error Codes

int wally_asset_blinding_key_from_seed(const unsigned char *bytes, size_t bytes_len, unsigned char *bytes_out, size_t len)

Generate a master blinding key from a seed as specified in SLIP-0077.

Parameters:
Returns:

See Error Codes

int wally_asset_blinding_key_to_ec_private_key(const unsigned char *bytes, size_t bytes_len, const unsigned char *script, size_t script_len, unsigned char *bytes_out, size_t len)

Generate a blinding private key for a scriptPubkey.

Parameters:

  • bytes – A full master blinding key, e.g. from wally_asset_blinding_key_from_seed, or a partial key of length SHA256_LEN, typically from the last half of the full key.

  • bytes_len – Length of bytes. Must be HMAC_SHA512_LEN or SHA256_LEN.

  • script – The scriptPubkey for the confidential output address.

  • script_len – Length of script.

  • bytes_out – Destination for the resulting blinding private key.

  • len – Size of bytes_out. Must be EC_PRIVATE_KEY_LEN.

Returns:

See Error Codes

int wally_asset_blinding_key_to_abf_vbf(const unsigned char *bytes, size_t bytes_len, const unsigned char *hash_prevouts, size_t hash_prevouts_len, uint32_t output_index, unsigned char *bytes_out, size_t len)

Generate asset and value blinding factors for a transaction output.

Parameters:

  • bytes – A full master blinding key, e.g. from wally_asset_blinding_key_from_seed, or a partial key of length SHA256_LEN, typically from the last half of the full key.

  • bytes_len – Length of bytes. Must be HMAC_SHA512_LEN or SHA256_LEN.

  • hash_prevouts – The hashPrevouts of the transaction from wally_get_hash_prevouts.

  • hash_prevouts_len – Length of hash_prevouts in bytes. Must be SHA256_LEN.

  • output_index – The zero-based index of the transaction output to be blinded.

  • bytes_out – Destination for the concatenated asset and value blinding factors.

  • len – Size of bytes_out. Must be WALLY_ABF_VBF_LEN.

Returns:

See Error Codes

int wally_asset_blinding_key_to_abf(const unsigned char *bytes, size_t bytes_len, const unsigned char *hash_prevouts, size_t hash_prevouts_len, uint32_t output_index, unsigned char *bytes_out, size_t len)

Generate an asset blinding factor for a transaction output.

Parameters:
Returns:

See Error Codes

int wally_asset_blinding_key_to_vbf(const unsigned char *bytes, size_t bytes_len, const unsigned char *hash_prevouts, size_t hash_prevouts_len, uint32_t output_index, unsigned char *bytes_out, size_t len)

Generate a value blinding factor for a transaction output.

Parameters:
Returns:

See Error Codes

int wally_asset_pak_whitelistproof_size(size_t num_keys, size_t *written)

Calculate the size in bytes of a whitelist proof.

Parameters:

  • num_keys – The number of offline/online keys.

  • written – Destination for the number of bytes needed for the proof.

Note

This function is a simpler variant of wally_asset_pak_whitelistproof_len.

Returns:

See Error Codes

int wally_asset_pak_whitelistproof(const unsigned char *online_keys, size_t online_keys_len, const unsigned char *offline_keys, size_t offline_keys_len, size_t key_index, const unsigned char *sub_pubkey, size_t sub_pubkey_len, const unsigned char *online_priv_key, size_t online_priv_key_len, const unsigned char *summed_key, size_t summed_key_len, unsigned char *bytes_out, size_t len, size_t *written)

Generate a whitelist proof for a pegout script.

Parameters:

  • online_keys – The list of concatenated online keys.

  • online_keys_len – Length of online_keys in bytes. Must be a multiple of EC_PUBLIC_KEY_LEN.

  • offline_keys – The list of concatenated offline keys.

  • offline_keys_len – Length of offline_keys in bytes. Must match online_keys_len.

  • key_index – The index in the PAK list of the key signing this whitelist proof.

  • sub_pubkey – The public key to be whitelisted.

  • sub_pubkey_len – Length of sub_pubkey in bytes. Must be EC_PUBLIC_KEY_LEN.

  • online_priv_key – The secret key to the signer’s online pubkey.

  • online_priv_key_len – Length of online_priv_key in bytes. Must be EC_PRIVATE_KEY_LEN.

  • summed_key – The secret key to the sum of (whitelisted key, signer’s offline pubkey).

  • summed_key_len – Length of summed_key in bytes. Must be EC_PRIVATE_KEY_LEN.

  • bytes_out – Destination for the resulting whitelist proof.

  • len – Length of bytes_out in bytes.

  • written – Destination for the number of bytes written to bytes_out.

Returns:

See Variable Length Output Buffers

int wally_asset_pak_whitelistproof_len(const unsigned char *online_keys, size_t online_keys_len, const unsigned char *offline_keys, size_t offline_keys_len, size_t key_index, const unsigned char *sub_pubkey, size_t sub_pubkey_len, const unsigned char *online_priv_key, size_t online_priv_key_len, const unsigned char *summed_key, size_t summed_key_len, size_t *written)

Calculate the size in bytes of a whitelist proof.

Parameters:

  • online_keys – The list of concatenated online keys.

  • online_keys_len – Length of online_keys in bytes. Must be a multiple of EC_PUBLIC_KEY_LEN.

  • offline_keys – The list of concatenated offline keys.

  • offline_keys_len – Length of offline_keys in bytes. Must match online_keys_len.

  • key_index – The index in the PAK list of the key signing this whitelist proof.

  • sub_pubkey – The public key to be whitelisted.

  • sub_pubkey_len – Length of sub_pubkey in bytes. Must be EC_PUBLIC_KEY_LEN.

  • online_priv_key – The secret key to the signer’s online pubkey.

  • online_priv_key_len – Length of online_priv_key in bytes. Must be EC_PRIVATE_KEY_LEN.

  • summed_key – The secret key to the sum of (whitelisted key, signer’s offline pubkey).

  • summed_key_len – Length of summed_key in bytes. Must be EC_PRIVATE_KEY_LEN.

  • written – Destination for resulting proof size in bytes.

Note

Use wally_asset_pak_whitelistproof_size for a simpler call interface.

Returns:

See Error Codes

Elements Constants

ASSET_TAG_LEN

Length of an Asset Tag

BLINDING_FACTOR_LEN

Length of a Blinding Factor (or blinder)

ASSET_GENERATOR_LEN

Length of an Asset Generator

ASSET_COMMITMENT_LEN

Length of an Asset Value Commitment

ASSET_RANGEPROOF_MAX_LEN

Maximum length of an Asset Value Range Proof

ASSET_EXPLICIT_RANGEPROOF_MAX_LEN

Maximum length of an Explicit Asset Value Range Proof

ASSET_SURJECTIONPROOF_MAX_LEN

Maximum length of a wally-produced Asset Surjection Proof

ASSET_EXPLICIT_SURJECTIONPROOF_LEN

Length of an Explicit Asset Surjection Proof

WALLY_ABF_VBF_LEN