1 #ifndef LIBWALLY_CORE_ELEMENTS_H 2 #define LIBWALLY_CORE_ELEMENTS_H 3 4 #include "wally_core.h" 5 6 #ifdef __cplusplus 7 extern "C" { 8 #endif 9 10 #ifdef BUILD_ELEMENTS 11 12 #define ASSET_TAG_LEN 32 /** Length of an Asset Tag */ 13 14 #define BLINDING_FACTOR_LEN 32 /** Length of a Blinding Factor (or blinder) */ 15 16 #define ASSET_GENERATOR_LEN 33 /** Length of an Asset Generator */ 17 18 #define ASSET_COMMITMENT_LEN 33 /** Length of an Asset Value Commitment */ 19 20 #define ASSET_RANGEPROOF_MAX_LEN 5134 /** Maximum length of an Asset Range Proof */ 21 22 /** 23 * Create a blinded Asset Generator from an Asset Tag and Asset Blinding Factor. 24 * 25 * :param asset: Asset Tag to create a blinding generator for. 26 * :param asset_len: Length of ``asset`` in bytes. Must be ``ASSET_TAG_LEN``. 27 * :param abf: Asset Blinding Factor (Random entropy to blind with). 28 * :param abf_len: Length of ``abf`` in bytes. Must be ``BLINDING_FACTOR_LEN``. 29 * :param bytes_out: Destination for the resulting Asset Generator. 30 * :param len: The length of ``bytes_out`` in bytes. Must be ``ASSET_GENERATOR_LEN``. 31 */ 32 WALLY_CORE_API int wally_asset_generator_from_bytes( 33 const unsigned char *asset, 34 size_t asset_len, 35 const unsigned char *abf, 36 size_t abf_len, 37 unsigned char *bytes_out, 38 size_t len); 39 40 /** 41 * Generate the final value blinding factor required for blinding a confidential transaction. 42 * 43 * :param values: Array of transaction input values in satoshi 44 * :param values_len: Length of ``values``, also the number of elements in all three of the input arrays, which is equal 45 *| to ``num_inputs`` plus the number of outputs. 46 * :param num_inputs: Number of elements in the input arrays that represent transaction inputs. The number of outputs is 47 *| implicitly ``values_len`` - ``num_inputs``. 48 * :param abf: Array of bytes representing ``values_len`` asset blinding factors. 49 * :param abf_len: Length of ``abf`` in bytes. Must be ``values_len`` * ``BLINDING_FACTOR_LEN``. 50 * :param vbf: Array of bytes representing (``values_len`` - 1) value blinding factors. 51 * :param vbf_len: Length of ``vbf`` in bytes. Must be (``values_len`` - 1) * ``BLINDING_FACTOR_LEN``. 52 * :param bytes_out: Buffer to receive the final value blinding factor. 53 * :param len: Length of ``bytes_out``. Must be ``BLINDING_FACTOR_LEN``. 54 */ 55 WALLY_CORE_API int wally_asset_final_vbf( 56 const uint64_t *values, 57 size_t values_len, 58 size_t num_inputs, 59 const unsigned char *abf, 60 size_t abf_len, 61 const unsigned char *vbf, 62 size_t vbf_len, 63 unsigned char *bytes_out, 64 size_t len); 65 66 /** 67 * Calculate the value commitment for a transaction output. 68 * 69 * :param value: Output value in satoshi. 70 * :param vbf: Value Blinding Factor. 71 * :param vbf_len: Length of ``vbf``. Must be ``BLINDING_FACTOR_LEN``. 72 * :param generator: Asset generator from `wally_asset_generator_from_bytes`. 73 * :param generator_len: Length of ``generator``. Must be ``ASSET_GENERATOR_LEN``. 74 * :param bytes_out: Buffer to receive value commitment. 75 * :param len: Length of ``bytes_out``. Must be ``ASSET_COMMITMENT_LEN``. 76 */ 77 WALLY_CORE_API int wally_asset_value_commitment( 78 uint64_t value, 79 const unsigned char *vbf, 80 size_t vbf_len, 81 const unsigned char *generator, 82 size_t generator_len, 83 unsigned char *bytes_out, 84 size_t len); 85 86 /* 87 * As per wally_asset_rangeproof with a user provided nonce. 88 */ 89 WALLY_CORE_API int wally_asset_rangeproof_with_nonce( 90 uint64_t value, 91 const unsigned char *nonce_hash, 92 size_t nonce_hash_len, 93 const unsigned char *asset, 94 size_t asset_len, 95 const unsigned char *abf, 96 size_t abf_len, 97 const unsigned char *vbf, 98 size_t vbf_len, 99 const unsigned char *commitment, 100 size_t commitment_len, 101 const unsigned char *extra, 102 size_t extra_len, 103 const unsigned char *generator, 104 size_t generator_len, 105 uint64_t min_value, 106 int exp, 107 int min_bits, 108 unsigned char *bytes_out, 109 size_t len, 110 size_t *written); 111 112 /** 113 * Generate a rangeproof for a transaction output. 114 * 115 * :param value: Value of the output in satoshi. 116 * :param pub_key: Public blinding key for the output. See `wally_confidential_addr_to_ec_public_key`. 117 * :param pub_key_len: Length of ``pub_key``. Must be ``EC_PUBLIC_KEY_LEN`` 118 * :param priv_key: Pivate ephemeral key. Should be randomly generated for each output. 119 * :param priv_key_length: Length of ``priv_key``. 120 * :param asset: Asset id of output. 121 * :param asset_len: Length of ``asset``. Must be ``ASSET_TAG_LEN``. 122 * :param abf: Asset blinding factor. Randomly generated for each output. 123 * :param abf_len: Length of ``abf``. Must be ``BLINDING_FACTOR_LEN``. 124 * :param vbf: Value blinding factor. Randomly generated for each output except the last, which is generate by calling 125 *| `wally_asset_final_vbf`. 126 * :param vbf_len: Length of ``vbf``. Must be ``BLINDING_FACTOR_LEN``. 127 * :param commitment: Value commitment from `wally_asset_value_commitment`. 128 * :param commitment_len: Length of ``commitment``. Must be ``ASSET_COMMITMENT_LEN``. 129 * :param extra: Set this to the script pubkey of the output. 130 * :param extra_len: Length of ``extra``, i.e. script pubkey. 131 * :param generator: Asset generator from `wally_asset_generator_from_bytes`. 132 * :param generator_len: Length of ``generator`. Must be ``ASSET_GENERATOR_LEN``. 133 * :param min_value: Recommended value 1. 134 * :param exp: Exponent value. -1 >= ``exp`` >= 18. Recommended value 0. 135 * :param min_bits: 0 >= min_bits >= 64. Recommended value 52. 136 * :param bytes_out: Buffer to receive rangeproof. 137 * :param len: Length of ``bytes_out``. See ``ASSET_RANGEPROOF_MAX_LEN``. 138 * :param written: Number of bytes actually written to ``bytes_out``. 139 */ 140 WALLY_CORE_API int wally_asset_rangeproof( 141 uint64_t value, 142 const unsigned char *pub_key, 143 size_t pub_key_len, 144 const unsigned char *priv_key, 145 size_t priv_key_len, 146 const unsigned char *asset, 147 size_t asset_len, 148 const unsigned char *abf, 149 size_t abf_len, 150 const unsigned char *vbf, 151 size_t vbf_len, 152 const unsigned char *commitment, 153 size_t commitment_len, 154 const unsigned char *extra, 155 size_t extra_len, 156 const unsigned char *generator, 157 size_t generator_len, 158 uint64_t min_value, 159 int exp, 160 int min_bits, 161 unsigned char *bytes_out, 162 size_t len, 163 size_t *written); 164 165 /** 166 * Return the required buffer size for receiving a surjection proof 167 * 168 * :param num_inputs: Number of transaction inputs. 169 * :param written: Destination for the surjection proof size. 170 */ 171 WALLY_CORE_API int wally_asset_surjectionproof_size( 172 size_t num_inputs, 173 size_t *written); 174 175 /** 176 * Generate a surjection proof for a transaction output 177 * 178 * :param output_asset: asset id for the output. 179 * :param output_asset_len: Length of ``asset``. Must be ``ASSET_TAG_LEN``. 180 * :param output_abf: Asset blinding factor for the output. Generated randomly for each output. 181 * :param output_abf_len: Length of ``output_abf``. Must be ``BLINDING_FACTOR_LEN``. 182 * :param output_generator: Asset generator from `wally_asset_generator_from_bytes`. 183 * :param output_generator_len: Length of ``output_generator`. Must be ``ASSET_GENERATOR_LEN``. 184 * :param bytes: Must be generated randomly for each output. 185 * :param bytes_len: Length of ``bytes``. Must be 32. 186 * :param asset: Array of input asset tags. 187 * :param asset_len: Length of ``asset`. Must be ``ASSET_TAG_LEN`` * number of inputs. 188 * :param abf: Array of asset blinding factors from the transaction inputs. 189 * :param abf_len: Length of ``abf``. Must be ``BLINDING_FACTOR_LEN`` * number of inputs. 190 * :param generator: Array of asset generators from transaction inputs. 191 * :param generator_len: Length of ``generator``. Must be ``ASSET_GENERATOR_LEN`` * number of inputs. 192 * :param bytes_out: Buffer to receive surjection proof. 193 * :param bytes_out_len: Length of ``bytes_out``. See `wally_asset_surjectionproof_size`. 194 * :param written: Number of bytes actually written to ``bytes_out``. 195 */ 196 WALLY_CORE_API int wally_asset_surjectionproof( 197 const unsigned char *output_asset, 198 size_t output_asset_len, 199 const unsigned char *output_abf, 200 size_t output_abf_len, 201 const unsigned char *output_generator, 202 size_t output_generator_len, 203 const unsigned char *bytes, 204 size_t bytes_len, 205 const unsigned char *asset, 206 size_t asset_len, 207 const unsigned char *abf, 208 size_t abf_len, 209 const unsigned char *generator, 210 size_t generator_len, 211 unsigned char *bytes_out, 212 size_t len, 213 size_t *written); 214 215 /** 216 * Unblind a confidential transaction output. 217 * 218 * :param nonce_hash: SHA-256 hash of the generated nonce. 219 * :param nonce_hash_len: Length of ``nonce_hash``. Must be ``SHA256_LEN``. 220 * :param proof: Rangeproof from :c:func:`wally_tx_get_output_rangeproof`. 221 * :param proof_len: Length of ``proof``. 222 * :param commitment: Value commitment from :c:func:`wally_tx_get_output_value`. 223 * :param commitment_len: Length of ``commitment``. 224 * :param extra: Script pubkey from :c:func:`wally_tx_get_output_script`. 225 * :param extra_len: Length of ``extra``. 226 * :param generator: Asset generator from :c:func:`wally_tx_get_output_asset`. 227 * :param generator_len: Length of ``generator``. Must be ``ASSET_GENERATOR_LEN``. 228 * :param asset_out: Buffer to receive unblinded asset id. 229 * :param asset_out_len: Length of ``asset_out``. Must be ``ASSET_TAG_LEN``. 230 * :param abf_out: Buffer to receive asset blinding factor. 231 * :param abf_out_len: Length of ``abf_out``. Must be ``BLINDING_FACTOR_LEN``. 232 * :param vbf_out: Buffer to receive asset blinding factor. 233 * :param vbf_out_len: Length of ``vbf_out``. Must be ``BLINDING_FACTOR_LEN``. 234 * :param value_out: Destination for unblinded transaction output value. 235 */ 236 WALLY_CORE_API int wally_asset_unblind_with_nonce( 237 const unsigned char *nonce_hash, 238 size_t nonce_hash_len, 239 const unsigned char *proof, 240 size_t proof_len, 241 const unsigned char *commitment, 242 size_t commitment_len, 243 const unsigned char *extra, 244 size_t extra_len, 245 const unsigned char *generator, 246 size_t generator_len, 247 unsigned char *asset_out, 248 size_t asset_out_len, 249 unsigned char *abf_out, 250 size_t abf_out_len, 251 unsigned char *vbf_out, 252 size_t vbf_out_len, 253 uint64_t *value_out); 254 255 /** 256 * Unblind a confidential transaction output. 257 * 258 * :param pub_key: From :c:func:`wally_tx_get_output_nonce`. 259 * :param pub_key_len: Length of ``pub_key``. Must be ``EC_PUBLIC_KEY_LEN``. 260 * :param priv_key: Private blinding key corresponding to public blinding key used to generate destination address. See 261 *| :c:func:`wally_asset_blinding_key_to_ec_private_key`. 262 * :param proof: Rangeproof from :c:func:`wally_tx_get_output_rangeproof`. 263 * :param proof_len: Length of ``proof``. 264 * :param commitment: Value commitment from :c:func:`wally_tx_get_output_value`. 265 * :param commitment_len: Length of ``commitment``. 266 * :param extra: Script pubkey from :c:func:`wally_tx_get_output_script`. 267 * :param extra_len: Length of ``extra``. 268 * :param generator: Asset generator from :c:func:`wally_tx_get_output_asset`. 269 * :param generator_len: Length of ``generator``. Must be ``ASSET_GENERATOR_LEN``. 270 * :param asset_out: Buffer to receive unblinded asset id. 271 * :param asset_out_len: Length of ``asset_out``. Must be ``ASSET_TAG_LEN``. 272 * :param abf_out: Buffer to receive asset blinding factor. 273 * :param abf_out_len: Length of ``abf_out``. Must be ``BLINDING_FACTOR_LEN``. 274 * :param vbf_out: Buffer to receive asset blinding factor. 275 * :param vbf_out_len: Length of ``vbf_out``. Must be ``BLINDING_FACTOR_LEN``. 276 * :param value_out: Destination for unblinded transaction output value. 277 */ 278 WALLY_CORE_API int wally_asset_unblind( 279 const unsigned char *pub_key, 280 size_t pub_key_len, 281 const unsigned char *priv_key, 282 size_t priv_key_len, 283 const unsigned char *proof, 284 size_t proof_len, 285 const unsigned char *commitment, 286 size_t commitment_len, 287 const unsigned char *extra, 288 size_t extra_len, 289 const unsigned char *generator, 290 size_t generator_len, 291 unsigned char *asset_out, 292 size_t asset_out_len, 293 unsigned char *abf_out, 294 size_t abf_out_len, 295 unsigned char *vbf_out, 296 size_t vbf_out_len, 297 uint64_t *value_out); 298 299 /** 300 * Generate a master blinding key from a seed as specified in SLIP-0077. 301 * 302 * :param bytes: Seed value. See :c:func:`bip39_mnemonic_to_seed`. 303 * :param bytes_len: Length of ``seed``. Must be one of ``BIP32_ENTROPY_LEN_128``, ``BIP32_ENTROPY_LEN_256`` or 304 *| ``BIP32_ENTROPY_LEN_512``. 305 * :param bytes_out: Buffer to receive master blinding key. The master blinding key can be used to generate blinding 306 *| keys for specific outputs by passing it to `wally_asset_blinding_key_to_ec_private_key`. 307 * :param len: Length of ``bytes_out``. Must be ``HMAC_SHA512_LEN``. 308 */ 309 WALLY_CORE_API int wally_asset_blinding_key_from_seed( 310 const unsigned char *bytes, 311 size_t bytes_len, 312 unsigned char *bytes_out, 313 size_t len); 314 315 /** 316 * Generate a blinding key for a script pubkey. 317 * 318 * :param bytes: Master blinding key from `wally_asset_blinding_key_from_seed`. 319 * :param bytes_len: Length of ``bytes``. Must be ``HMAC_SHA512_LEN``. 320 * :param script: The script pubkey for the confidential output address. 321 * :param script_len: Length of ``script``. 322 * :param bytes_out: Buffer to receive blinding key. 323 * :param len: Length of ``bytes_out``. Must be ``EC_PRIVATE_KEY_LEN``. 324 */ 325 WALLY_CORE_API int wally_asset_blinding_key_to_ec_private_key( 326 const unsigned char *bytes, 327 size_t bytes_len, 328 const unsigned char *script, 329 size_t script_len, 330 unsigned char *bytes_out, 331 size_t len); 332 333 /** 334 * Calculate the size in bytes of the whitelist proof. 335 * 336 * :param num_keys: The number of offline/online keys. 337 * :param written: Destination for the number of bytes needed for the proof. 338 */ 339 WALLY_CORE_API int wally_asset_pak_whitelistproof_size( 340 size_t num_keys, 341 size_t *written); 342 343 /** 344 * Generate the whitelist proof for the pegout script. 345 * 346 * :param online_keys: The list of online keys. 347 * :param online_keys_len: Length of ``online_keys_len`` in bytes. Must be a multiple of ``EC_PUBLIC_KEY_LEN``. 348 * :param offline_keys: The list of offline keys. 349 * :param offline_keys_len: Length of ``offline_keys_len`` in bytes. Must be a multiple of ``EC_PUBLIC_KEY_LEN``. 350 * :param key_index: The index in the PAK list of the key signing this whitelist proof 351 * :param sub_pubkey: The key to be whitelisted. 352 * :param sub_pubkey_len: Length of ``sub_pubkey`` in bytes. Must be ``EC_PUBLIC_KEY_LEN``. 353 * :param online_priv_key: The secret key to the signer's online pubkey. 354 * :param online_priv_key_len: Length of ``online_priv_key`` in bytes. Must be ``EC_PRIVATE_KEY_LEN``. 355 * :param summed_key: The secret key to the sum of (whitelisted key, signer's offline pubkey). 356 * :param summed_key_len: Length of ``summed_key`` in bytes. Must be ``EC_PRIVATE_KEY_LEN``. 357 * :param bytes_out: Destination for the resulting whitelist proof. 358 * :param len: Length of ``bytes_out`` in bytes. 359 * :param written: Number of bytes actually written to ``bytes_out``. 360 */ 361 WALLY_CORE_API int wally_asset_pak_whitelistproof( 362 const unsigned char *online_keys, 363 size_t online_keys_len, 364 const unsigned char *offline_keys, 365 size_t offline_keys_len, 366 size_t key_index, 367 const unsigned char *sub_pubkey, 368 size_t sub_pubkey_len, 369 const unsigned char *online_priv_key, 370 size_t online_priv_key_len, 371 const unsigned char *summed_key, 372 size_t summed_key_len, 373 unsigned char *bytes_out, 374 size_t len, 375 size_t *written); 376 377 #endif /* BUILD_ELEMENTS */ 378 379 #ifdef __cplusplus 380 } 381 #endif 382 383 #endif /* LIBWALLY_CORE_ELEMENTS_H */ 384