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