APIs in TimestampVM

Throughout this case study, we have been focusing of the functionality of the TimestampVM. However, one thing we haven't discussed is how external users can interact with an instance of TimestampVM. Without a way for users to interact with TimestampVM, the blockchain itself will be stagnant. In this section, we will go over the two types of APIs used in TimestampVM:

• Static APIs
• Chain APIs

Precursor: Static and Instance Methods

When understanding the static and chain APIs used in TimestampVM, a good way to think about these APIs is to compare them to static and instance methods in object-oriented programming. That is,

• Static Methods: functions which belong to the class itself, and not any instance of the class
• Instance Methods: functions which belong to the instance of a class

Static APIs

We can think of the static APIs in TimestampVM as functions which call the VM and are not associated with any specific instance of the TimestampVM. Within TimestampVM, we have just one static API function - the ping function:

timestampvm/src/api/static_handlers.rs

/// Defines static handler RPCs for this VM.
#[rpc]
pub trait Rpc {
    #[rpc(name = "ping", alias("timestampvm.ping"))]
    fn ping(&self) -> BoxFuture<Result<crate::api::PingResponse>>;
}

Chain APIs

In contrast to the static API, the chain API of TimestampVM is much more rich in the sense that we have functions with read from and write to an instance of TimestampVM. In this case, we have four functions defined in the chain API:

• ping: when called, this function pings an instance of TimestampVM
• propose_Block: write function which passes a block to TimestampVM for consideration to be appended to the blockchain
• last_accepted: read function which returns the last accepted block (that is, the block at the tip of the blockchain)
• get_block: read function which fetches the requested block

We can see the functions included in the chain API here:

timestampvm/src/api/chain_handlers.rs

/// Defines RPCs specific to the chain.
#[rpc]
pub trait Rpc {
    /// Pings the VM.
    #[rpc(name = "ping", alias("timestampvm.ping"))]
    fn ping(&self) -> BoxFuture<Result<crate::api::PingResponse>>;

    /// Proposes the arbitrary data.
    #[rpc(name = "proposeBlock", alias("timestampvm.proposeBlock"))]
    fn propose_block(&self, args: ProposeBlockArgs) -> BoxFuture<Result<ProposeBlockResponse>>;

    /// Fetches the last accepted block.
    #[rpc(name = "lastAccepted", alias("timestampvm.lastAccepted"))]
    fn last_accepted(&self) -> BoxFuture<Result<LastAcceptedResponse>>;

    /// Fetches the block.
    #[rpc(name = "getBlock", alias("timestampvm.getBlock"))]
    fn get_block(&self, args: GetBlockArgs) -> BoxFuture<Result<GetBlockResponse>>;
}