2023-05-05 14:46:07 -07:00
|
|
|
package cash.z.ecc.android.sdk.internal.transaction
|
|
|
|
|
|
|
|
import cash.z.ecc.android.sdk.internal.model.EncodedTransaction
|
|
|
|
import cash.z.ecc.android.sdk.model.Account
|
2024-02-19 14:09:01 -08:00
|
|
|
import cash.z.ecc.android.sdk.model.Proposal
|
2023-05-05 14:46:07 -07:00
|
|
|
import cash.z.ecc.android.sdk.model.TransactionRecipient
|
2024-02-19 14:09:01 -08:00
|
|
|
import cash.z.ecc.android.sdk.model.TransactionSubmitResult
|
2023-05-05 14:46:07 -07:00
|
|
|
import cash.z.ecc.android.sdk.model.UnifiedSpendingKey
|
|
|
|
import cash.z.ecc.android.sdk.model.Zatoshi
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Manage outbound transactions with the main purpose of reporting which ones are still pending,
|
|
|
|
* particularly after failed attempts or dropped connectivity. The intent is to help see outbound
|
|
|
|
* transactions through to completion.
|
|
|
|
*/
|
|
|
|
@Suppress("TooManyFunctions")
|
|
|
|
internal interface OutboundTransactionManager {
|
|
|
|
/**
|
|
|
|
* Encode the pending transaction using the given spending key. This is a local operation that
|
|
|
|
* produces a raw transaction to submit to lightwalletd.
|
|
|
|
*
|
|
|
|
* @param usk the unified spending key to use for constructing the transaction.
|
|
|
|
* @param amount the amount to send.
|
|
|
|
* @param recipient the recipient of the transaction.
|
|
|
|
* @param memo the memo to include in the transaction.
|
|
|
|
* @param account the account to use for the transaction.
|
|
|
|
*
|
|
|
|
* @return The encoded transaction, which can be submitted to lightwalletd.
|
|
|
|
*/
|
|
|
|
suspend fun encode(
|
|
|
|
usk: UnifiedSpendingKey,
|
|
|
|
amount: Zatoshi,
|
|
|
|
recipient: TransactionRecipient,
|
|
|
|
memo: String,
|
|
|
|
account: Account
|
|
|
|
): EncodedTransaction
|
|
|
|
|
2024-02-27 10:21:58 -08:00
|
|
|
/**
|
|
|
|
* Creates a proposal for transferring funds from a ZIP-321 compliant payment URI
|
|
|
|
*
|
|
|
|
* @param account the account from which to transfer funds.
|
|
|
|
* @param uri a ZIP-321 compliant payment URI
|
|
|
|
*
|
|
|
|
* @return the proposal or an exception
|
|
|
|
*/
|
|
|
|
suspend fun proposeTransferFromUri(
|
|
|
|
account: Account,
|
|
|
|
uri: String
|
|
|
|
): Proposal
|
|
|
|
|
2024-02-19 14:09:01 -08:00
|
|
|
/**
|
|
|
|
* Creates a proposal for transferring funds to the given recipient.
|
|
|
|
*
|
|
|
|
* @param account the account from which to transfer funds.
|
|
|
|
* @param recipient the recipient's address.
|
|
|
|
* @param amount the amount of zatoshi to send.
|
|
|
|
* @param memo the optional memo to include as part of the proposal's transactions.
|
|
|
|
*
|
|
|
|
* @return the proposal or an exception
|
|
|
|
*/
|
|
|
|
suspend fun proposeTransfer(
|
|
|
|
account: Account,
|
|
|
|
recipient: String,
|
|
|
|
amount: Zatoshi,
|
|
|
|
memo: String
|
|
|
|
): Proposal
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Creates a proposal for shielding any transparent funds received by the given account.
|
|
|
|
*
|
|
|
|
* @param account the account for which to shield funds.
|
2024-02-27 11:00:06 -08:00
|
|
|
* @param shieldingThreshold the minimum transparent balance required before a
|
|
|
|
* proposal will be created.
|
2024-02-19 14:09:01 -08:00
|
|
|
* @param memo the optional memo to include as part of the proposal's transactions.
|
2024-02-27 17:44:12 -08:00
|
|
|
* @param transparentReceiver a specific transparent receiver within the account that
|
|
|
|
* should be the source of transparent funds. Default is
|
|
|
|
* null which will select whichever of the account's
|
|
|
|
* transparent receivers has funds to shield.
|
|
|
|
*
|
|
|
|
* @return the proposal, or null if the transparent balance that would be shielded is
|
|
|
|
* zero or below `shieldingThreshold`.
|
|
|
|
*
|
|
|
|
* @throws Exception if `transparentReceiver` is null and there are transparent funds
|
|
|
|
* in more than one of the account's transparent receivers.
|
2024-02-19 14:09:01 -08:00
|
|
|
*/
|
|
|
|
suspend fun proposeShielding(
|
|
|
|
account: Account,
|
2024-02-27 11:00:06 -08:00
|
|
|
shieldingThreshold: Zatoshi,
|
2024-02-27 17:44:12 -08:00
|
|
|
memo: String,
|
|
|
|
transparentReceiver: String?
|
|
|
|
): Proposal?
|
2024-02-19 14:09:01 -08:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Creates the transactions in the given proposal.
|
|
|
|
*
|
|
|
|
* @param proposal the proposal for which to create transactions.
|
|
|
|
* @param usk the unified spending key associated with the account for which the
|
|
|
|
* proposal was created.
|
|
|
|
*
|
|
|
|
* @return the successfully encoded transactions or an exception
|
|
|
|
*/
|
|
|
|
suspend fun createProposedTransactions(
|
|
|
|
proposal: Proposal,
|
|
|
|
usk: UnifiedSpendingKey
|
|
|
|
): List<EncodedTransaction>
|
|
|
|
|
2023-05-05 14:46:07 -07:00
|
|
|
/**
|
|
|
|
* Submits the transaction represented by [encodedTransaction] to lightwalletd to broadcast to the
|
|
|
|
* network and, hopefully, include in the next block.
|
|
|
|
*
|
|
|
|
* @param encodedTransaction the transaction information containing the raw bytes that will be submitted
|
|
|
|
* to lightwalletd.
|
|
|
|
* @return true if the transaction was successfully submitted to lightwalletd.
|
|
|
|
*/
|
2024-02-19 14:09:01 -08:00
|
|
|
suspend fun submit(encodedTransaction: EncodedTransaction): TransactionSubmitResult
|
2023-05-05 14:46:07 -07:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Return true when the given address is a valid t-addr.
|
|
|
|
*
|
|
|
|
* @param address the address to validate.
|
|
|
|
*
|
|
|
|
* @return true when the given address is a valid t-addr.
|
|
|
|
*/
|
|
|
|
suspend fun isValidShieldedAddress(address: String): Boolean
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Return true when the given address is a valid z-addr.
|
|
|
|
*
|
|
|
|
* @param address the address to validate.
|
|
|
|
*
|
|
|
|
* @return true when the given address is a valid z-addr.
|
|
|
|
*/
|
|
|
|
suspend fun isValidTransparentAddress(address: String): Boolean
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Return true when the given address is a valid ZIP 316 Unified Address.
|
|
|
|
*
|
|
|
|
* @param address the address to validate.
|
|
|
|
*
|
|
|
|
* @return true when the given address is a valid ZIP 316 Unified Address.
|
|
|
|
*/
|
|
|
|
suspend fun isValidUnifiedAddress(address: String): Boolean
|
|
|
|
}
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Interface for transaction errors.
|
|
|
|
*/
|
|
|
|
interface TransactionError {
|
|
|
|
/**
|
|
|
|
* The message associated with this error.
|
|
|
|
*/
|
|
|
|
val message: String
|
|
|
|
}
|