Crate piecrust_uplink

Piecrust Uplink is the crate for writing WASM smart contracts in Rust targeting the Piecrust virtual machine.

A smart contract is a program exposing a collection of functions that operate on a shared state. These functions can perform a variety of operations, such as reading or modifying the state, or interacting with the host.

State Model and ABI

Contracts targeting the Piecrust VM represent their state as a WASM memory. The contract is free to represent its data as it sees fit, and may allocate at will.

To communicate with the host, both the contract and the host can emplace data in a special region of this memory called the argument buffer. The argument buffer is used as both the input from the host and as the output of the contract. All functions exposed by the contract must follow the convention:

// A function compatible with the piecrust ABI takes in the number of bytes
// written by the host to the argument buffer and returns the number of
// bytes written by the contract.
uint32_t fname(uint32_t arg_len);

The contract also has some functions available to it, offered by the host through WASM imports. Examples of these functions include, but are not limited to:

• call to call another contract
• emit to emit events

The functions in this crate are wrappers around a particular way of calling the WASM imports. Take a look at the externs for a full view of what is available.

Examples

Some of the contracts used for testing purposes function as good examples. Take a look at the contracts/ directory.

Features

By default, this crate will include no features and build only the types and functions available when the ABI is not present. To write a contract one must use the abi feature:

• abi for writing contracts
• dlmalloc to using the builtin allocator
• debug for writing contracts with debug capabilities such as the debug! macro, and logging panics to stdout

Modules

• arg_bufabi

Macros

• debugdebug and abi
  Macro to format and send debug output to the host

Structs

• ArchivedEvent
  An archived Event
• ArgbufWriterabi
  A small struct that can fmt::Write to the argument buffer.
• ContractId
  ID to identify the wasm contracts after they have been deployed
• ContractIdResolver
  The resolver for an archived ContractId
• Event
  And event emitted by a contract.
• EventResolver
  The resolver for an archived Event

Enums

• ArchivedContractError
  An archived ContractError
• ContractError
  The error possibly returned on an inter-contract-call.
• ContractErrorResolver
  The resolver for an archived ContractError

Constants

• ARGBUF_LEN
  The size of the argument buffer in bytes
• CONTRACT_ID_BYTES
  The length of ContractId in bytes
• SCRATCH_BUF_BYTES
  How many bytes to use for scratch space when serializing

Functions

• callabi
  Calls a contract’s fn_name function with the given argument fn_arg. The contract will have 93% of the remaining gas available to spend.
• call_rawabi
  Calls the function with name fn_name of the given contract using fn_arg as argument.
• call_raw_with_limitabi
  Calls the function with name fn_name of the given contract using fn_arg as argument, allowing it to spend the given gas_limit.
• call_with_limitabi
  Calls a contract’s fn_name function with the given argument fn_arg, allowing it to spend the given gas_limit.
• callerabi
  Return the ID of the calling contract. The returned id will be uninitialized if there is no caller - meaning this is the first contract to be called.
• emitabi
  Emits an event with the given data.
• feedabi
  Feeds the host with data.
• hdebug^⚠debug and abi
• host_queryabi
  Execute some code that the host provides under the given name.
• limitabi
  Returns the gas limit with which the contact was called.
• meta_dataabi
  Returns data made available by the host under the given name. The type D must be correctly specified, otherwise undefined behavior will occur.
• ownerabi
  Return the given contract’s owner, if the contract exists.
• self_idabi
  Return the current contract’s id.
• self_ownerabi
  Returns the current contract’s owner.
• spentabi
  Returns the amount of gas the contact has spent.
• wrap_callabi
  Wrap a call with its respective (de)serializers.

Type Aliases

• StandardBufSerializer
  Type with rkyv serialization capabilities for specific types.