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

breez_sdk_spark/signer/
external_spark.rs
