react-native-zcash 0.6.14 → 0.7.0

package/ios/ZCashLightClientKit/Rust/zcashlc.h

@@ -3,6 +3,36 @@
 #include <stdint.h>
 #include <stdlib.h>
 
+/**
+ * A struct that contains details about an account in the wallet.
+ */
+typedef struct FfiAccount {
+  uint8_t seed_fingerprint[32];
+  uint32_t account_index;
+} FfiAccount;
+
+/**
+ * A struct that contains a pointer to, and length information for, a heap-allocated
+ * slice of [`FfiAccount`] values.
+ *
+ * # Safety
+ *
+ * - `ptr` must be non-null and must be valid for reads for `len * mem::size_of::<FfiAccount>()`
+ *   many bytes, and it must be properly aligned. This means in particular:
+ *   - The entire memory range pointed to by `ptr` must be contained within a single allocated
+ *     object. Slices can never span across multiple allocated objects.
+ *   - `ptr` must be non-null and aligned even for zero-length slices.
+ *   - `ptr` must point to `len` consecutive properly initialized values of type
+ *     [`FfiAccount`].
+ * - The total size `len * mem::size_of::<FfiAccount>()` of the slice pointed to
+ *   by `ptr` must be no larger than isize::MAX. See the safety documentation of pointer::offset.
+ * - See the safety documentation of [`FfiAccount`]
+ */
+typedef struct FfiAccounts {
+  struct FfiAccount *ptr;
+  uintptr_t len;
+} FfiAccounts;
+
 /**
  * A struct that contains an account identifier along with a pointer to the binary encoding
  * of an associated key.
@@ -91,6 +121,56 @@ typedef struct FfiSubtreeRoots {
   uintptr_t len;
 } FfiSubtreeRoots;
 
+/**
+ * Balance information for a value within a single pool in an account.
+ */
+typedef struct FfiBalance {
+  /**
+   * The value in the account that may currently be spent; it is possible to compute witnesses
+   * for all the notes that comprise this value, and all of this value is confirmed to the
+   * required confirmation depth.
+   */
+  int64_t spendable_value;
+  /**
+   * The value in the account of shielded change notes that do not yet have sufficient
+   * confirmations to be spendable.
+   */
+  int64_t change_pending_confirmation;
+  /**
+   * The value in the account of all remaining received notes that either do not have sufficient
+   * confirmations to be spendable, or for which witnesses cannot yet be constructed without
+   * additional scanning.
+   */
+  int64_t value_pending_spendability;
+} FfiBalance;
+
+/**
+ * Balance information for a single account.
+ *
+ * The sum of this struct's fields is the total balance of the account.
+ */
+typedef struct FfiAccountBalance {
+  uint32_t account_id;
+  /**
+   * The value of unspent Sapling outputs belonging to the account.
+   */
+  struct FfiBalance sapling_balance;
+  /**
+   * The value of unspent Orchard outputs belonging to the account.
+   */
+  struct FfiBalance orchard_balance;
+  /**
+   * The value of all unspent transparent outputs belonging to the account,
+   * irrespective of confirmation depth.
+   *
+   * Unshielded balances are not subject to confirmation-depth constraints, because the
+   * only possible operation on a transparent balance is to shield it, it is possible
+   * to create a zero-conf transaction to perform that shielding, and the resulting
+   * shielded notes will be subject to normal confirmation rules.
+   */
+  int64_t unshielded;
+} FfiAccountBalance;
+
 /**
  * A struct that contains details about scan progress.
  *
@@ -103,6 +183,42 @@ typedef struct FfiScanProgress {
   uint64_t denominator;
 } FfiScanProgress;
 
+/**
+ * A type representing the potentially-spendable value of unspent outputs in the wallet.
+ *
+ * The balances reported using this data structure may overestimate the total spendable
+ * value of the wallet, in the case that the spend of a previously received shielded note
+ * has not yet been detected by the process of scanning the chain. The balances reported
+ * using this data structure can only be certain to be unspent in the case that
+ * [`Self::is_synced`] is true, and even in this circumstance it is possible that a newly
+ * created transaction could conflict with a not-yet-mined transaction in the mempool.
+ *
+ * # Safety
+ *
+ * - `account_balances` must be non-null and must be valid for reads for
+ *   `account_balances_len * mem::size_of::<FfiAccountBalance>()` many bytes, and it must
+ *   be properly aligned. This means in particular:
+ *   - The entire memory range pointed to by `account_balances` must be contained within
+ *     a single allocated object. Slices can never span across multiple allocated objects.
+ *   - `account_balances` must be non-null and aligned even for zero-length slices.
+ *   - `account_balances` must point to `len` consecutive properly initialized values of
+ *     type [`FfiAccountBalance`].
+ * - The total size `account_balances_len * mem::size_of::<FfiAccountBalance>()` of the
+ *   slice pointed to by `account_balances` must be no larger than `isize::MAX`. See the
+ *   safety documentation of `pointer::offset`.
+ * - `scan_progress` must, if non-null, point to a struct having the layout of
+ *   [`FfiScanProgress`].
+ */
+typedef struct FfiWalletSummary {
+  struct FfiAccountBalance *account_balances;
+  uintptr_t account_balances_len;
+  int32_t chain_tip_height;
+  int32_t fully_scanned_height;
+  struct FfiScanProgress *scan_progress;
+  uint64_t next_sapling_subtree_index;
+  uint64_t next_orchard_subtree_index;
+} FfiWalletSummary;
+
 /**
  * A struct that contains the start (inclusive) and end (exclusive) of a range of blocks
  * to scan.
@@ -135,6 +251,17 @@ typedef struct FfiScanRanges {
   uintptr_t len;
 } FfiScanRanges;
 
+/**
+ * Metadata about modifications to the wallet state made in the course of scanning a set
+ * of blocks.
+ */
+typedef struct FfiScanSummary {
+  int32_t scanned_start;
+  int32_t scanned_end;
+  uint64_t spent_sapling_note_count;
+  uint64_t received_sapling_note_count;
+} FfiScanSummary;
+
 typedef struct FFIBlockMeta {
   uint32_t height;
   uint8_t *block_hash_ptr;
@@ -149,6 +276,46 @@ typedef struct FFIBlocksMeta {
   uintptr_t len;
 } FFIBlocksMeta;
 
+/**
+ * A struct that contains a pointer to, and length information for, a heap-allocated
+ * boxed slice.
+ *
+ * # Safety
+ *
+ * - `ptr` must be non-null and valid for reads for `len` bytes, and it must have an
+ *   alignment of `1`. Its contents must be an encoded Proposal protobuf.
+ * - The memory referenced by `ptr` must not be mutated for the lifetime of the struct
+ *   (up until [`zcashlc_free_boxed_slice`] is called with it).
+ * - The total size `len` must be no larger than `isize::MAX`. See the safety
+ *   documentation of `pointer::offset`.
+ */
+typedef struct FfiBoxedSlice {
+  uint8_t *ptr;
+  uintptr_t len;
+} FfiBoxedSlice;
+
+/**
+ * A struct that contains a pointer to, and length information for, a heap-allocated
+ * slice of `[u8; 32]` arrays.
+ *
+ * # Safety
+ *
+ * - `ptr` must be non-null and must be valid for reads for `len * mem::size_of::<[u8; 32]>()`
+ *   many bytes, and it must be properly aligned. This means in particular:
+ *   - The entire memory range pointed to by `ptr` must be contained within a single
+ *     allocated object. Slices can never span across multiple allocated objects.
+ *   - `ptr` must be non-null and aligned even for zero-length slices.
+ *   - `ptr` must point to `len` consecutive properly initialized values of type
+ *     `[u8; 32]`.
+ * - The total size `len * mem::size_of::<[u8; 32]>()` of the slice pointed to
+ *   by `ptr` must be no larger than isize::MAX. See the safety documentation of
+ *   `pointer::offset`.
+ */
+typedef struct FfiTxIds {
+  uint8_t (*ptr)[32];
+  uintptr_t len;
+} FfiTxIds;
+
 /**
  * Initializes global Rust state, such as the logging infrastructure and threadpools.
  *
@@ -188,8 +355,11 @@ void zcashlc_clear_last_error(void);
  * null pointer if the caller wishes to attempt migrations without providing the wallet's seed
  * value.
  *
- * Returns 0 if successful, 1 if the seed must be provided in order to execute the requested
- * migrations, or -1 otherwise.
+ * Returns:
+ * - 0 if successful.
+ * - 1 if the seed must be provided in order to execute the requested migrations
+ * - 2 if the provided seed is not relevant to any of the derived accounts in the wallet.
+ * - -1 on error.
  *
  * # Safety
  *
@@ -211,6 +381,34 @@ int32_t zcashlc_init_data_database(const uint8_t *db_data,
                                    uintptr_t seed_len,
                                    uint32_t network_id);
 
+/**
+ * Frees an array of FfiAccounts values as allocated by `zcashlc_list_accounts`.
+ *
+ * # Safety
+ *
+ * - `ptr` must be non-null and must point to a struct having the layout of [`FfiAccounts`].
+ *   See the safety documentation of [`FfiAccounts`].
+ */
+void zcashlc_free_accounts(struct FfiAccounts *ptr);
+
+/**
+ * Returns a list of the accounts in the wallet.
+ *
+ * # Safety
+ *
+ * - `db_data` must be non-null and valid for reads for `db_data_len` bytes, and it must have an
+ *   alignment of `1`. Its contents must be a string representing a valid system path in the
+ *   operating system's preferred representation.
+ * - The memory referenced by `db_data` must not be mutated for the duration of the function call.
+ * - The total size `db_data_len` must be no larger than `isize::MAX`. See the safety
+ *   documentation of pointer::offset.
+ * - Call [`zcashlc_free_accounts`] to free the memory associated with the returned pointer
+ *   when done using it.
+ */
+struct FfiAccounts *zcashlc_list_accounts(const uint8_t *db_data,
+                                          uintptr_t db_data_len,
+                                          uint32_t network_id);
+
 /**
  * Frees a FFIBinaryKey value
  *
@@ -264,6 +462,20 @@ struct FFIBinaryKey *zcashlc_create_account(const uint8_t *db_data,
                                             int64_t recover_until,
                                             uint32_t network_id);
 
+/**
+ * Checks whether the given seed is relevant to any of the accounts in the wallet.
+ *
+ * Returns:
+ * - `1` for `Ok(true)`.
+ * - `0` for `Ok(false)`.
+ * - `-1` for `Err(_)`.
+ */
+int8_t zcashlc_is_seed_relevant_to_any_derived_account(const uint8_t *db_data,
+                                                       uintptr_t db_data_len,
+                                                       const uint8_t *seed,
+                                                       uintptr_t seed_len,
+                                                       uint32_t network_id);
+
 /**
  * Frees an array of FFIEncodedKeys values as allocated by `zcashlc_derive_unified_viewing_keys_from_seed`
  *
@@ -434,7 +646,7 @@ char *zcashlc_get_sapling_receiver_for_unified_address(const char *ua);
  * - `address` must be non-null and must point to a null-terminated UTF-8 string.
  * - The memory referenced by `address` must not be mutated for the duration of the function call.
  */
-bool zcashlc_is_valid_shielded_address(const char *address, uint32_t network_id);
+bool zcashlc_is_valid_sapling_address(const char *address, uint32_t network_id);
 
 /**
  * Returns the network type and address kind for the given address string,
@@ -512,42 +724,6 @@ bool zcashlc_is_valid_unified_full_viewing_key(const char *ufvk, uint32_t networ
  */
 bool zcashlc_is_valid_unified_address(const char *address, uint32_t network_id);
 
-/**
- * Returns the balance for the specified account, including all unspent notes that we know about.
- *
- * # Safety
- *
- * - `db_data` must be non-null and valid for reads for `db_data_len` bytes, and it must have an
- *   alignment of `1`. Its contents must be a string representing a valid system path in the
- *   operating system's preferred representation.
- * - The memory referenced by `db_data` must not be mutated for the duration of the function call.
- * - The total size `db_data_len` must be no larger than `isize::MAX`. See the safety
- *   documentation of pointer::offset.
- */
-int64_t zcashlc_get_balance(const uint8_t *db_data,
-                            uintptr_t db_data_len,
-                            int32_t account,
-                            uint32_t network_id);
-
-/**
- * Returns the verified balance for the account, which ignores notes that have been
- * received too recently and are not yet deemed spendable according to `min_confirmations`.
- *
- * # Safety
- *
- * - `db_data` must be non-null and valid for reads for `db_data_len` bytes, and it must have an
- *   alignment of `1`. Its contents must be a string representing a valid system path in the
- *   operating system's preferred representation.
- * - The memory referenced by `db_data` must not be mutated for the duration of the function call.
- * - The total size `db_data_len` must be no larger than `isize::MAX`. See the safety
- *   documentation of pointer::offset.
- */
-int64_t zcashlc_get_verified_balance(const uint8_t *db_data,
-                                     uintptr_t db_data_len,
-                                     int32_t account,
-                                     uint32_t network_id,
-                                     uint32_t min_confirmations);
-
 /**
  * Returns the verified transparent balance for `address`, which ignores utxos that have been
  * received too recently and are not yet deemed spendable according to `min_confirmations`.
@@ -647,6 +823,7 @@ int64_t zcashlc_get_total_transparent_balance_for_account(const uint8_t *db_data
 bool zcashlc_get_memo(const uint8_t *db_data,
                       uintptr_t db_data_len,
                       const uint8_t *txid_bytes,
+                      uint32_t output_pool,
                       uint16_t output_index,
                       uint8_t *memo_bytes_ret,
                       uint32_t network_id);
@@ -748,6 +925,29 @@ bool zcashlc_put_sapling_subtree_roots(const uint8_t *db_data,
                                        const struct FfiSubtreeRoots *roots,
                                        uint32_t network_id);
 
+/**
+ * Adds a sequence of Orchard subtree roots to the data store.
+ *
+ * Returns true if the subtrees could be stored, false otherwise. When false is returned,
+ * caller should check for errors.
+ *
+ * # Safety
+ *
+ * - `db_data` must be non-null and valid for reads for `db_data_len` bytes, and it must have an
+ *   alignment of `1`. Its contents must be a string representing a valid system path in the
+ *   operating system's preferred representation.
+ * - The memory referenced by `db_data` must not be mutated for the duration of the function call.
+ * - The total size `db_data_len` must be no larger than `isize::MAX`. See the safety
+ *   documentation of `pointer::offset`.
+ * - `roots` must be non-null and initialized.
+ * - The memory referenced by `roots` must not be mutated for the duration of the function call.
+ */
+bool zcashlc_put_orchard_subtree_roots(const uint8_t *db_data,
+                                       uintptr_t db_data_len,
+                                       uint64_t start_index,
+                                       const struct FfiSubtreeRoots *roots,
+                                       uint32_t network_id);
+
 /**
  * Updates the wallet's view of the blockchain.
  *
@@ -815,7 +1015,10 @@ int64_t zcashlc_max_scanned_height(const uint8_t *db_data,
                                    uint32_t network_id);
 
 /**
- * Returns the scan progress derived from the current wallet state.
+ * Returns the account balances and sync status given the specified minimum number of
+ * confirmations.
+ *
+ * Returns `fully_scanned_height = -1` if the wallet has no balance data available.
  *
  * # Safety
  *
@@ -827,9 +1030,20 @@ int64_t zcashlc_max_scanned_height(const uint8_t *db_data,
  * - The total size `db_data_len` must be no larger than `isize::MAX`. See the safety
  *   documentation of pointer::offset.
  */
-struct FfiScanProgress zcashlc_get_scan_progress(const uint8_t *db_data,
-                                                 uintptr_t db_data_len,
-                                                 uint32_t network_id);
+struct FfiWalletSummary *zcashlc_get_wallet_summary(const uint8_t *db_data,
+                                                    uintptr_t db_data_len,
+                                                    uint32_t network_id,
+                                                    uint32_t min_confirmations);
+
+/**
+ * Frees an [`FfiWalletSummary`] value.
+ *
+ * # Safety
+ *
+ * - `ptr` must be non-null and must point to a struct having the layout of [`FfiWalletSummary`].
+ *   See the safety documentation of [`FfiWalletSummary`].
+ */
+void zcashlc_free_wallet_summary(struct FfiWalletSummary *ptr);
 
 /**
  * Frees an array of FfiScanRanges values as allocated by `zcashlc_derive_unified_viewing_keys_from_seed`
@@ -898,13 +1112,24 @@ struct FfiScanRanges *zcashlc_suggest_scan_ranges(const uint8_t *db_data,
  * - The total size `db_data_len` must be no larger than `isize::MAX`. See the safety
  *   documentation of pointer::offset.
  */
-int32_t zcashlc_scan_blocks(const uint8_t *fs_block_cache_root,
-                            uintptr_t fs_block_cache_root_len,
-                            const uint8_t *db_data,
-                            uintptr_t db_data_len,
-                            int32_t from_height,
-                            uint32_t scan_limit,
-                            uint32_t network_id);
+struct FfiScanSummary *zcashlc_scan_blocks(const uint8_t *fs_block_cache_root,
+                                           uintptr_t fs_block_cache_root_len,
+                                           const uint8_t *db_data,
+                                           uintptr_t db_data_len,
+                                           int32_t from_height,
+                                           const uint8_t *from_state,
+                                           uintptr_t from_state_len,
+                                           uint32_t scan_limit,
+                                           uint32_t network_id);
+
+/**
+ * Frees an [`FfiScanSummary`] value.
+ *
+ * # Safety
+ *
+ * - `ptr` must be non-null and must point to a struct having the layout of [`FfiScanSummary`].
+ */
+void zcashlc_free_scan_summary(struct FfiScanSummary *ptr);
 
 /**
  * Inserts a UTXO into the wallet database.
@@ -1045,14 +1270,19 @@ int32_t zcashlc_decrypt_and_store_transaction(const uint8_t *db_data,
                                               uint32_t network_id);
 
 /**
- * Creates a transaction paying the specified address from the given account.
+ * Frees an [`FfiBoxedSlice`].
  *
- * Returns the row index of the newly-created transaction in the `transactions` table
- * within the data database. The caller can read the raw transaction bytes from the `raw`
- * column in order to broadcast the transaction to the network.
+ * # Safety
  *
- * Do not call this multiple times in parallel, or you will generate transactions that
- * double-spend the same notes.
+ * - `ptr` must be non-null and must point to a struct having the layout of
+ *   [`FfiBoxedSlice`]. See the safety documentation of [`FfiBoxedSlice`].
+ */
+void zcashlc_free_boxed_slice(struct FfiBoxedSlice *ptr);
+
+/**
+ * Select transaction inputs, compute fees, and construct a proposal for a transaction
+ * that can then be authorized and made ready for submission to the network with
+ * `zcashlc_create_proposed_transaction`.
  *
  * # Safety
  *
@@ -1062,42 +1292,45 @@ int32_t zcashlc_decrypt_and_store_transaction(const uint8_t *db_data,
  * - The memory referenced by `db_data` must not be mutated for the duration of the function call.
  * - The total size `db_data_len` must be no larger than `isize::MAX`. See the safety
  *   documentation of pointer::offset.
- * - `usk_ptr` must be non-null and must point to an array of `usk_len` bytes containing a unified
- *   spending key encoded as returned from the `zcashlc_create_account` or
- *   `zcashlc_derive_spending_key` functions.
- * - The memory referenced by `usk_ptr` must not be mutated for the duration of the function call.
- * - The total size `usk_len` must be no larger than `isize::MAX`. See the safety documentation
- *   of pointer::offset.
  * - `to` must be non-null and must point to a null-terminated UTF-8 string.
  * - `memo` must either be null (indicating an empty memo or a transparent recipient) or point to a
  *    512-byte array.
- * - `spend_params` must be non-null and valid for reads for `spend_params_len` bytes, and it must have an
- *   alignment of `1`. Its contents must be the Sapling spend proving parameters.
- * - The memory referenced by `spend_params` must not be mutated for the duration of the function call.
- * - The total size `spend_params_len` must be no larger than `isize::MAX`. See the safety
- *   documentation of pointer::offset.
- * - `output_params` must be non-null and valid for reads for `output_params_len` bytes, and it must have an
- *   alignment of `1`. Its contents must be the Sapling output proving parameters.
- * - The memory referenced by `output_params` must not be mutated for the duration of the function call.
- * - The total size `output_params_len` must be no larger than `isize::MAX`. See the safety
+ */
+struct FfiBoxedSlice *zcashlc_propose_transfer(const uint8_t *db_data,
+                                               uintptr_t db_data_len,
+                                               int32_t account,
+                                               const char *to,
+                                               int64_t value,
+                                               const uint8_t *memo,
+                                               uint32_t network_id,
+                                               uint32_t min_confirmations,
+                                               bool use_zip317_fees);
+
+/**
+ * Select transaction inputs, compute fees, and construct a proposal for a transaction
+ * from a ZIP-321 payment URI that can then be authorized and made ready for submission to the
+ * network with `zcashlc_create_proposed_transaction`.
+ *
+ * # Safety
+ *
+ * - `db_data` must be non-null and valid for reads for `db_data_len` bytes, and it must have an
+ *   alignment of `1`. Its contents must be a string representing a valid system path in the
+ *   operating system's preferred representation.
+ * - The memory referenced by `db_data` must not be mutated for the duration of the function call.
+ * - The total size `db_data_len` must be no larger than `isize::MAX`. See the safety
  *   documentation of pointer::offset.
- * - `txid_bytes_ret` must be non-null and must point to an allocated 32-byte region of memory.
+ * - `payment_uri` must be non-null and must point to a null-terminated UTF-8 string.
+ * - `network_id` a u32. 0 for Testnet and 1 for Mainnet
+ * - `min_confirmations` number of confirmations of the funds to spend
+ * - `use_zip317_fees` `true`` to use ZIP-317 fees.
  */
-bool zcashlc_create_to_address(const uint8_t *db_data,
-                               uintptr_t db_data_len,
-                               const uint8_t *usk_ptr,
-                               uintptr_t usk_len,
-                               const char *to,
-                               int64_t value,
-                               const uint8_t *memo,
-                               const uint8_t *spend_params,
-                               uintptr_t spend_params_len,
-                               const uint8_t *output_params,
-                               uintptr_t output_params_len,
-                               uint32_t network_id,
-                               uint32_t min_confirmations,
-                               bool use_zip317_fees,
-                               uint8_t *txid_bytes_ret);
+struct FfiBoxedSlice *zcashlc_propose_transfer_from_uri(const uint8_t *db_data,
+                                                        uintptr_t db_data_len,
+                                                        int32_t account,
+                                                        const char *payment_uri,
+                                                        uint32_t network_id,
+                                                        uint32_t min_confirmations,
+                                                        bool use_zip317_fees);
 
 int32_t zcashlc_branch_id_for_height(int32_t height, uint32_t network_id);
 
@@ -1111,8 +1344,9 @@ int32_t zcashlc_branch_id_for_height(int32_t height, uint32_t network_id);
 void zcashlc_string_free(char *s);
 
 /**
- * Shield transparent UTXOs by sending them to an address associated with the specified Sapling
- * spending key.
+ * Select transaction inputs, compute fees, and construct a proposal for a shielding
+ * transaction that can then be authorized and made ready for submission to the network
+ * with `zcashlc_create_proposed_transaction`.
  *
  * # Safety
  *
@@ -1122,36 +1356,86 @@ void zcashlc_string_free(char *s);
  * - The memory referenced by `db_data` must not be mutated for the duration of the function call.
  * - The total size `db_data_len` must be no larger than `isize::MAX`. See the safety
  *   documentation of pointer::offset.
- * - `usk_ptr` must be non-null and must point to an array of `usk_len` bytes containing a unified
- *   spending key encoded as returned from the `zcashlc_create_account` or
- *   `zcashlc_derive_spending_key` functions.
- * - The memory referenced by `usk_ptr` must not be mutated for the duration of the function call.
- * - The total size `usk_len` must be no larger than `isize::MAX`. See the safety documentation
- * - `memo` must either be null (indicating an empty memo) or point to a 512-byte array.
  * - `shielding_threshold` a non-negative shielding threshold amount in zatoshi
- * - `spend_params` must be non-null and valid for reads for `spend_params_len` bytes, and it must have an
- *   alignment of `1`. Its contents must be the Sapling spend proving parameters.
- * - The memory referenced by `spend_params` must not be mutated for the duration of the function call.
+ */
+struct FfiBoxedSlice *zcashlc_propose_shielding(const uint8_t *db_data,
+                                                uintptr_t db_data_len,
+                                                int32_t account,
+                                                const uint8_t *memo,
+                                                uint64_t shielding_threshold,
+                                                const char *transparent_receiver,
+                                                uint32_t network_id,
+                                                uint32_t min_confirmations,
+                                                bool use_zip317_fees);
+
+/**
+ * Frees an array of FfiTxIds values as allocated by `zcashlc_create_proposed_transactions`.
+ *
+ * # Safety
+ *
+ * - `ptr` must be non-null and must point to a struct having the layout of [`FfiTxIds`].
+ *   See the safety documentation of [`FfiTxIds`].
+ */
+void zcashlc_free_txids(struct FfiTxIds *ptr);
+
+/**
+ * Creates a transaction from the given proposal.
+ *
+ * Returns the row index of the newly-created transaction in the `transactions` table
+ * within the data database. The caller can read the raw transaction bytes from the `raw`
+ * column in order to broadcast the transaction to the network.
+ *
+ * Do not call this multiple times in parallel, or you will generate transactions that
+ * double-spend the same notes.
+ *
+ * # Safety
+ *
+ * - `db_data` must be non-null and valid for reads for `db_data_len` bytes, and it must
+ *   have an alignment of `1`. Its contents must be a string representing a valid system
+ *   path in the operating system's preferred representation.
+ * - The memory referenced by `db_data` must not be mutated for the duration of the
+ *   function call.
+ * - The total size `db_data_len` must be no larger than `isize::MAX`. See the safety
+ *   documentation of `pointer::offset`.
+ * - `proposal_ptr` must be non-null and valid for reads for `proposal_len` bytes, and it
+ *   must have an alignment of `1`. Its contents must be an encoded Proposal protobuf.
+ * - The memory referenced by `proposal_ptr` must not be mutated for the duration of the
+ *   function call.
+ * - The total size `proposal_len` must be no larger than `isize::MAX`. See the safety
+ *   documentation of `pointer::offset`.
+ * - `usk_ptr` must be non-null and must point to an array of `usk_len` bytes containing
+ *   a unified spending key encoded as returned from the `zcashlc_create_account` or
+ *   `zcashlc_derive_spending_key` functions.
+ * - The memory referenced by `usk_ptr` must not be mutated for the duration of the
+ *   function call.
+ * - The total size `usk_len` must be no larger than `isize::MAX`. See the safety
+ *   documentation of `pointer::offset`.
+ * - `to` must be non-null and must point to a null-terminated UTF-8 string.
+ * - `memo` must either be null (indicating an empty memo or a transparent recipient) or
+ *   point to a 512-byte array.
+ * - `spend_params` must be non-null and valid for reads for `spend_params_len` bytes,
+ *   and it must have an alignment of `1`. Its contents must be the Sapling spend proving
+ *   parameters.
+ * - The memory referenced by `spend_params` must not be mutated for the duration of the
+ *   function call.
  * - The total size `spend_params_len` must be no larger than `isize::MAX`. See the safety
- *   documentation of pointer::offset.
- * - `output_params` must be non-null and valid for reads for `output_params_len` bytes, and it must have an
- *   alignment of `1`. Its contents must be the Sapling output proving parameters.
- * - The memory referenced by `output_params` must not be mutated for the duration of the function call.
+ *   documentation of `pointer::offset`.
+ * - `output_params` must be non-null and valid for reads for `output_params_len` bytes,
+ *   and it must have an alignment of `1`. Its contents must be the Sapling output
+ *   proving parameters.
+ * - The memory referenced by `output_params` must not be mutated for the duration of the
+ *   function call.
  * - The total size `output_params_len` must be no larger than `isize::MAX`. See the safety
  *   documentation of pointer::offset.
- * - `txid_bytes_ret` must be non-null and must point to an allocated 32-byte region of memory.
- */
-bool zcashlc_shield_funds(const uint8_t *db_data,
-                          uintptr_t db_data_len,
-                          const uint8_t *usk_ptr,
-                          uintptr_t usk_len,
-                          const uint8_t *memo,
-                          uint64_t shielding_threshold,
-                          const uint8_t *spend_params,
-                          uintptr_t spend_params_len,
-                          const uint8_t *output_params,
-                          uintptr_t output_params_len,
-                          uint32_t network_id,
-                          uint32_t min_confirmations,
-                          bool use_zip317_fees,
-                          uint8_t *txid_bytes_ret);
+ */
+struct FfiTxIds *zcashlc_create_proposed_transactions(const uint8_t *db_data,
+                                                      uintptr_t db_data_len,
+                                                      const uint8_t *proposal_ptr,
+                                                      uintptr_t proposal_len,
+                                                      const uint8_t *usk_ptr,
+                                                      uintptr_t usk_len,
+                                                      const uint8_t *spend_params,
+                                                      uintptr_t spend_params_len,
+                                                      const uint8_t *output_params,
+                                                      uintptr_t output_params_len,
+                                                      uint32_t network_id);