Crate piecrust_uplink
source ·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:
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 contractsdlmalloc
to using the builtin allocatordebug
for writing contracts with debug capabilities such as thedebug!
macro, and logging panics to stdout
Modules§
- arg_buf
abi
Macros§
- debug
debug
andabi
Macro to format and send debug output to the host
Structs§
- An archived
Event
- ArgbufWriter
abi
A small struct that canfmt::Write
to the argument buffer. - ID to identify the wasm contracts after they have been deployed
- The resolver for an archived
ContractId
- And event emitted by a contract.
- The resolver for an archived
Event
Enums§
- An archived
ContractError
- The error possibly returned on an inter-contract-call.
- The resolver for an archived
ContractError
Constants§
- The size of the argument buffer in bytes
- The length of
ContractId
in bytes - How many bytes to use for scratch space when serializing
Functions§
- call
abi
Calls acontract
’sfn_name
function with the given argumentfn_arg
. The contract will have93%
of the remaining gas available to spend. - call_raw
abi
Calls the function with namefn_name
of the givencontract
usingfn_arg
as argument. - Calls the function with name
fn_name
of the givencontract
usingfn_arg
as argument, allowing it to spend the givengas_limit
. - Calls a
contract
’sfn_name
function with the given argumentfn_arg
, allowing it to spend the givengas_limit
. - caller
abi
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. - emit
abi
Emits an event with the given data. - feed
abi
Feeds the host with data. - hdebug⚠
debug
andabi
- host_query
abi
Execute some code that the host provides under the given name. - limit
abi
Returns the gas limit with which the contact was called. - meta_data
abi
Returns data made available by the host under the given name. The typeD
must be correctly specified, otherwise undefined behavior will occur. - owner
abi
Return the given contract’s owner, if the contract exists. - self_id
abi
Return the current contract’s id. - self_owner
abi
Returns the current contract’s owner. - spent
abi
Returns the amount of gas the contact has spent. - wrap_call
abi
Wrap a call with its respective (de)serializers. Checks integrity of the arguments. - Wrap a call with its respective (de)serializers. Does not check the integrity of arguments.
Type Aliases§
- Type with
rkyv
serialization capabilities for specific types.