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 values_len, 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
  • values_len – 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 values_len - num_inputs.
  • abf – Array of bytes representing values_len asset blinding factors.
  • abf_len – Length of abf in bytes. Must be values_len * BLINDING_FACTOR_LEN.
  • vbf – Array of bytes representing (values_len - 1) value blinding factors.
  • vbf_len – Length of vbf in bytes. Must be (values_len - 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:
  • value – Output value in satoshi.
  • vbf – Value Blinding Factor.
  • vbf_len – Length of vbf. Must be BLINDING_FACTOR_LEN.
  • generator – Asset generator from wally_asset_generator_from_bytes.
  • generator_len – Length of generator. Must be ASSET_GENERATOR_LEN.
  • bytes_out – Buffer to receive value commitment.
  • len – Size of bytes_out. Must be ASSET_COMMITMENT_LEN.
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 script pubkey of the output.
  • extra_len – Length of extra, i.e. script pubkey.
  • 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.
  • n – 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:
  • n – Size of bytes_out. Passing ASSET_RANGEPROOF_MAX_LEN will ensure the buffer is large enough.
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:
  • n – Size of bytes_out. Passing ASSET_EXPLICIT_RANGEPROOF_MAX_LEN will ensure the buffer is large enough.
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:
  • rangeproof – The explicit value rangeproof to validate.
  • rangeproof_len – Length of rangeproof in bytes.
  • value – The expected value that the explicit rangeproof proves.
  • commitment – Value commitment from wally_asset_value_commitment.
  • commitment_len – Length of commitment. Must be ASSET_COMMITMENT_LEN.
  • generator – Asset generator from wally_asset_generator_from_bytes.
  • generator_len – Length of generator`. Must be ``ASSET_GENERATOR_LEN.
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:
  • 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_out – Buffer to receive surjection proof.
  • len – Size of bytes_out. Must be ASSET_EXPLICIT_SURJECTIONPROOF_LEN.
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 – Script pubkey 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 – Script pubkey 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:
  • bytes – Seed value. See bip39_mnemonic_to_seed().
  • bytes_len – Length of bytes. Must be one of BIP32_ENTROPY_LEN_128, BIP32_ENTROPY_LEN_256 or BIP32_ENTROPY_LEN_512.
  • bytes_out – Buffer to receive master blinding key. The master blinding key can be used to generate blinding keys for specific outputs by passing it to wally_asset_blinding_key_to_ec_private_key.
  • len – Size of bytes_out. Must be HMAC_SHA512_LEN.
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 key for a script pubkey.

Parameters:
  • bytes – Master blinding key from wally_asset_blinding_key_from_seed.
  • bytes_len – Length of bytes. Must be HMAC_SHA512_LEN.
  • script – The script pubkey for the confidential output address.
  • script_len – Length of script.
  • bytes_out – Buffer to receive blinding key.
  • len – Size of bytes_out. Must be EC_PRIVATE_KEY_LEN.
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