Struct grin_api::Foreign

pub struct Foreign<B, P>
where
    B: BlockChain,
    P: PoolAdapter,
{
    pub chain: Weak<Chain>,
    pub tx_pool: Weak<RwLock<TransactionPool<B, P>>>,
    pub sync_state: Weak<SyncState>,
}

Main interface into all node API functions. Node APIs are split into two seperate blocks of functionality called the ‘Owner’ and ‘Foreign’ APIs

Methods in this API are intended to be ‘single use’.

Fields

chain: Weak<Chain>

tx_pool: Weak<RwLock<TransactionPool<B, P>>>

sync_state: Weak<SyncState>

Implementations

impl<B, P> Foreign<B, P>

where B: BlockChain, P: PoolAdapter,

pub fn new( chain: Weak<Chain>, tx_pool: Weak<RwLock<TransactionPool<B, P>>>, sync_state: Weak<SyncState> ) -> Self

Create a new API instance with the chain, transaction pool, peers and sync_state. All subsequent API calls will operate on this instance of node API.

Arguments

• chain - A non-owning reference of the chain.
• tx_pool - A non-owning reference of the transaction pool.
• sync_state - A non-owning reference of the sync_state.

Returns

• An instance of the Node holding references to the current chain, transaction pool, peers and sync_state.

pub fn get_header( &self, height: Option<u64>, hash: Option<Hash>, commit: Option<String> ) -> Result<BlockHeaderPrintable, Error>

Gets block header given either a height, a hash or an unspent output commitment. Only one parameters is needed. If multiple parameters are provided only the first one in the list is used.

Arguments

• height - block height.
• hash - block hash.
• commit - output commitment.

Returns

• Result Containing:
• A BlockHeaderPrintable
• or Error if an error is encountered.

pub fn get_block( &self, height: Option<u64>, hash: Option<Hash>, commit: Option<String> ) -> Result<BlockPrintable, Error>

Gets block details given either a height, a hash or an unspent output commitment. Only one parameters is needed. If multiple parameters are provided only the first one in the list is used.

Arguments

• height - block height.
• hash - block hash.
• commit - output commitment.

Returns

• Result Containing:
• A BlockPrintable
• or Error if an error is encountered.

pub fn get_blocks( &self, start_height: u64, end_height: u64, max: u64, include_proof: Option<bool> ) -> Result<BlockListing, Error>

Returns a BlockListing of available blocks between min_height and max_height The method will query the database for blocks starting at the block height min_height and continue until max_height, skipping any blocks that aren’t available.

Arguments

