ddk_manager/
lib.rs

1//! # Library providing data structures and functions supporting the execution
2//! and management of DLC.
3
4#![crate_name = "ddk_manager"]
5// Coding conventions
6#![forbid(unsafe_code)]
7#![deny(non_upper_case_globals)]
8#![deny(non_camel_case_types)]
9#![deny(non_snake_case)]
10#![deny(unused_mut)]
11#![deny(dead_code)]
12#![deny(unused_imports)]
13#![deny(missing_docs)]
14
15#[macro_use]
16extern crate ddk_messages;
17
18pub mod chain_monitor;
19pub mod channel;
20pub mod channel_updater;
21pub mod contract;
22pub mod contract_updater;
23mod conversion_utils;
24mod dlc_input;
25pub mod error;
26pub mod manager;
27pub mod payout_curve;
28mod utils;
29
30use bitcoin::psbt::Psbt;
31use bitcoin::{Address, Amount, Block, OutPoint, ScriptBuf, Transaction, TxOut, Txid};
32use chain_monitor::ChainMonitor;
33use channel::offered_channel::OfferedChannel;
34use channel::signed_channel::{SignedChannel, SignedChannelStateType};
35use channel::Channel;
36use contract::PreClosedContract;
37use contract::{offered_contract::OfferedContract, signed_contract::SignedContract, Contract};
38use ddk_messages::impl_dlc_writeable;
39use ddk_messages::oracle_msgs::{OracleAnnouncement, OracleAttestation};
40use ddk_messages::ser_impls::{read_address, write_address};
41use error::Error;
42use lightning::ln::msgs::DecodeError;
43use lightning::util::ser::{Readable, Writeable, Writer};
44use secp256k1_zkp::{PublicKey, SecretKey, Signing};
45use secp256k1_zkp::{Secp256k1, XOnlyPublicKey};
46use std::collections::HashMap;
47use std::ops::Deref;
48use std::sync::RwLock;
49
50/// Type alias for a contract id.
51pub type ContractId = [u8; 32];
52
53/// Type alias for a keys id.
54pub type KeysId = [u8; 32];
55
56/// Type alias for a channel id.
57pub type ChannelId = [u8; 32];
58
59/// Time trait to provide current unix time. Mainly defined to facilitate testing.
60pub trait Time {
61    /// Must return the unix epoch corresponding to the current time.
62    fn unix_time_now(&self) -> u64;
63}
64
65/// Provide current time through `SystemTime`.
66#[derive(Debug)]
67pub struct SystemTimeProvider {}
68
69impl Time for SystemTimeProvider {
70    fn unix_time_now(&self) -> u64 {
71        let now = std::time::SystemTime::now();
72        now.duration_since(std::time::UNIX_EPOCH)
73            .expect("Unexpected time error")
74            .as_secs()
75    }
76}
77
78/// Provides signing related functionalities.
79pub trait ContractSigner: Clone {
80    /// Get the public key associated with the [`ContractSigner`].
81    fn get_public_key<C: Signing>(&self, secp: &Secp256k1<C>) -> Result<PublicKey, Error>;
82    /// Returns the secret key associated with the [`ContractSigner`].
83    // todo: remove this method and add create_adaptor_signature to the trait
84    fn get_secret_key(&self) -> Result<SecretKey, Error>;
85}
86
87/// Simple sample implementation of [`ContractSigner`].
88#[derive(Debug, Copy, Clone)]
89pub struct SimpleSigner {
90    secret_key: SecretKey,
91}
92
93impl SimpleSigner {
94    /// Creates a new [`SimpleSigner`] from the provided secret key.
95    pub fn new(secret_key: SecretKey) -> Self {
96        Self { secret_key }
97    }
98}
99
100impl ContractSigner for SimpleSigner {
101    fn get_public_key<C: Signing>(&self, secp: &Secp256k1<C>) -> Result<PublicKey, Error> {
102        Ok(self.secret_key.public_key(secp))
103    }
104
105    fn get_secret_key(&self) -> Result<SecretKey, Error> {
106        Ok(self.secret_key)
107    }
108}
109
110impl ContractSigner for SecretKey {
111    fn get_public_key<C: Signing>(&self, secp: &Secp256k1<C>) -> Result<PublicKey, Error> {
112        Ok(self.public_key(secp))
113    }
114
115    fn get_secret_key(&self) -> Result<SecretKey, Error> {
116        Ok(*self)
117    }
118}
119
120/// Derives a [`ContractSigner`] from a [`ContractSignerProvider`] and a `contract_keys_id`.
121pub trait ContractSignerProvider {
122    /// A type which implements [`ContractSigner`]
123    type Signer: ContractSigner;
124
125    /// Create a keys id for deriving a `Signer`.
126    fn derive_signer_key_id(&self, is_offer_party: bool, temp_id: [u8; 32]) -> [u8; 32];
127
128    /// Derives the private key material backing a `Signer`.
129    fn derive_contract_signer(&self, key_id: [u8; 32]) -> Result<Self::Signer, Error>;
130
131    /// Get the secret key associated with the provided public key.
132    ///
133    /// Only used for Channels.
134    fn get_secret_key_for_pubkey(&self, pubkey: &PublicKey) -> Result<SecretKey, Error>;
135    /// Generate a new secret key and store it in the wallet so that it can later be retrieved.
136    ///
137    /// Only used for Channels.
138    fn get_new_secret_key(&self) -> Result<SecretKey, Error>;
139}
140
141#[async_trait::async_trait]
142/// Wallet trait to provide functionalities related to generating, storing and
143/// managing bitcoin addresses and UTXOs.
144pub trait Wallet {
145    /// Returns a new (unused) address.
146    async fn get_new_address(&self) -> Result<Address, Error>;
147    /// Returns a new (unused) change address.
148    async fn get_new_change_address(&self) -> Result<Address, Error>;
149    /// Get a set of UTXOs to fund the given amount.
150    async fn get_utxos_for_amount(
151        &self,
152        amount: Amount,
153        fee_rate: u64,
154        lock_utxos: bool,
155    ) -> Result<Vec<Utxo>, Error>;
156    /// Signs a transaction input
157    async fn sign_psbt_input(&self, psbt: &mut Psbt, input_index: usize) -> Result<(), Error>;
158    /// Import the provided address.
159    fn import_address(&self, address: &Address) -> Result<(), Error>;
160    /// Unlock reserved utxo
161    fn unreserve_utxos(&self, outpoints: &[OutPoint]) -> Result<(), Error>;
162}
163
164#[async_trait::async_trait]
165/// Blockchain trait provides access to the bitcoin blockchain.
166pub trait Blockchain {
167    /// Broadcast the given transaction to the bitcoin network.
168    async fn send_transaction(&self, transaction: &Transaction) -> Result<(), Error>;
169    /// Returns the network currently used (mainnet, testnet or regtest).
170    fn get_network(&self) -> Result<bitcoin::Network, Error>;
171    /// Returns the height of the blockchain
172    async fn get_blockchain_height(&self) -> Result<u64, Error>;
173    /// Returns the block at given height
174    async fn get_block_at_height(&self, height: u64) -> Result<Block, Error>;
175    /// Get the transaction with given id.
176    async fn get_transaction(&self, tx_id: &Txid) -> Result<Transaction, Error>;
177    /// Get the number of confirmation for the transaction with given id.
178    async fn get_transaction_confirmations(&self, tx_id: &Txid) -> Result<u32, Error>;
179}
180
181#[async_trait::async_trait]
182/// Storage trait provides functionalities to store and retrieve DLCs.
183pub trait Storage {
184    /// Returns the contract with given id if found.
185    async fn get_contract(&self, id: &ContractId) -> Result<Option<Contract>, Error>;
186    /// Return all contracts
187    async fn get_contracts(&self) -> Result<Vec<Contract>, Error>;
188    /// Create a record for the given contract.
189    async fn create_contract(&self, contract: &OfferedContract) -> Result<(), Error>;
190    /// Delete the record for the contract with the given id.
191    async fn delete_contract(&self, id: &ContractId) -> Result<(), Error>;
192    /// Update the given contract.
193    async fn update_contract(&self, contract: &Contract) -> Result<(), Error>;
194    /// Returns the set of contracts in offered state.
195    async fn get_contract_offers(&self) -> Result<Vec<OfferedContract>, Error>;
196    /// Returns the set of contracts in signed state.
197    async fn get_signed_contracts(&self) -> Result<Vec<SignedContract>, Error>;
198    /// Returns the set of confirmed contracts.
199    async fn get_confirmed_contracts(&self) -> Result<Vec<SignedContract>, Error>;
200    /// Returns the set of contracts whos broadcasted cet has not been verified to be confirmed on
201    /// blockchain
202    async fn get_preclosed_contracts(&self) -> Result<Vec<PreClosedContract>, Error>;
203    /// Update the state of the channel and optionally its associated contract
204    /// atomically.
205    async fn upsert_channel(
206        &self,
207        channel: Channel,
208        contract: Option<Contract>,
209    ) -> Result<(), Error>;
210    /// Delete the channel with given [`ChannelId`] if any.
211    async fn delete_channel(&self, channel_id: &ChannelId) -> Result<(), Error>;
212    /// Returns the channel with given [`ChannelId`] if any.
213    async fn get_channel(&self, channel_id: &ChannelId) -> Result<Option<Channel>, Error>;
214    /// Returns the set of [`SignedChannel`] in the store. Returns only the one
215    /// with matching `channel_state` if set.
216    async fn get_signed_channels(
217        &self,
218        channel_state: Option<SignedChannelStateType>,
219    ) -> Result<Vec<SignedChannel>, Error>;
220    /// Returns the set of channels in offer state.
221    async fn get_offered_channels(&self) -> Result<Vec<OfferedChannel>, Error>;
222    /// Writes the [`ChainMonitor`] data to the store.
223    async fn persist_chain_monitor(&self, monitor: &ChainMonitor) -> Result<(), Error>;
224    /// Returns the latest [`ChainMonitor`] in the store if any.
225    async fn get_chain_monitor(&self) -> Result<Option<ChainMonitor>, Error>;
226}
227
228#[async_trait::async_trait]
229/// Oracle trait provides access to oracle information.
230pub trait Oracle {
231    /// Returns the public key of the oracle.
232    fn get_public_key(&self) -> XOnlyPublicKey;
233    /// Returns the announcement for the event with the given id if found.
234    async fn get_announcement(&self, event_id: &str) -> Result<OracleAnnouncement, Error>;
235    /// Returns the attestation for the event with the given id if found.
236    async fn get_attestation(&self, event_id: &str) -> Result<OracleAttestation, Error>;
237}
238
239/// Represents a UTXO.
240#[derive(Clone, Debug)]
241pub struct Utxo {
242    /// The TxOut containing the value and script pubkey of the referenced output.
243    pub tx_out: TxOut,
244    /// The outpoint containing the txid and vout of the referenced output.
245    pub outpoint: OutPoint,
246    /// The address associated with the referenced output.
247    pub address: Address,
248    /// The redeem script for the referenced output.
249    pub redeem_script: ScriptBuf,
250    /// Whether this Utxo has been reserved (and so should not be used to fund
251    /// a DLC).
252    pub reserved: bool,
253}
254
255impl_dlc_writeable!(Utxo, {
256    (tx_out, writeable),
257    (outpoint, writeable),
258    (address, {cb_writeable, write_address, read_address}),
259    (redeem_script, writeable),
260    (reserved, writeable)
261});
262
263/// A ContractSignerProvider that caches the signers
264#[derive(Debug)]
265pub struct CachedContractSignerProvider<SP: Deref, X>
266where
267    SP::Target: ContractSignerProvider<Signer = X>,
268{
269    pub(crate) signer_provider: SP,
270    pub(crate) cache: RwLock<HashMap<KeysId, X>>,
271}
272
273impl<SP: Deref, X> CachedContractSignerProvider<SP, X>
274where
275    SP::Target: ContractSignerProvider<Signer = X>,
276{
277    /// Create a new [`ContractSignerProvider`]
278    pub fn new(signer_provider: SP) -> Self {
279        Self {
280            signer_provider,
281            cache: RwLock::new(HashMap::new()),
282        }
283    }
284}
285
286impl<SP: Deref, X: ContractSigner> ContractSignerProvider for CachedContractSignerProvider<SP, X>
287where
288    SP::Target: ContractSignerProvider<Signer = X>,
289{
290    type Signer = X;
291
292    fn derive_signer_key_id(&self, is_offer_party: bool, temp_id: [u8; 32]) -> KeysId {
293        self.signer_provider
294            .derive_signer_key_id(is_offer_party, temp_id)
295    }
296
297    fn derive_contract_signer(&self, key_id: KeysId) -> Result<Self::Signer, Error> {
298        match self.cache.try_read().unwrap().get(&key_id) {
299            Some(signer) => Ok(signer.clone()),
300            None => self.signer_provider.derive_contract_signer(key_id),
301        }
302    }
303
304    fn get_secret_key_for_pubkey(&self, pubkey: &PublicKey) -> Result<SecretKey, Error> {
305        self.signer_provider.get_secret_key_for_pubkey(pubkey)
306    }
307
308    fn get_new_secret_key(&self) -> Result<SecretKey, Error> {
309        self.signer_provider.get_new_secret_key()
310    }
311}
ddk_manager/lib.rs

ddk_manager/
lib.rs
