[−][src]Struct grin_wallet_api::Foreign
Main interface into all wallet API functions. Wallet APIs are split into two seperate blocks of functionality called the 'Owner' and 'Foreign' APIs
- The 'Foreign' API contains methods that other wallets will use to interact with the owner's wallet. This API can be exposed to the outside world, with the consideration as to how that can be done securely up to the implementor.
Methods in both APIs are intended to be 'single use', that is to say each method will 'open' the wallet (load the keychain with its master seed), perform its operation, then 'close' the wallet (unloading references to the keychain and master seed).
Fields
wallet: Arc<Mutex<W>>
Wallet, contains its keychain (TODO: Split these up into 2 traits perhaps)
doctest_mode: bool
Flag to normalize some output during testing. Can mostly be ignored.
Methods
impl<'a, W: ?Sized, C, K> Foreign<W, C, K> where
W: WalletBackend<C, K>,
C: NodeClient,
K: Keychain,
[src]
W: WalletBackend<C, K>,
C: NodeClient,
K: Keychain,
pub fn new(wallet_in: Arc<Mutex<W>>) -> Self
[src]
Create a new API instance with the given wallet instance. All subsequent API calls will operate on this instance of the wallet.
Each method will call the WalletBackend
's
open_with_credentials
(initialising a keychain with the master seed), perform its operation, then close the keychain
with a call to close
Arguments
wallet_in
- A reference-counted mutex containing an implementation of theWalletBackend
trait.
Returns
- An instance of the ForeignApi holding a reference to the provided wallet
Example
use grin_wallet_util::grin_keychain as keychain; use grin_wallet_util::grin_util as util; use grin_wallet_api as api; use grin_wallet_config as config; use grin_wallet_impls as impls; use grin_wallet_libwallet as libwallet; use keychain::ExtKeychain; use tempfile::tempdir; use std::sync::Arc; use util::Mutex; use api::Foreign; use config::WalletConfig; use impls::{HTTPNodeClient, LMDBBackend}; use libwallet::WalletBackend; let mut wallet_config = WalletConfig::default(); // A NodeClient must first be created to handle communication between // the wallet and the node. let node_client = HTTPNodeClient::new(&wallet_config.check_node_api_http_addr, None); let mut wallet:Arc<Mutex<WalletBackend<HTTPNodeClient, ExtKeychain>>> = Arc::new(Mutex::new( LMDBBackend::new(wallet_config.clone(), "", node_client).unwrap() )); let api_owner = Foreign::new(wallet.clone()); // .. perform wallet operations
pub fn check_version(&self) -> Result<VersionInfo, Error>
[src]
Return the version capabilities of the running ForeignApi Node
Arguments
None
Returns
Example
Set up as in new
method above.
let mut api_foreign = Foreign::new(wallet.clone()); let version_info = api_foreign.check_version(); // check and proceed accordingly
pub fn build_coinbase(&self, block_fees: &BlockFees) -> Result<CbData, Error>
[src]
Builds a new unconfirmed coinbase output in the wallet, generally for inclusion in a potential new block's coinbase output during mining.
All potential coinbase outputs are created as 'Unconfirmed' with the coinbase flag set.
If a potential coinbase output is found on the chain after a wallet update, it status
is set to Unsent
and a Transaction Log Entry
will be created. Note the output will be unspendable until the coinbase maturity period
has expired.
Arguments
block_fees
- ABlockFees
struct, set up as follows:
fees
- should contain the sum of all transaction fees included in the potential
block
height
- should contain the block height being mined
key_id
- can optionally contain the corresponding keychain ID in the wallet to use
to create the output's blinding factor. If this is not provided, the next available key
id will be assigned
Returns
Ok
(cb_data
)
if successful. This will contain the corresponding output, kernel and keyID used to create the coinbase output.- or
libwallet::Error
if an error is encountered.
Example
Set up as in new
method above.
let mut api_foreign = Foreign::new(wallet.clone()); let block_fees = BlockFees { fees: 800000, height: 234323, key_id: None, }; // Build a new coinbase output let res = api_foreign.build_coinbase(&block_fees); if let Ok(cb_data) = res { // cb_data is populated with coinbase output info // ... }
pub fn verify_slate_messages(&self, slate: &Slate) -> Result<(), Error>
[src]
Verifies all messages in the slate match their public keys.
The option messages themselves are part of the participant_data
field within the slate.
Messages are signed with the same key used to sign for the paricipant's inputs, and can thus be
verified with the public key found in the public_blind_excess
field. This function is a
simple helper to returns whether all signatures in the participant data match their public
keys.
Arguments
slate
- The transactionSlate
.
Returns
Ok(())
if successful and the signatures validate- or
libwallet::Error
if an error is encountered.
Example
Set up as in new
method above.
let mut api_foreign = Foreign::new(wallet.clone()); // Receive a slate via some means let res = api_foreign.verify_slate_messages(&slate); if let Err(e) = res { // Messages don't validate, likely return an error // ... } else { // Slate messages are fine }
pub fn receive_tx(
&self,
slate: &Slate,
dest_acct_name: Option<&str>,
message: Option<String>
) -> Result<Slate, Error>
[src]
&self,
slate: &Slate,
dest_acct_name: Option<&str>,
message: Option<String>
) -> Result<Slate, Error>
Recieve a tranaction created by another party, returning the modified
Slate
object, modified with
the recipient's output for the transaction amount, and public signature data. This slate can
then be sent back to the sender to finalize the transaction via the
Owner API's finalize_tx
method.
This function creates a single output for the full amount, set to a status of 'Awaiting finalization'. It will remain in this state until the wallet finds the corresponding output on the chain, at which point it will become 'Unspent'. The slate will be updated with the results of Signing round 1 and 2, adding the recipient's public nonce, public excess value, and partial signature to the slate.
Also creates a corresponding Transaction Log Entry in the wallet's transaction log.
Arguments
slate
- The transactionSlate
. The slate should contain the results of the sender's round 1 (e.g, public nonce and public excess value).dest_acct_name
- The name of the account into which the slate should be received. IfNone
, the default account is used.message
- An optional participant message to include alongside the recipient's public ParticipantData within the slate. This message will include a signature created with the recipient's private excess value, and will be publically verifiable. Note this message is for the convenience of the participants during the exchange; it is not included in the final transaction sent to the chain. The message will be truncated to 256 characters. Validation of this message is optional.
Returns
- a result containing:
Ok
(slate
)
if successful, containing the new slate updated with the recipient's output and public signing information.- or
libwallet::Error
if an error is encountered.
Remarks
- This method will store a partially completed transaction in the wallet's transaction log.
Example
Set up as in new method above.
let mut api_foreign = Foreign::new(wallet.clone()); // . . . // Obtain a sent slate somehow let result = api_foreign.receive_tx(&slate, None, None); if let Ok(slate) = result { // Send back to recipient somehow // ... }
pub fn finalize_invoice_tx(&self, slate: &Slate) -> Result<Slate, Error>
[src]
Finalizes an invoice transaction initiated by this wallet's Owner api. This step assumes the paying party has completed round 1 and 2 of slate creation, and added their partial signatures. The invoicer will verify and add their partial sig, then create the finalized transaction, ready to post to a node.
Note that this function DOES NOT POST the transaction to a node
for validation. This is done in separately via the
post_tx
function.
This function also stores the final transaction in the user's wallet files for retrieval
via the get_stored_tx
function.
Arguments
slate
- The transactionSlate
. The payer should have filled in round 1 and 2.
Returns
- Ok(
slate
) if successful, containing the new finalized slate. - or
libwallet::Error
if an error is encountered.
Example
Set up as in new
method above.
let mut api_owner = Owner::new(wallet.clone()); let mut api_foreign = Foreign::new(wallet.clone()); // . . . // Issue the invoice tx via the owner API let args = IssueInvoiceTxArgs { amount: 10_000_000_000, ..Default::default() }; let result = api_owner.issue_invoice_tx(args); // If result okay, send to payer, who will apply the transaction via their // owner API, then send back the slate // ... let slate = api_foreign.finalize_invoice_tx(&slate); // if okay, then post via the owner API
Trait Implementations
impl<W: ?Sized, C, K> ForeignRpc for Foreign<W, C, K> where
W: WalletBackend<C, K>,
C: NodeClient,
K: Keychain,
[src]
W: WalletBackend<C, K>,
C: NodeClient,
K: Keychain,
fn check_version(&self) -> Result<VersionInfo, ErrorKind>
[src]
fn build_coinbase(&self, block_fees: &BlockFees) -> Result<CbData, ErrorKind>
[src]
fn verify_slate_messages(&self, slate: &Slate) -> Result<(), ErrorKind>
[src]
fn receive_tx(
&self,
slate: VersionedSlate,
dest_acct_name: Option<String>,
message: Option<String>
) -> Result<VersionedSlate, ErrorKind>
[src]
&self,
slate: VersionedSlate,
dest_acct_name: Option<String>,
message: Option<String>
) -> Result<VersionedSlate, ErrorKind>
fn finalize_invoice_tx(&self, slate: &Slate) -> Result<Slate, ErrorKind>
[src]
Auto Trait Implementations
impl<W: ?Sized, C, K> Send for Foreign<W, C, K> where
W: Send,
W: Send,
impl<W: ?Sized, C, K> Sync for Foreign<W, C, K> where
W: Send,
W: Send,
Blanket Implementations
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T> From<T> for T
[src]
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Erased for T
impl<T> UnsafeAny for T where
T: Any,
T: Any,
impl<T> SafeBorrow<T> for T where
T: ?Sized,
T: ?Sized,
fn borrow_replacement(ptr: &T) -> &T
impl<T> Same<T> for T
type Output = T
Should always be Self