Crate piecrust_uplink

Expand description

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_buf

Macros§

debug: 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§

call: 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_raw: Calls the function with name fn_name of the given contract using fn_arg as argument.
call_raw_with_limit: 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_limit: Calls a contract’s fn_name function with the given argument fn_arg, allowing it to spend the given gas_limit.
caller: Returns the ID of the calling contract, or None if this is the first contract to be called.
callstack: Returns IDs of all calling contracts present in the calling stack
emit: Emits an event with the given data, serializing it using rkyv.
emit_raw: Emits an event with the given data.
feed: Feeds the host with data, serializing it using rkyv.
feed_raw: Feeds the host with data.
hdebug^⚠
host_query: Execute some code that the host provides under the given name.
limit: Returns the gas limit with which the contact was called.
meta_data: Returns data made available by the host under the given name. The type D must be correctly specified, otherwise undefined behavior will occur.
owner: Return the given contract’s owner, if the contract exists.
self_id: Return the current contract’s id.
self_owner: Returns the current contract’s owner.
spent: Returns the amount of gas the contact has spent.
wrap_call: Wrap a call with its respective (de)serializers. Checks integrity of the arguments.
wrap_call_unchecked: Wrap a call with its respective (de)serializers. Does not check the integrity of arguments.

Type Aliases§

StandardBufSerializer: Type with rkyv serialization capabilities for specific types.