@bsv/sdk 1.3.2 → 1.3.4

package/src/wallet/Wallet.interfaces.ts

@@ -272,8 +272,8 @@ export interface CreateActionOutput {
    * @param {TXIDHexString[]} [knownTxids] - Optional. When working with large chained transactions using `noSend` and `sendWith` options, include TXIDs of inputs that may be assumed to be valid even if not already known by this wallet.
    * @param {BooleanDefaultFalse} [returnTXIDOnly] - Optional. If true, only a TXID will be returned instead of a transaction.
    * @param {BooleanDefaultFalse} [noSend] - Optional. If true, the transaction will be constructed but not sent to the network. Supports the creation of chained batches of transactions using the `sendWith` option.
-   * @param {Array<OutPoint>} [noSendChange] - Optional. Valid when `noSend` is true. May contain `noSendChange` outpoints previously returned by prior `noSend` actions in the same batch of chained actions.
-   * @param {Array<TXIDHexString>} [sendWith] - Optional. Sends a batch of actions previously created as `noSend` actions to the network; either synchronously if `acceptDelayedBroadcast` is true or by a background process.
+   * @param {OutPoint[]} [noSendChange] - Optional. Valid when `noSend` is true. May contain `noSendChange` outpoints previously returned by prior `noSend` actions in the same batch of chained actions.
+   * @param {TXIDHexString[]} [sendWith] - Optional. Sends a batch of actions previously created as `noSend` actions to the network; either synchronously if `acceptDelayedBroadcast` is true or by a background process.
    * @param {BooleanDefaultTrue} [randomizeOutputs] — optional. When set to false, the wallet will avoid randomizing the order of outputs within the transaction.
  */
 export interface CreateActionOptions {
@@ -288,11 +288,14 @@ export interface CreateActionOptions {
   randomizeOutputs?: BooleanDefaultTrue
 }
 
+export type SendWithResultStatus = 'unproven' | 'sending' | 'failed'
+
 export interface SendWithResult {
   txid: TXIDHexString
-  status: 'unproven' | 'sending' | 'failed'
+  status: SendWithResultStatus
 }
 
+
 export interface SignableTransaction {
   tx: AtomicBEEF
   reference: Base64String
@@ -309,12 +312,12 @@ export interface CreateActionResult {
 /**
    * @param {DescriptionString5to50Bytes} description - A human-readable description of the action represented by this transaction.
    * @param {BEEF} [inputBEEF] - BEEF data associated with the set of input transactions from which UTXOs will be consumed.
-   * @param {Array<Object>} [inputs] - An optional array of input objects used in the transaction.
-   * @param {Array<Object>} [outputs] - An optional array of output objects for the transaction.
+   * @param {CreateActionInput[]} [inputs] - An optional array of input objects used in the transaction.
+   * @param {CreateActionOutput[]} [outputs] - An optional array of output objects for the transaction.
    * @param {PositiveIntegerOrZero} [lockTime] - Optional lock time for the transaction.
    * @param {PositiveInteger} [version] - Optional transaction version specifier.
    * @param {LabelStringUnder300Bytes[]} [labels] - Optional labels providing additional categorization for the transaction.
-   * @param {Object} [options] - Optional settings modifying transaction processing behavior.
+   * @param {CreateActionOptions} [options] - Optional settings modifying transaction processing behavior.
  */
 export interface CreateActionArgs {
   description: DescriptionString5to50Bytes
@@ -342,7 +345,7 @@ export interface SignActionSpend {
    * @param {TXIDHexString[]} [knownTxids] - Optional. When working with large chained transactions using `noSend` and `sendWith` options, include TXIDs of inputs that may be assumed to be valid even if not already known by this wallet.
    * @param {BooleanDefaultFalse} [returnTXIDOnly] - Optional. If true, only a TXID will be returned instead of a transaction.
    * @param {BooleanDefaultFalse} [noSend] - Optional. If true, the transaction will be constructed but not sent to the network. Supports the creation of chained batches of transactions using the `sendWith` option.
-   * @param {Array<TXIDHexString>} [sendWith] - Optional. Sends a batch of actions previously created as `noSend` actions to the network; either synchronously if `acceptDelayedBroadcast` is true or by a background process.
+   * @param {TXIDHexString[]} [sendWith] - Optional. Sends a batch of actions previously created as `noSend` actions to the network; either synchronously if `acceptDelayedBroadcast` is true or by a background process.
  */
 export interface SignActionOptions {
   acceptDelayedBroadcast?: BooleanDefaultTrue
@@ -352,9 +355,9 @@ export interface SignActionOptions {
 }
 
 /**
-   * @param {Record<PositiveIntegerOrZero, Object>} spends - Map of input indexes to the corresponding unlocking script and optional sequence number.
+   * @param {Record<PositiveIntegerOrZero, SignActionSpend>} spends - Map of input indexes to the corresponding unlocking script and optional sequence number.
    * @param {Base64String} reference - Reference number returned from the call to `createAction`.
-   * @param {Object} [options] - Optional settings modifying transaction processing behavior.
+   * @param {SignActionOptions} [options] - Optional settings modifying transaction processing behavior.
  */
 export interface SignActionArgs {
   spends: Record<PositiveIntegerOrZero, SignActionSpend>
@@ -363,7 +366,7 @@ export interface SignActionArgs {
 }
 
 /**
- *
+ * 
  */
 export interface SignActionResult {
   txid?: TXIDHexString
@@ -386,11 +389,11 @@ export interface AbortActionResult {
    * @param {LabelStringUnder300Bytes[]} labels - An array of labels used to filter actions.
    * @param {'any' | 'all'} [labelQueryMode] - Specifies how to match labels (default is any which matches any of the labels).
    * @param {BooleanDefaultFalse} [includeLabels] - Whether to include transaction labels in the result set.
-   * @param {boolean} [includeInputs] - Whether to include input details in the result set.
-   * @param {boolean} [includeInputSourceLockingScripts] - Whether to include input source locking scripts in the result set.
-   * @param {boolean} [includeInputUnlockingScripts] - Whether to include input unlocking scripts in the result set.
-   * @param {boolean} [includeOutputs] - Whether to include output details in the result set.
-   * @param {boolean} [includeOutputLockingScripts] - Whether to include output locking scripts in the result set.
+   * @param {BooleanDefaultFalse} [includeInputs] - Whether to include input details in the result set.
+   * @param {BooleanDefaultFalse} [includeInputSourceLockingScripts] - Whether to include input source locking scripts in the result set.
+   * @param {BooleanDefaultFalse} [includeInputUnlockingScripts] - Whether to include input unlocking scripts in the result set.
+   * @param {BooleanDefaultFalse} [includeOutputs] - Whether to include output details in the result set.
+   * @param {BooleanDefaultFalse} [includeOutputLockingScripts] - Whether to include output locking scripts in the result set.
    * @param {PositiveIntegerDefault10Max10000} [limit] - The maximum number of transactions to retrieve.
    * @param {PositiveIntegerOrZero} [offset] - Number of transactions to skip before starting to return the results.
    * @param {BooleanDefaultTrue} [seekPermission] — Whether to seek permission from the user for this operation if required. Default true, will return an error rather than proceed if set to false.
@@ -435,7 +438,7 @@ export interface WalletActionOutput {
 export interface WalletOutput {
   satoshis: SatoshiValue
   lockingScript?: HexString
-  spendable: true
+  spendable: boolean
   customInstructions?: string
 
   tags?: OutputTagStringUnder300Bytes[]
@@ -488,8 +491,8 @@ export interface BasketInsertion {
 /**
    * @param {PositiveIntegerOrZero} outputIndex - Index of the output within the transaction.
    * @param {'payment' | 'insert'} protocol - Specifies whether the output is a payment (to be received into the wallet balance) or an insert operation (into a particular basket).
-   * @param {Object} [paymentRemittance] - Remittance data, structured accordingly for the payment operation.
-   * @param {Object} [insertionRemittance] - Remittance data, structured accordingly for the insertion operation.
+   * @param {WalletPayment} [paymentRemittance] - Optional. Remittance data, structured accordingly for the payment operation.
+   * @param {BasketInsertion} [insertionRemittance] - Optional. Remittance data, structured accordingly for the insertion operation.
  */
 export interface InternalizeOutput {
   outputIndex: PositiveIntegerOrZero
@@ -500,7 +503,7 @@ export interface InternalizeOutput {
 
 /**
    * @param {BEEF} tx - Atomic BEEF-formatted transaction to internalize.
-   * @param {Array<Object>} outputs - Metadata about outputs, processed differently based on payment or insertion types.
+   * @param {InternalizeOutput[]} outputs - Metadata about outputs, processed differently based on payment or insertion types.
    * @param {DescriptionString5to50Bytes} description - Human-readable description of the transaction being internalized.
    * @param {LabelStringUnder300Bytes[]} [labels] - Optional labels associated with this transaction.
    * @param {BooleanDefaultTrue} [seekPermission] — Whether to seek permission from the user for this operation if required. Default true, will return an error rather than proceed if set to false.
@@ -549,40 +552,37 @@ export interface ListOutputsResult {
   outputs: WalletOutput[]
 }
 
+export interface RelinquishOutputArgs {
+  basket: BasketStringUnder300Bytes
+  output: OutpointString
+}
+
+export interface RelinquishOutputResult {
+  relinquished: true
+}
+
 /**
    * @param {WalletProtocol} protocolID - The security level and protocol string under which the data should be encrypted.
-   * @param {SecurityLevel} securityLevel - The security level of the protocol.
-   * @param {WalletProtocol} protocolID - The security level and protocol string under which the data should be encrypted.
-   * @param {SecurityLevel} protocolID[0] - SecurityLevel:
-   * 0 = Silently grants the request with no user interation.
-   * 1 = Requires user approval for every application.
-   * 2 = Requires user approval per counterparty per application.
-   * @param {ProtocolString5To400Bytes} protocolID[1] - The name of the protocol.
    * @param {KeyIDStringUnder800Bytes} keyID - Key ID under which the encryption will be performed.
    * @param {DescriptionString5to50Bytes} [privilegedReason] - Reason provided for privileged access, required if this is a privileged operation.
    * @param {WalletCounterparty} [counterparty] - Public key of the counterparty (if two-party encryption is desired).
    * @param {BooleanDefaultFalse} [privileged] - Whether this is a privileged request.
+   * @param {BooleanDefaultTrue} [seekPermission] — Whether to seek permission from the user for this operation if required. Default true, will return an error rather than proceed if set to false.
  */
-export interface KeyLinkageArgs {
-  protocolID: [SecurityLevel, ProtocolString5To400Bytes]
+export interface WalletEncryptionArgs {
+  protocolID: WalletProtocol
   keyID: KeyIDStringUnder800Bytes
   counterparty?: WalletCounterparty
   privileged?: BooleanDefaultFalse
   privilegedReason?: DescriptionString5to50Bytes
-}
-
-/**
-   * @param {BooleanDefaultTrue} [seekPermission] — Whether to seek permission from the user for this operation if required. Default true, will return an error rather than proceed if set to false.
- */
-export interface WalletEncryptionArgs extends KeyLinkageArgs {
   seekPermission?: BooleanDefaultTrue
 }
 
 /**
    * When `identityKey` is true, `WalletEncryptionArgs` are not used.
-   *
+   * 
    * When `identityKey` is undefined, `WalletEncryptionArgs` are required.
-   *
+   * 
    * @param {BooleanDefaultFalse|true} [identityKey] - Use true to retrieve the current user's own identity key, overriding any protocol ID, key ID, or counterparty specified.
    * @param {BooleanDefaultFalse} [forSelf] - Whether to return the public key derived from the current user's own identity (as opposed to the counterparty's identity).
  */
@@ -609,12 +609,16 @@ export interface RevealCounterpartyKeyLinkageArgs {
    * @param {PubKeyHex} verifier - The public key of the verifier requesting the linkage information.
    * @param {WalletProtocol} protocolID - The security level and protocol string associated with the linkage information to reveal.
    * @param {KeyIDStringUnder800Bytes} keyID - The key ID associated with the linkage information to reveal.
-   * @param {DescriptionString5to50Bytes} [privilegedReason] - Reason provided for privileged access, required if this is a privileged operation.
-   * @param {BooleanDefaultFalse} [privileged] - Whether this is a privileged request.
+   * @param {DescriptionString5to50Bytes} [privilegedReason] - Optional. Reason provided for privileged access, required if this is a privileged operation.
+   * @param {BooleanDefaultFalse} [privileged] - Optional. Whether this is a privileged request.
  */
-export interface RevealSpecificKeyLinkageArgs extends KeyLinkageArgs {
-  verifier: PubKeyHex
+export interface RevealSpecificKeyLinkageArgs {
   counterparty: WalletCounterparty
+  verifier: PubKeyHex
+  protocolID: WalletProtocol
+  keyID: KeyIDStringUnder800Bytes
+  privilegedReason?: DescriptionString5to50Bytes
+  privileged?: BooleanDefaultFalse
 }
 
 /**
@@ -648,6 +652,10 @@ export interface WalletEncryptArgs extends WalletEncryptionArgs {
   plaintext: Byte[]
 }
 
+export interface WalletEncryptResult {
+  ciphertext: Byte[]
+}
+
 /**
    * @param {Byte[]} ciphertext - Encrypted bytes, including the initialization vector, for decryption.
  */
@@ -655,6 +663,10 @@ export interface WalletDecryptArgs extends WalletEncryptionArgs {
   ciphertext: Byte[]
 }
 
+export interface WalletDecryptResult {
+  plaintext: Byte[]
+}
+
 /**
    * @param {Byte[]} data - Input data (in bytes) for which the HMAC needs to be created.
  */
@@ -662,6 +674,10 @@ export interface CreateHmacArgs extends WalletEncryptionArgs {
   data: Byte[]
 }
 
+export interface CreateHmacResult {
+  hmac: Byte[]
+}
+
 /**
    * @param {Byte[]} data - The input data whose HMAC is to be verified.
    * @param {Byte[]} hmac - Byte array representing the HMAC value to be verified.
@@ -671,6 +687,10 @@ export interface VerifyHmacArgs extends WalletEncryptionArgs {
   hmac: Byte[]
 }
 
+export interface VerifyHmacResult {
+  valid: true
+}
+
 /**
    * @param {Byte[]} [data] - Data to be signed using the derived private key with ECDSA. Required unless directly signing a hash.
    * @param {Byte[]} [hashToDirectlySign] - Sign a pre-hashed value in situations where data can't or shouldn't be revealed, whether due to its size or for privacy.
@@ -680,6 +700,10 @@ export interface CreateSignatureArgs extends WalletEncryptionArgs {
   hashToDirectlySign?: Byte[]
 }
 
+export interface CreateSignatureResult {
+  signature: Byte[]
+}
+
 /**
    * @param {Byte[]} [args.data] - The data originally signed, which is required for verification unless directly verifying a hash.
    * @param {Byte[]} [args.hashToDirectlyVerify] - Optional field to verify the signature against a precomputed hash instead of data.
@@ -693,6 +717,10 @@ export interface VerifySignatureArgs extends WalletEncryptionArgs {
   forSelf?: BooleanDefaultFalse
 }
 
+export interface VerifySignatureResult {
+  valid: true
+}
+
 /**
    * @param {Base64String} type - Type identifier for the certificate.
    * @param {PubKeyHex} certifier - The public identity key of the certifier.
@@ -765,9 +793,14 @@ export interface ListCertificatesArgs {
   privilegedReason?: DescriptionString5to50Bytes
 }
 
+export interface CertificateResult extends WalletCertificate {
+  keyring?: Record<CertificateFieldNameUnder50Bytes, Base64String>
+  verifier?: string
+}
+
 export interface ListCertificatesResult {
   totalCertificates: PositiveIntegerOrZero
-  certificates: WalletCertificate[]
+  certificates: CertificateResult[]
 }
 
 /**
@@ -778,7 +811,7 @@ export interface ListCertificatesResult {
    * @param {DescriptionString5to50Bytes} [privilegedReason] - Reason provided for privileged access, required if this is a privileged operation.
  */
 export interface ProveCertificateArgs {
-  certificate: WalletCertificate
+  certificate: Partial<WalletCertificate>
   fieldsToReveal: CertificateFieldNameUnder50Bytes[]
   verifier: PubKeyHex
   privileged?: BooleanDefaultFalse
@@ -787,6 +820,8 @@ export interface ProveCertificateArgs {
 
 export interface ProveCertificateResult {
   keyringForVerifier: Record<CertificateFieldNameUnder50Bytes, Base64String>
+  certificate?: WalletCertificate
+  verifier?: PubKeyHex
 }
 
 /**
@@ -800,6 +835,37 @@ export interface RelinquishCertificateArgs {
   certifier: PubKeyHex
 }
 
+export interface RelinquishCertificateResult {
+  relinquished: true
+}
+
+export interface AuthenticatedResult {
+  authenticated: true
+}
+
+export interface GetHeightResult {
+  height: PositiveInteger
+}
+
+/**
+ * @param {PositiveInteger} height - Specifies the height at which the block header needs to be retrieved.
+ */
+export interface GetHeaderArgs {
+  height: PositiveInteger
+}
+
+export interface GetHeaderResult {
+  header: HexString
+}
+
+export interface GetNetworkResult {
+  network: WalletNetwork
+}
+
+export interface GetVersionResult {
+  version: VersionString7To30Bytes
+}
+
 /**
    * @param {PubKeyHex} identityKey - Identity key used to filter and discover certificates.
    * @param {PositiveIntegerDefault10Max10000} [limit] - Maximum number of certificates to return in the response.
@@ -835,224 +901,242 @@ export interface DiscoverByAttributesArgs {
 
 /**
  * Every method of the `Wallet` interface has a return value of the form `Promise<object>`.
- * When errors occur, an exception object may be thrown which must conform to the `WalletError` interface.
+ * When errors occur, an exception object may be thrown which must conform to the `WalletErrorObject` interface.
  * Serialization layers can rely on the `isError` property being unique to error objects.
- * Deserialization should rethrow `WalletError` conforming objects.
+ * Deserialization should rethrow `WalletErrorObject` conforming objects.
  */
 export interface WalletErrorObject extends Error {
   isError: true
 }
 
 /**
- * The Wallet interface defines a wallet capable of various tasks including transaction creation and signing,
- * encryption, decryption, identity certificate management, identity verification, and communication
- * with applications as per the BRC standards. This interface allows applications to interact with
- * the wallet for a range of functionalities aligned with the Babbage architectural principles.
+ * 
+ */
+export interface GetPublicKeyResult {
+  publicKey: PubKeyHex
+}
+
+/**
+ * The ProtoWalletApi interface defines a wallet cryptographic capabilities including:
+ * key derivation, encryption, decryption, hmac creation and verification, signature generation and verification
  *
  * Error Handling
- *
+ * 
  * Every method of the `Wallet` interface has a return value of the form `Promise<object>`.
- * When an error occurs, an exception object may be thrown which must conform to the `WalletError` interface.
+ * When an error occurs, an exception object may be thrown which must conform to the `WalletErrorObject` interface.
  * Serialization layers can rely on the `isError` property being unique to error objects to
- * deserialize and rethrow `WalletError` conforming objects.
+ * deserialize and rethrow `WalletErrorObject` conforming objects.
  */
-export interface Wallet {
+export interface ProtoWalletApi {
   /**
-   * Creates a new Bitcoin transaction based on the provided inputs, outputs, labels, locks, and other options.
+   * Retrieves a derived or identity public key based on the requested protocol, key ID, counterparty, and other factors.
    *
-   * @param {CreateActionArgs} args - The arguments required to create the transaction.
+   * @param {GetPublicKeyArgs} args - Arguments to specify which public key to retrieve.
    * @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
-   * @returns {Promise<CreateActionResult>} The promise returns different structures based on the outcome: error response, response with TXID, response with transaction, or info about signable transaction (partial BEEF and reference number).
+   * @returns {Promise<GetPublicKeyResult>}} Resolves to an object containing the public key, or an error response.
    */
-  createAction: (
-    args: CreateActionArgs,
+  getPublicKey: (
+    args: GetPublicKeyArgs,
     originator?: OriginatorDomainNameStringUnder250Bytes
-  ) => Promise<CreateActionResult>
+  ) => Promise<GetPublicKeyResult>
 
   /**
-   * Signs a transaction previously created using `createAction`.
+   * Reveals the key linkage between ourselves and a counterparty, to a particular verifier, across all interactions with the counterparty.
    *
-   * @param {SignActionArgs} args - Arguments to sign the transaction.
+   * @param {RevealCounterpartyKeyLinkageArgs} args - Contains information about counterparty, verifier, and whether the operation is privileged.
    * @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
-   * @returns {Promise<SignActionResult>} The promise returns an error response or a response with either the completed transaction or TXID.
+   * @returns {Promise<RevealSpecificKeyLinkageResult>} Resolves to the key linkage, or an error response.
    */
-  signAction: (
-    args: SignActionArgs,
+  revealCounterpartyKeyLinkage: (
+    args: RevealCounterpartyKeyLinkageArgs,
     originator?: OriginatorDomainNameStringUnder250Bytes
-  ) => Promise<SignActionResult>
+  ) => Promise<RevealCounterpartyKeyLinkageResult>
 
   /**
-   * Aborts a transaction that is in progress and has not yet been finalized or sent to the network.
+   * Reveals the key linkage between ourselves and a counterparty, to a particular verifier, with respect to a specific interaction.
    *
-   * @param {AbortActionArgs} args - Arguments to identify the transaction that needs to be aborted.
+   * @param {RevealSpecificKeyLinkageArgs} args - The object defining the counterparty, verifier, protocol, and keyID for which linkage should be revealed.
    * @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
-   * @returns {Promise<AbortActionResult>} The promise resolves to an object indicating the abortion result (either success or error).
+   * @returns {Promise<RevealSpecificKeyLinkageResult>} The promise returns the requested linkage information, or an error object.
    */
-  abortAction: (
-    args: AbortActionArgs,
+  revealSpecificKeyLinkage: (
+    args: RevealSpecificKeyLinkageArgs,
     originator?: OriginatorDomainNameStringUnder250Bytes
-  ) => Promise<AbortActionResult>
+  ) => Promise<RevealSpecificKeyLinkageResult>
 
   /**
-   * Lists all transactions matching the specified labels.
+   * Encrypts the provided plaintext data using derived keys, based on the protocol ID, key ID, counterparty, and other factors.
    *
-   * @param {Object} args - Arguments to specify how to filter or retrieve transactions.
+   * @param {WalletEncryptArgs} args - Information needed for encryption, including the plaintext, protocol ID, and key ID.
    * @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
-   * @returns {Promise<ListActionsResult>} The promise resolves to an object containing actions, their metadata, inputs, and outputs if applicable, or an error object.
+   * @returns {Promise<WalletEncryptResult>} Resolves to the encrypted ciphertext bytes or an error if encryption fails.
    */
-  listActions: (
-    args: ListActionsArgs,
+  encrypt: (
+    args: WalletEncryptArgs,
     originator?: OriginatorDomainNameStringUnder250Bytes
-  ) => Promise<ListActionsResult>
+  ) => Promise<WalletEncryptResult>
 
   /**
-   * Submits a transaction to be internalized and optionally labeled, outputs paid to the wallet balance, inserted into baskets, and/or tagged.
+   * Decrypts the provided ciphertext using derived keys, based on the protocol ID, key ID, counterparty, and other factors.
    *
-   * @param {InternalizeActionArgs} args - Arguments required to internalize the transaction.
+   * @param {WalletDecryptArgs} args - Contains the ciphertext, protocol ID, and key ID required to decrypt the data.
    * @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
-   * @returns {Promise<InternalizeActionResult>} The promise resolves to an object indicating the success of the operation or an error object.
+   * @returns {Promise<WalletDecryptResult>} Resolves to the decryption result, containing the plaintext data or an error.
    */
-  internalizeAction: (
-    args: InternalizeActionArgs,
+  decrypt: (
+    args: WalletDecryptArgs,
     originator?: OriginatorDomainNameStringUnder250Bytes
-  ) => Promise<InternalizeActionResult>
+  ) => Promise<WalletDecryptResult>
 
   /**
-   * Lists the spendable outputs kept within a specific basket, optionally tagged with specific labels.
+   * Creates an HMAC (Hash-based Message Authentication Code) based on the provided data, protocol, key ID, counterparty, and other factors.
    *
-   * @param {ListOutputsArgs} args - Arguments detailing the query for listing spendable outputs.
+   * @param {CreateHmacArgs} args - Arguments containing the data, protocol ID, and key ID to generate the HMAC from.
    * @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
-   * @returns {Promise<Object>} The promise returns an output listing or an error object.
+   * @returns {Promise<CreateHmacResult>} Resolves to an object containing the generated HMAC bytes, or an error if the creation fails.
    */
-  listOutputs: (
-    args: ListOutputsArgs,
+  createHmac: (
+    args: CreateHmacArgs,
     originator?: OriginatorDomainNameStringUnder250Bytes
-  ) => Promise<ListOutputsResult>
+  ) => Promise<CreateHmacResult>
 
   /**
-   * Relinquish an output out of a basket, removing it from tracking without spending it.
+   * Verifies an HMAC (Hash-based Message Authentication Code) based on the provided data, protocol, key ID, counterparty, and other factors.
    *
-   * @param {Object} args - Arguments identifying the output in the basket.
-   * @param {BasketStringUnder300Bytes} args.basket - The associated basket name where the output should be removed.
-   * @param {OutpointString} args.outpoint - The output that should be removed from the basket.
+   * @param {VerifyHmacArgs} args - Arguments containing the HMAC data, protocol ID, and key ID needed for verification.
    * @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
-   * @returns {Promise<Object>} The promise returns an indication of successful removal or an error object.
+   * @returns {Promise<VerifyHmacResult>} Resolves to an object confirming whether the HMAC was valid or an error.
    */
-  relinquishOutput: (
-    args: {
-      basket: BasketStringUnder300Bytes
-      output: OutpointString
-    },
+  verifyHmac: (
+    args: VerifyHmacArgs,
     originator?: OriginatorDomainNameStringUnder250Bytes
-  ) => Promise<{ relinquished: true }>
+  ) => Promise<VerifyHmacResult>
 
   /**
-   * Retrieves a derived or identity public key based on the requested protocol, key ID, counterparty, and other factors.
+   * Creates a digital signature for the provided data or hash using a specific protocol, key, and optionally considering privilege and counterparty.
    *
-   * @param {GetPublicKeyArgs} args - Arguments to specify which public key to retrieve.
+   * @param {CreateSignatureArgs} args - Arguments to specify data, protocol, key ID, and privilege for creating the signature.
    * @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
-   * @returns {Promise<Object>} Resolves to an object containing the public key, or an error response.
+   * @returns {Promise<CreateSignatureResult>} The promise will resolve to an object containing the DER-encoded ECDSA signature, or an error on failure.
    */
-  getPublicKey: (
-    args: GetPublicKeyArgs,
+  createSignature: (
+    args: CreateSignatureArgs,
     originator?: OriginatorDomainNameStringUnder250Bytes
-  ) => Promise<{ publicKey: PubKeyHex }>
+  ) => Promise<CreateSignatureResult>
 
   /**
-   * Reveals the key linkage between ourselves and a counterparty, to a particular verifier, across all interactions with the counterparty.
+   * Verifies a digital signature for the provided data or hash using a specific protocol, key, and optionally considering privilege and counterparty.
    *
-   * @param {RevealCounterpartyKeyLinkageArgs} args - Contains information about counterparty, verifier, and whether the operation is privileged.
+   * @param {VerifySignatureArgs} args - Arguments specifying the data, signature, protocol, and key ID.
    * @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
-   * @returns {Promise<Object>} Resolves to the key linkage, or an error response.
+   * @returns {Promise<VerifySignatureResult>} The promise resolves to a boolean object indicating whether the signature was valid or an error message.
    */
-  revealCounterpartyKeyLinkage: (
-    args: RevealCounterpartyKeyLinkageArgs,
+  verifySignature: (
+    args: VerifySignatureArgs,
     originator?: OriginatorDomainNameStringUnder250Bytes
-  ) => Promise<RevealCounterpartyKeyLinkageResult>
+  ) => Promise<VerifySignatureResult>
+
+}
 
+/**
+ * The Wallet interface defines a wallet capable of various tasks including transaction creation and signing,
+ * encryption, decryption, identity certificate management, identity verification, and communication
+ * with applications as per the BRC standards. This interface allows applications to interact with
+ * the wallet for a range of functionalities aligned with the Babbage architectural principles.
+ * 
+ * Error Handling
+ * 
+ * Every method of the `Wallet` interface has a return value of the form `Promise<object>`.
+ * When an error occurs, an exception object may be thrown which must conform to the `WalletErrorObject` interface.
+ * Serialization layers can rely on the `isError` property being unique to error objects to
+ * deserialize and rethrow `WalletErrorObject` conforming objects.
+ */
+export interface Wallet extends ProtoWalletApi {
   /**
-   * Reveals the key linkage between ourselves and a counterparty, to a particular verifier, with respect to a specific interaction.
+   * Creates a new Bitcoin transaction based on the provided inputs, outputs, labels, locks, and other options.
    *
-   * @param {RevealSpecificKeyLinkageArgs} args - The object defining the counterparty, verifier, protocol, and keyID for which linkage should be revealed.
+   * @param {CreateActionArgs} args - The arguments required to create the transaction.
    * @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
-   * @returns {Promise<Object>} The promise returns the requested linkage information, or an error object.
+   * @returns {Promise<CreateActionResult>} The promise returns different structures based on the outcome: error response, response with TXID, response with transaction, or info about signable transaction (partial BEEF and reference number).
    */
-  revealSpecificKeyLinkage: (
-    args: RevealSpecificKeyLinkageArgs,
+  createAction: (
+    args: CreateActionArgs,
     originator?: OriginatorDomainNameStringUnder250Bytes
-  ) => Promise<RevealSpecificKeyLinkageResult>
+  ) => Promise<CreateActionResult>
 
   /**
-   * Encrypts the provided plaintext data using derived keys, based on the protocol ID, key ID, counterparty, and other factors.
+   * Signs a transaction previously created using `createAction`.
    *
-   * @param {WalletEncryptArgs} args - Information needed for encryption, including the plaintext, protocol ID, and key ID.
+   * @param {SignActionArgs} args - Arguments to sign the transaction.
    * @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
-   * @returns {Promise<Object>} Resolves to the encrypted ciphertext bytes or an error if encryption fails.
+   * @returns {Promise<SignActionResult>} The promise returns an error response or a response with either the completed transaction or TXID.
    */
-  encrypt: (
-    args: WalletEncryptArgs,
+  signAction: (
+    args: SignActionArgs,
     originator?: OriginatorDomainNameStringUnder250Bytes
-  ) => Promise<{ ciphertext: Byte[] }>
+  ) => Promise<SignActionResult>
 
   /**
-   * Decrypts the provided ciphertext using derived keys, based on the protocol ID, key ID, counterparty, and other factors.
+   * Aborts a transaction that is in progress and has not yet been finalized or sent to the network.
    *
-   * @param {WalletDecryptArgs} args - Contains the ciphertext, protocol ID, and key ID required to decrypt the data.
+   * @param {AbortActionArgs} args - Arguments to identify the transaction that needs to be aborted.
    * @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
-   * @returns {Promise<Object>} Resolves to the decryption result, containing the plaintext data or an error.
+   * @returns {Promise<AbortActionResult>} The promise resolves to an object indicating the abortion result (either success or error).
    */
-  decrypt: (
-    args: WalletDecryptArgs,
+  abortAction: (
+    args: AbortActionArgs,
     originator?: OriginatorDomainNameStringUnder250Bytes
-  ) => Promise<{ plaintext: Byte[] }>
+  ) => Promise<AbortActionResult>
 
   /**
-   * Creates an HMAC (Hash-based Message Authentication Code) based on the provided data, protocol, key ID, counterparty, and other factors.
+   * Lists all transactions matching the specified labels.
    *
-   * @param {Object} args - Arguments containing the data, protocol ID, and key ID to generate the HMAC from.
+   * @param {ListActionsArgs} args - Arguments to specify how to filter or retrieve transactions.
    * @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
-   * @returns {Promise<Object>} Resolves to an object containing the generated HMAC bytes, or an error if the creation fails.
+   * @returns {Promise<ListActionsResult>} The promise resolves to an object containing actions, their metadata, inputs, and outputs if applicable, or an error object.
    */
-  createHmac: (
-    args: CreateHmacArgs,
+  listActions: (
+    args: ListActionsArgs,
     originator?: OriginatorDomainNameStringUnder250Bytes
-  ) => Promise<{ hmac: Byte[] }>
+  ) => Promise<ListActionsResult>
 
   /**
-   * Verifies an HMAC (Hash-based Message Authentication Code) based on the provided data, protocol, key ID, counterparty, and other factors.
+   * Submits a transaction to be internalized and optionally labeled, outputs paid to the wallet balance, inserted into baskets, and/or tagged.
    *
-   * @param {VerifyHmacArgs} args - Arguments containing the HMAC data, protocol ID, and key ID needed for verification.
+   * @param {InternalizeActionArgs} args - Arguments required to internalize the transaction.
    * @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
-   * @returns {Promise<Object>} Resolves to an object confirming whether the HMAC was valid or an error.
+   * @returns {Promise<InternalizeActionResult>} The promise resolves to an object indicating the success of the operation or an error object.
    */
-  verifyHmac: (
-    args: VerifyHmacArgs,
+  internalizeAction: (
+    args: InternalizeActionArgs,
     originator?: OriginatorDomainNameStringUnder250Bytes
-  ) => Promise<{ valid: true }>
+  ) => Promise<InternalizeActionResult>
 
   /**
-   * Creates a digital signature for the provided data or hash using a specific protocol, key, and optionally considering privilege and counterparty.
+   * Lists the spendable outputs kept within a specific basket, optionally tagged with specific labels.
    *
-   * @param {CreateSignatureArgs} args - Arguments to specify data, protocol, key ID, and privilege for creating the signature.
+   * @param {ListOutputsArgs} args - Arguments detailing the query for listing spendable outputs.
    * @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
-   * @returns {Promise<Object>} The promise will resolve to an object containing the DER-encoded ECDSA signature, or an error on failure.
+   * @returns {Promise<ListOutputsResult>} The promise returns an output listing or an error object.
    */
-  createSignature: (
-    args: CreateSignatureArgs,
+  listOutputs: (
+    args: ListOutputsArgs,
     originator?: OriginatorDomainNameStringUnder250Bytes
-  ) => Promise<{ signature: Byte[] }>
+  ) => Promise<ListOutputsResult>
 
   /**
-   * Verifies a digital signature for the provided data or hash using a specific protocol, key, and optionally considering privilege and counterparty.
+   * Relinquish an output out of a basket, removing it from tracking without spending it.
    *
-   * @param {VerifySignatureArgs} args - Arguments specifying the data, signature, protocol, and key ID.
+   * @param {RelinquishOutputArgs} args - Arguments identifying the output in the basket.
+   * @param {BasketStringUnder300Bytes} args.basket - The associated basket name where the output should be removed.
+   * @param {OutpointString} args.outpoint - The output that should be removed from the basket.
    * @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
-   * @returns {Promise<Object>} The promise resolves to a boolean object indicating whether the signature was valid or an error message.
+   * @returns {Promise<RelinquishOutputResult>} The promise returns an indication of successful removal or an error object.
    */
-  verifySignature: (
-    args: VerifySignatureArgs,
+  relinquishOutput: (
+    args: RelinquishOutputArgs,
     originator?: OriginatorDomainNameStringUnder250Bytes
-  ) => Promise<{ valid: true }>
+  ) => Promise<RelinquishOutputResult>
 
   /**
    * Acquires an identity certificate, whether by acquiring one from the certifier or by directly receiving it.
@@ -1095,19 +1179,19 @@ export interface Wallet {
    *
    * @param {RelinquishCertificateArgs} args - Contains the type of certificate, certifier, and serial number for relinquishment.
    * @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
-   * @returns {Promise<Object>} The promise resolves to an indication of successful relinquishment or an error object.
+   * @returns {Promise<RelinquishCertificateResult>} The promise resolves to an indication of successful relinquishment or an error object.
    */
   relinquishCertificate: (
     args: RelinquishCertificateArgs,
     originator?: OriginatorDomainNameStringUnder250Bytes
-  ) => Promise<{ relinquished: true }>
+  ) => Promise<RelinquishCertificateResult>
 
   /**
    * Discovers identity certificates, issued to a given identity key by a trusted entity.
    *
    * @param {DiscoverByIdentityKeyArgs} args - Arguments for requesting the discovery based on the identity key.
    * @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
-   * @returns {Promise<Object>} The promise resolves to the list of certificates discovered or an error object.
+   * @returns {Promise<DiscoverCertificatesResult>} The promise resolves to the list of certificates discovered or an error object.
    */
   discoverByIdentityKey: (
     args: DiscoverByIdentityKeyArgs,
@@ -1129,73 +1213,72 @@ export interface Wallet {
   /**
    * Checks the authentication status of the user.
    *
-   * @param {Object} args - Empty object, as no parameters are needed.
+   * @param {{}} args - Empty object, as no parameters are needed.
    * @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
-   * @returns {Promise<Object>} The promise resolves to an object indicating whether the user is authenticated or an error response.
+   * @returns {Promise<AuthenticatedResult>} The promise resolves to an object indicating whether the user is authenticated or an error response.
    */
   isAuthenticated: (
     args: {},
     originator?: OriginatorDomainNameStringUnder250Bytes
-  ) => Promise<{ authenticated: boolean }>
+  ) => Promise<AuthenticatedResult>
 
   /**
    * Continuously waits until the user is authenticated, returning the result once confirmed.
    *
-   * @param {Object} args - Not used, pass an empty object.
+   * @param {{}} args - Not used, pass an empty object.
    * @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
-   * @returns {Promise<Object>} The final result indicating that the user is authenticated or an error object.
+   * @returns {Promise<AuthenticatedResult>} The final result indicating that the user is authenticated or an error object.
    */
   waitForAuthentication: (
     args: {},
     originator?: OriginatorDomainNameStringUnder250Bytes
-  ) => Promise<{ authenticated: true }>
+  ) => Promise<AuthenticatedResult>
 
   /**
    * Retrieves the current height of the blockchain.
    *
-   * @param {Object} args - Empty object as no other parameters are necessary.
+   * @param {{}} args - Empty object as no other parameters are necessary.
    * @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
    * @returns {Promise<Object>} Resolves to an object indicating the current height or an error on failure.
    */
   getHeight: (
     args: {},
     originator?: OriginatorDomainNameStringUnder250Bytes
-  ) => Promise<{ height: PositiveInteger }>
+  ) => Promise<GetHeightResult>
 
   /**
    * Retrieves the block header of a block at a specified height.
    *
-   * @param {Object} args - Contains the height parameter needed to retrieve the block header.
-   * @param {PositiveInteger} args.height - Specifies the height at which the block header needs to be retrieved.
+   * @param {GetHeaderArgs} args - Contains the height parameter needed to retrieve the block header.
    * @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
-   * @returns {Promise<Object>} The promise resolves to an 80-byte block header or an error if it cannot be retrieved.
+   * @returns {Promise<GetHeaderResult>} The promise resolves to an 80-byte block header or an error if it cannot be retrieved.
    */
   getHeaderForHeight: (
-    args: { height: PositiveInteger },
+    args: GetHeaderArgs,
     originator?: OriginatorDomainNameStringUnder250Bytes
-  ) => Promise<{ header: HexString }>
+  ) => Promise<GetHeaderResult>
 
   /**
    * Retrieves the Bitcoin network the client is using (mainnet or testnet).
    *
-   * @param {Object} args - No arguments required, pass an empty object.
+   * @param {{}} args - No arguments required, pass an empty object.
    * @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
-   * @returns {Promise<Object>} The promise resolves to an object indicating whether the client is using the mainnet or testnet.
+   * @returns {Promise<GetNetworkResult>} The promise resolves to an object indicating whether the client is using the mainnet or testnet.
    */
   getNetwork: (
     args: {},
     originator?: OriginatorDomainNameStringUnder250Bytes
-  ) => Promise<{ network: WalletNetwork }>
+  ) => Promise<GetNetworkResult>
 
   /**
    * Retrieves the current version string of the wallet.
    *
-   * @param {Object} args - Empty argument object.
+   * @param {{}} args - Empty argument object.
    * @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Fully-qualified domain name (FQDN) of the application that originated the request.
-   * @returns {Promise<Object>} Resolves to an object containing the version string of the wallet, or an error.
+   * @returns {Promise<GetVersionResult>} Resolves to an object containing the version string of the wallet, or an error.
    */
   getVersion: (
     args: {},
     originator?: OriginatorDomainNameStringUnder250Bytes
-  ) => Promise<{ version: VersionString7To30Bytes }>
-}
+  ) => Promise<GetVersionResult>
+}