• start_height - starting height to lookup.
• end_height - ending height to to lookup.
• ’max` - The max number of blocks to return. Note this is overriden with BLOCK_TRANSFER_LIMIT if BLOCK_TRANSFER_LIMIT is exceeded

Returns

• Result Containing:
• A BlockListing
• or Error if an error is encountered.

pub fn get_version(&self) -> Result<Version, Error>

Returns the node version and block header version (used by grin-wallet).

Returns

• Result Containing:
• A Version
• or Error if an error is encountered.

pub fn get_tip(&self) -> Result<Tip, Error>

Returns details about the state of the current fork tip.

Returns

• Result Containing:
• A Tip
• or Error if an error is encountered.

pub fn get_kernel( &self, excess: String, min_height: Option<u64>, max_height: Option<u64> ) -> Result<LocatedTxKernel, Error>

Returns a LocatedTxKernel based on the kernel excess. The min_height and max_height parameters are both optional. If not supplied, min_height will be set to 0 and max_height will be set to the head of the chain. The method will start at the block height max_height and traverse the kernel MMR backwards, until either the kernel is found or min_height is reached.

Arguments

• excess - kernel excess to look for.
• min_height - minimum height to stop the lookup.
• max_height - maximum height to start the lookup.

Returns

• Result Containing:
• A LocatedTxKernel
• or Error if an error is encountered.

pub fn get_outputs( &self, commits: Option<Vec<String>>, start_height: Option<u64>, end_height: Option<u64>, include_proof: Option<bool>, include_merkle_proof: Option<bool> ) -> Result<Vec<OutputPrintable>, Error>

Retrieves details about specifics outputs. Supports retrieval of multiple outputs in a single request. Support retrieval by both commitment string and block height.

Arguments

• commits - a vector of unspent output commitments.
• start_height - start height to start the lookup.
• end_height - end height to stop the lookup.
• include_proof - whether or not to include the range proof in the response.
• include_merkle_proof - whether or not to include the merkle proof in the response.

Returns

• Result Containing:
• An OutputPrintable
• or Error if an error is encountered.

pub fn get_unspent_outputs( &self, start_index: u64, end_index: Option<u64>, max: u64, include_proof: Option<bool> ) -> Result<OutputListing, Error>

UTXO traversal. Retrieves last utxos since a start_index until a max.

Arguments

• start_index - start index in the MMR.
• end_index - optional index so stop in the MMR.
• max - max index in the MMR.
• include_proof - whether or not to include the range proof in the response.

Returns

• Result Containing:
• An OutputListing
• or Error if an error is encountered.

pub fn get_pmmr_indices( &self, start_block_height: u64, end_block_height: Option<u64> ) -> Result<OutputListing, Error>

Retrieves the PMMR indices based on the provided block height(s).

Arguments

• start_block_height - start index in the MMR.
• end_block_height - optional index so stop in the MMR.

Returns

• Result Containing:
• An OutputListing
• or Error if an error is encountered.

pub fn get_pool_size(&self) -> Result<usize, Error>

Returns the number of transaction in the transaction pool.

Returns

• Result Containing:
• usize
• or Error if an error is encountered.

pub fn get_stempool_size(&self) -> Result<usize, Error>

Returns the number of transaction in the stem transaction pool.

Returns

• Result Containing:
• usize
• or Error if an error is encountered.

pub fn get_unconfirmed_transactions(&self) -> Result<Vec<PoolEntry>, Error>

Returns the unconfirmed transactions in the transaction pool. Will not return transactions in the stempool.

Returns

• Result Containing:
• A vector of PoolEntry
• or Error if an error is encountered.

pub fn push_transaction( &self, tx: Transaction, fluff: Option<bool> ) -> Result<(), Error>

Push new transaction to our local transaction pool.

Arguments

• tx - the Grin transaction to push.
• fluff - boolean to bypass Dandelion relay.

Returns

• Result Containing:
• Ok(()) if the transaction was pushed successfully
• or Error if an error is encountered.

Trait Implementations

impl<B, P> ForeignRpc for Foreign<B, P>

where B: BlockChain, P: PoolAdapter,

fn get_header( &self, height: Option<u64>, hash: Option<String>, commit: Option<String> ) -> Result<BlockHeaderPrintable, Error>

Networked version of Foreign::get_header.

fn get_block( &self, height: Option<u64>, hash: Option<String>, commit: Option<String> ) -> Result<BlockPrintable, Error>

Networked version of Foreign::get_block.

fn get_blocks( &self, start_height: u64, end_height: u64, max: u64, include_proof: Option<bool> ) -> Result<BlockListing, Error>

Networked version of Foreign::get_blocks.

fn get_version(&self) -> Result<Version, Error>

Networked version of Foreign::get_version.

fn get_tip(&self) -> Result<Tip, Error>

Networked version of Foreign::get_tip.

fn get_kernel( &self, excess: String, min_height: Option<u64>, max_height: Option<u64> ) -> Result<LocatedTxKernel, Error>

Networked version of Foreign::get_kernel.

fn get_outputs( &self, commits: Option<Vec<String>>, start_height: Option<u64>, end_height: Option<u64>, include_proof: Option<bool>, include_merkle_proof: Option<bool> ) -> Result<Vec<OutputPrintable>, Error>

Networked version of Foreign::get_outputs.

fn get_unspent_outputs( &self, start_index: u64, end_index: Option<u64>, max: u64, include_proof: Option<bool> ) -> Result<OutputListing, Error>

Networked version of Foreign::get_unspent_outputs.

fn get_pmmr_indices( &self, start_block_height: u64, end_block_height: Option<u64> ) -> Result<OutputListing, Error>

Networked version of Foreign::get_pmmr_indices.

fn get_pool_size(&self) -> Result<usize, Error>

Networked version of Foreign::get_pool_size.

fn get_stempool_size(&self) -> Result<usize, Error>

Networked version of Foreign::get_stempool_size.

fn get_unconfirmed_transactions(&self) -> Result<Vec<PoolEntry>, Error>

Networked version of Foreign::get_unconfirmed_transactions.

fn push_transaction( &self, tx: Transaction, fluff: Option<bool> ) -> Result<(), Error>

Networked version of Foreign::push_transaction.