Crate tari_template_lib

Expand description

This crate provides ergonomic abstractions that allow WASM templates to interact with the Tari Ootle engine. Almost all Ootle templates written in Rust should depend on this crate.

Include the template prelude which provides all the necessary imports for writing templates. This includes common types (e.g. Component, Resource, Vault, AccessRule etc.) and macros (e.g. the template macro).

use tari_template_lib::prelude::*;

§Getting started

Include this crate in your Cargo.toml:

[dependencies]
tari_template_lib = { version = "*" } # Or specify a specific version

Apply the template macro and define your template struct and its methods. This macro generates the necessary ABI functions and boilerplate to make your template work with the Ootle engine.

use tari_template_lib::prelude::*;

// The `template` macro generates and implements the necessary ABI functions, `TemplateDefinition` and other boilerplate that
// hooks up the functions and methods you define to the Ootle execution engine.
// The module name is not important (it is ignored). The `template` macro must be applied to the module that contains your template struct/enum.
#[template]
mod my_template {
   // Bring prelude and anything else into scope.
   use super::*;

   /// Defines the component state that is stored on-chain. This can be a struct or an enum.
   /// The struct/enum name can be selected arbitrarily, and is exposed in the TemplateDefinition for the template.
   pub struct MyCounter {
      counter: u64,
      /// Vaults contain resources. A vault is a separate substate created within a component, and belongs to that component.
      vault: Vault,
   }

   impl MyCounter {
     /// A simple constructor.
     /// NOTE: this is a convenience constructor that implicitly creates a component with some defaults. These defaults are restrictive for many use cases
     /// for e.g. all component methods are only callable by the component owner (i.e. the same signer that created the component must sign the transaction
     /// to call any method).
     /// To see how to customise this, see the `custom` constructor below.
     pub fn new() -> Self {
         Self {
            counter: 0,
            // A empty vault that can only hold the native token (XTR). You can also create vaults that hold your own resources (see the `ResourceBuilder`).
            vault: Vault::new_empty(XTR),
         }
     }

     /// This constructor provides more control over the component configuration.
     ///
     /// ## Arguments
     /// - `address`: An component address allocation. This allows a single transaction to both create and call onto the created component without knowing the component address in advance.
     /// - `access_rules`: Custom method access rules for the component. All methods referenced in the access rules must be defined on the component or the transaction will fail.
     /// - `owner_rule`: Custom owner rule for the component. The owner of a component is able to change access rules and call all methods. Setting `OwnerRule::None` means the component has no owner and all access rules are immutable.
     pub fn custom(address: ComponentAddressAllocation, access_rules: ComponentAccessRules, owner_rule: OwnerRule) -> Component<Self> {
       // Call `new` which initialises the component state. NOTE that this is a completely normal function call. The component
       // is not yet created on-chain.
       let component = Self::new();

       Component::new(component)
          .with_address_allocation(address)
          .with_access_rules(access_rules)
          .with_owner_rule(owner_rule)
          // Create the component on-chain
          .create()
     }

    /// Increment the counter by 1. The `CallMethod` instruction is used to invoke this method.
    /// This method is callable as per the access rules defined for the component.
    pub fn increment(&mut self) {
      self.counter += 1;
    }

    /// A simple associated function that returns a string. The `CallFunction` instruction is used to invoke this function.
    /// Apart from defining constructors, associated functions can provide any shared functionality callable by anyone.
    pub fn some_function(name: String, number: u64) -> String {
       format!("Hello {name}, the number is {number}")
    }
  }
}

§Template Examples

§Re-exports

This crate re-exports common types (tari_template_lib_types), low-level ABI functions in tari_template_abi and the tari_template_macros proc macro.

§no_std

This crate supports no_std environments. To use in no_std, disable the std feature (default-features = false) and enable the alloc feature.

[dependencies]
tari_template_lib = { version = "*", default-features = false, features = ["alloc"] }

You will need to provide a global allocator (e.g. talc, lol_alloc). This crate provides a panic handler for no_std.

Re-exports§

pub use tari_template_lib_types as types;
pub use tari_bor::serde;

Modules§

args: Definitions and utilities related to instruction arguments
caller_context: Context definitions related to the caller of an instruction
component: Utilities for building and managing components inside templates
events: A wrapper for engine calls related to events
macros: Rust macros that can be used inside templates
models: The collection of all struct definitions that represent data in the Tari network (e.g., resources, components, proofs, etc.)
panic_hook: Hook that implements common behavior when a panic happens during template execution
prelude: The prelude contains all the commonly used types and functions that are used. To use it, add the import use tari_template_lib::prelude::*;
rand: Utilities to get random values inside templates
resource: Utilities for building and managing resources inside templates.
template: Utilities related to templates
template_macro_deps: Public types that are available to internal template code.

Macros§

__expr_counter: Low-level macro used for counting characters in the encoding of arguments. Not intended for general usage
debug: Macro for emitting debug log messages from inside templates
engine_debug: Macro that calls the engine debug function from inside templates. No-op unless the engine is in debug mode.
error: Macro for emitting error log messages from inside templates
info: Macro for emitting log messages from inside templates
invoke_arg: Low-level macro used for encoding the arguments of engine calls. Not intended for general usage
invoke_args: Low-level macro used for encoding the arguments of engine calls. Not intended for general usage
log: Macro for emitting log messages from inside templates
warn: Macro for emitting warn log messages from inside templates

Structs§

Consensus: The Consensus module provides access to data about the current state of the chain. Currently, it only exposes the epoch via current_epoch.

Functions§

engine: Returns the corresponding TariEngine of the current template execution
to_value: Encodes any Rust type using CBOR