Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
ink-wrapper
ink-wrapper
is a tool that generates type-safe code for calling a substrate smart contract based on the metadata
(.json
) file for that contract.
Installation
Install the tool from crates.io:
Note that this uses nightly-2023-04-19
. You will need to install the toolchain first. You may try with just +nightly
to use whatever nightly you already have installed, but this particular version should work. The crate will most likely compile on another toolchain, but generate broken code afterwards, see https://github.com/udoprog/genco/issues/39.
Usage
Note on compatibility.
The last release compatible with aleph_client
is version 0.6.0
. Note though that it's compatible with aleph-client
in version 3.0.0
as this is the last version available in crates.io. We do not guarantee it will work with Testnet or Mainnet since their runtimes may differ in ways that are not compatible with aleph_client 3.0.0
.
Current release focuses on compatibility with drink.
Future releases will try to address the support for live chains.
Setup
Given some metadata file like my_contract.json
run the tool and save the output to a file in your project:
We only take minimal steps to format the output of the tool, so we recommend that you run it through a formatter when (re)generating:
|
The output should compile with no warnings, please create an issue if any warnings pop up in your project in the generated code.
Make sure the file you generated is included in your module structure:
DRink!
Add the following to your `Cargo.toml:
[]
= "0.8.6"
= "4.3.0"
= { = "0.7.0", = false, = [ "drink" ] }
= { = "parity-scale-codec", = "3", = false, = [ "derive" ] }
After generating the wrappers, the my_contract
will contain Instance
struct which represents the contract's state.
The easiest way to write a test is to use drink's unit test macro which will set up the drink::session::Sessin<MinimalRuntime>
object:
// Auto-generated wrappers need to be added to the crate.
// Minimal imports
use ;
use ;
For more comprehensive examples on actual contract wrappers, see tests
directory.
aleph_client
(deprecated from 0.7.0
)
You will need the following dependencies for the wrapper to work:
= "0.6.0"
= { = "parity-scale-codec", = "3", = false, = ["derive"] }
= "4.2.1"
# You only need this one if you have messages of the form `Trait::message`, like the ones generated by openbrush, for
# example.
= "0.1.68"
# This one is optional, but you most likely need it as well if you're using the default `aleph_client` implementation
# for actually making calls. Otherwise, you will need to implement `ink_wrapper_types::Connection` and
# `ink_wrapper_types::SignedConnection` yourself.
= "3.0.0"
Basic usage
With that, you're ready to use the wrappers in your code. The generated module will have an Instance
struct that
represents an instance of your contract. You can either talk to an existing instance by converting an account_id
to
an Instance
:
let account_id: AccountId = ...;
let instance: Instance = account_id.into;
Or (assuming the contract code has already been uploaded) create an instance using one of the generated constructors:
let instance = conn.instantiate.await?;
And then call methods on your contract:
let result = conn.read.await?;
let tx_info = conn.exec.await?;
Note that any methods that have names like Trait::method_name
will be grouped into traits in the generated module. You
might encounter this if you're using openbrush, for example their PSP22
implementation generates method names like
PSP22::balance_of
. You need to use
the generated traits to access these:
use PSP22 as _;
conn.read.await?
In the examples above, conn
is anything that implements ink_wrapper_types::Connection
(and
ink_wrapper_types::SignedConnection
if you want to use constructors or mutators). Default implementations are provided
for the connection in aleph_client
.
Events
ink_wrapper_types::Connection
also allows you to fetch events for a given TxInfo
:
use Connection as _;
let tx_info = conn.exec.await?;
let all_events = conn.get_contract_events.await?;
let contract_events = all_events.for_contract;
let sub_contract_events = all_events.for_contract;
The all_events
object above may contain events from multiple contracts if the contract called into them. In that case,
you can filter and parse these events by calling for_contract
on it, with the various contracts you're interested in.
Code upload
If you provide a compile-time path to the compiled WASM
:
you will also be able to use the generated wrapper to upload the contract:
conn.upload.await
Note, that the upload
function will return Ok(TxInfo)
so long as the transaction was submitted successfully and the
code hash of the metadata matches the uploaded code. If the code already existed on the chain, no error is returned. You
can verify this condition yourself by looking at the events at the returned TxInfo
and checking if they contain a
CodeStored
event.
Example
Look at tests
in the project's repo for a fuller example. Note that tests/drink
is missing the actual
wrappers, which are normally generated when testing. The easiest way to regenerate them is by running
make all-dockerized
(requires docker) - see Development for more on that.
Development
Use the commands provided in the Makefile
to replicate the build process run on CI:
The most hassle-free is to just run everything in docker:
If you have the tooling installed on your host and start a node yourself, you can also run the build on your host:
In case there are any runaway containers from all-dockerized
you can kill them: