melwalletd_prot/
protocol.rs

1use crate::types::{
2    CreateWalletError, NeedWallet, NetworkError, PrepareTxArgs, PrepareTxError, SwapInfo,
3    TransactionStatus, TxBalance, WalletAccessError, WalletSummary,
4};
5
6use async_trait::async_trait;
7use melstructs::{BlockHeight, CoinData, CoinID, Denom, Transaction, TxHash};
8use melstructs::{Header, PoolKey, PoolState};
9use nanorpc::nanorpc_derive;
10use std::fmt::Debug;
11use tmelcrypt::HashVal;
12
13#[nanorpc_derive]
14#[async_trait]
15/// A [macro@nanorpc_derive] trait that describes the RPC protocol exposed by a `melwalletd` daemon.
16///
17/// **Note**: since the trait uses [macro@async_trait], the function signatures shown in the documentation are a little funky. The "human readable" versions are merely async methods; for example [MelwalletdProtocol::wallet_summary] should be implemented like
18/// ```ignore
19/// #[async_trait]
20/// impl MelwalletdProtocol for YourBusinessLogic {
21///     //...
22///     async fn wallet_summary(&self, wallet_name: String)
23///         -> Result<WalletSummary, WalletAccessError> {
24///         todo!()
25///     }
26/// }
27/// ```
28pub trait MelwalletdProtocol: Send + Sync {
29    /// Returns a list of wallet names.
30    async fn list_wallets(&self) -> Vec<String>;
31
32    /// Returns a summary of the overall state of the wallet. See [WalletSummary] for what that entails.
33    async fn wallet_summary(&self, wallet_name: String)
34        -> Result<WalletSummary, WalletAccessError>;
35
36    /// Returns the latest blockchain header.
37    async fn latest_header(&self) -> Result<Header, NetworkError>;
38
39    /// Obtains up-to-date information about a particular melswap pool, identified by its [PoolKey]. Returns `None` if no such pool exists.
40    async fn melswap_info(&self, pool_key: PoolKey) -> Result<Option<PoolState>, NetworkError>;
41
42    /// Simulates a swap between the two given [Denom]s, returning a [SwapInfo] that contains detailed information about the swap (such as price, slippage, etc)
43    async fn simulate_swap(
44        &self,
45        to: Denom,
46        from: Denom,
47        value: u128,
48    ) -> Result<Option<SwapInfo>, NetworkError>;
49
50    /// Creates a wallet. If `secret` is provided, this must be a base32-encoded ed25519 private key.
51    async fn create_wallet(
52        &self,
53        wallet_name: String,
54        password: String,
55        secret: Option<String>,
56    ) -> Result<(), CreateWalletError>;
57
58    /// Dump all the coins of a given wallet.
59    async fn dump_coins(
60        &self,
61        wallet_name: String,
62    ) -> Result<Vec<(CoinID, CoinData)>, WalletAccessError>;
63
64    /// Dumps the transactions history of the given wallet.
65    async fn dump_transactions(
66        &self,
67        wallet_name: String,
68    ) -> Result<Vec<(TxHash, Option<BlockHeight>)>, WalletAccessError>;
69
70    /// Locks the wallet.
71    async fn lock_wallet(&self, wallet_name: String) -> Result<(), WalletAccessError>;
72
73    /// Unlocks the given wallet. If the password is incorrect, will return [WalletAccessError::Locked].
74    async fn unlock_wallet(
75        &self,
76        wallet_name: String,
77        password: String,
78    ) -> Result<(), WalletAccessError>;
79
80    /// Exports the secret key, in the standard base32 format, from the given wallet. The password must be correct; if it is not, will return [WalletAccessError::Locked].
81    async fn export_sk(
82        &self,
83        wallet_name: String,
84        password: String,
85    ) -> Result<String, WalletAccessError>;
86
87    /// Prepares a transaction according to a template (see [PrepareTxArgs]). Returns a transaction that is ready for inspection.
88    ///
89    /// This method does not change the internal state of the wallet or send any transactions. Once you're sure you want to send the transaction returned, simply pass it to [MelwalletdProtocol::send_tx].
90    async fn prepare_tx(
91        &self,
92        wallet_name: String,
93        request: PrepareTxArgs,
94    ) -> Result<Transaction, NeedWallet<PrepareTxError>>;
95
96    /// Sends a transaction to the network, returning its hash. Note that the absence of an error does *not* mean that the transaction will certainly go through!
97    async fn send_tx(
98        &self,
99        wallet_name: String,
100        tx: Transaction,
101    ) -> Result<TxHash, NeedWallet<NetworkError>>;
102
103    /// Returns the "balance" (see [TxBalance]) of a transaction --- how much it increased or decreased the balance of the wallet. If such a transaction doesn't exist in the given wallet, returns `Ok(None)`.
104    async fn tx_balance(
105        &self,
106        wallet_name: String,
107        txhash: HashVal,
108    ) -> Result<Option<TxBalance>, WalletAccessError>;
109
110    /// Returns the status ([TransactionStatus]) of a transaction, which includes its full contents as well as where, if anywhere, was it confirmed. If no such transaction can be found, or if the wallet has given up on the transaction already, returns `Ok(None)`.
111    async fn tx_status(
112        &self,
113        wallet_name: String,
114        txhash: HashVal,
115    ) -> Result<Option<TransactionStatus>, WalletAccessError>;
116
117    /// A convenience method for sending 1000 MEL of a faucet transaction to the wallet itself.
118    async fn send_faucet(&self, wallet_name: String) -> Result<TxHash, NeedWallet<NetworkError>>;
119}
melwalletd_prot/protocol.rs

melwalletd_prot/
protocol.rs
