breez_sdk_spark/signer/
external_spark.rs

1//! External (foreign) high-level Spark signer trait.
2//!
3//! Mirrors `spark_wallet::SparkSigner` using FFI-compatible types so an
4//! integrator can implement the Spark flow-signing surface directly.
5//! The SDK wraps an implementation in
6//! [`ExternalSparkSignerAdapter`](super::ExternalSparkSignerAdapter) to obtain a
7//! native `spark_wallet::SparkSigner`.
8
9use crate::error::SignerError;
10
11use super::external_spark_types::{
12    ExternalFrostJob, ExternalFrostShareResult, ExternalPrepareClaimRequest,
13    ExternalPrepareLightningReceiveRequest, ExternalPrepareStaticDepositClaimRequest,
14    ExternalPrepareStaticDepositRequest, ExternalPrepareTokenTransactionRequest,
15    ExternalPrepareTransferRequest, ExternalPreparedClaim, ExternalPreparedLightningReceive,
16    ExternalPreparedStaticDeposit, ExternalPreparedStaticDepositClaim,
17    ExternalPreparedTokenTransaction, ExternalPreparedTransfer, ExternalSignSparkInvoiceRequest,
18    ExternalSignStaticDepositRefundRequest, ExternalSignedSparkInvoice,
19    ExternalStartStaticDepositRefundRequest, ExternalStartedStaticDepositRefund,
20};
21use super::external_types::{
22    EcdsaSignatureBytes, ExternalFrostSignature, ExternalTreeNodeId, PublicKeyBytes,
23    SchnorrSignatureBytes,
24};
25
26/// FFI-compatible mirror of `spark_wallet::SparkSigner`.
27#[cfg_attr(
28    feature = "uniffi",
29    uniffi::export(with_foreign, async_runtime = "tokio")
30)]
31#[macros::async_trait]
32pub trait ExternalSparkSigner: Send + Sync {
33    /// The wallet identity public key (33 bytes compressed).
34    async fn get_identity_public_key(&self) -> Result<PublicKeyBytes, SignerError>;
35
36    /// The signing public key for a tree leaf.
37    async fn get_public_key_for_leaf(
38        &self,
39        leaf_id: ExternalTreeNodeId,
40    ) -> Result<PublicKeyBytes, SignerError>;
41
42    /// Whether this signer is backed by a remote service, so its operations are
43    /// network round-trips rather than local computation. Local signers return
44    /// false; a hosted signer like Turnkey returns true so the SDK can avoid
45    /// redundant calls, e.g. re-deriving keys for leaves it has already verified.
46    fn is_remote(&self) -> bool {
47        false
48    }
49
50    /// The static-deposit signing public key at `index`.
51    async fn get_static_deposit_public_key(
52        &self,
53        index: u32,
54    ) -> Result<PublicKeyBytes, SignerError>;
55
56    /// ECDSA-sign a server authentication challenge with the identity key.
57    async fn sign_authentication_challenge(
58        &self,
59        challenge: Vec<u8>,
60    ) -> Result<EcdsaSignatureBytes, SignerError>;
61
62    /// ECDSA-sign an arbitrary user message with the identity key.
63    async fn sign_message(&self, message: Vec<u8>) -> Result<EcdsaSignatureBytes, SignerError>;
64
65    /// Schnorr-sign `sighash` to spend a tree leaf's P2TR refund output as a
66    /// BIP341 key-path spend (empty script tree).
67    async fn sign_leaf_refund_spend(
68        &self,
69        leaf_id: ExternalTreeNodeId,
70        sighash: Vec<u8>,
71    ) -> Result<SchnorrSignatureBytes, SignerError>;
72
73    /// Produce FROST shares for a batch of jobs.
74    async fn sign_frost(
75        &self,
76        jobs: Vec<ExternalFrostJob>,
77    ) -> Result<Vec<ExternalFrostShareResult>, SignerError>;
78
79    /// Prepare an outbound transfer (key-tweak + packages + payload signature).
80    async fn prepare_transfer(
81        &self,
82        request: ExternalPrepareTransferRequest,
83    ) -> Result<ExternalPreparedTransfer, SignerError>;
84
85    /// Claim an inbound transfer (key-tweak step).
86    async fn prepare_claim(
87        &self,
88        request: ExternalPrepareClaimRequest,
89    ) -> Result<ExternalPreparedClaim, SignerError>;
90
91    /// Prepare a Lightning receive (in-enclave preimage + Feldman split).
92    async fn prepare_lightning_receive(
93        &self,
94        request: ExternalPrepareLightningReceiveRequest,
95    ) -> Result<ExternalPreparedLightningReceive, SignerError>;
96
97    /// Prepare a static deposit (export secret to SSP + FROST-sign tree txs).
98    async fn prepare_static_deposit(
99        &self,
100        request: ExternalPrepareStaticDepositRequest,
101    ) -> Result<ExternalPreparedStaticDeposit, SignerError>;
102
103    /// Begin a static-deposit refund (user-commits-first).
104    async fn start_static_deposit_refund(
105        &self,
106        request: ExternalStartStaticDepositRefundRequest,
107    ) -> Result<ExternalStartedStaticDepositRefund, SignerError>;
108
109    /// Finish a static-deposit refund (aggregate into the final signature).
110    async fn sign_static_deposit_refund(
111        &self,
112        request: ExternalSignStaticDepositRefundRequest,
113    ) -> Result<ExternalFrostSignature, SignerError>;
114
115    /// Schnorr-sign a Spark invoice (sats or tokens) with the identity key.
116    async fn sign_spark_invoice(
117        &self,
118        request: ExternalSignSparkInvoiceRequest,
119    ) -> Result<ExternalSignedSparkInvoice, SignerError>;
120
121    /// Schnorr-sign a token-transaction digest with the identity key.
122    async fn prepare_token_transaction(
123        &self,
124        request: ExternalPrepareTokenTransactionRequest,
125    ) -> Result<ExternalPreparedTokenTransaction, SignerError>;
126
127    /// Prepare a static-deposit claim (export secret in the clear + sign).
128    async fn prepare_static_deposit_claim(
129        &self,
130        request: ExternalPrepareStaticDepositClaimRequest,
131    ) -> Result<ExternalPreparedStaticDepositClaim, SignerError>;
132}
breez_sdk_spark/signer/external_spark.rs

breez_sdk_spark/signer/
external_spark.rs
