Developing with Rust
Velas supports writing on-chain programs using the Rust programming language.
Velas Rust programs follow the typical Rust project layout:
But must also include:
Which must contain:
Velas Rust programs may depend directly on each other in order to gain access to instruction helpers when making cross-program invocations. When doing so it's important to not pull in the dependent program's entrypoint symbols because they may conflict with the program's own. To avoid this, programs should define an
exclude_entrypoint feature in
Cargo.toml and use to exclude the entrypoint.
Then when other programs include this program as a dependency, they should do so using the
At a minimum, Velas Rust programs must pull in the solana-program crate.
Velas BPF programs have some restrictions that may prevent the inclusion of some crates as dependencies or require special handling.
- Crates that require the architecture be a subset of the ones supported by the official toolchain. There is no workaround for this unless that crate is forked and BPF added to that those architecture checks.
- Crates may depend on
randwhich is not supported in Velas' deterministic program environment. To include a
randdependent crate refer to Depending on Rand.
- Crates may overflow the stack even if the stack overflowing code isn't included in the program itself. For more information refer to Stack.
How to Build
First setup the environment:
- Install the latest Rust stable from https://rustup.rs/
- Install the latest Velas command-line tools from https://docs.velas.com/cli/install-velas-cli-tools
The normal cargo build is available for building programs against your host machine which can be used for unit testing:
To build a specific program, such as SPL Token, for the Velas BPF target which can be deployed to the cluster:
How to Test
Velas programs can be unit tested via the traditional
cargo test mechanism by exercising program functions directly.
To help facilitate testing in an environment that more closely matches a live cluster, developers can use the
program-test crate. The
program-test crate starts up a local instance of the runtime and allows tests to send multiple transactions while keeping state for the duration of the test.
For more information the test in sysvar example shows how an instruction containing syavar account is sent and processed by the program.
Programs export a known entrypoint symbol which the Velas runtime looks up and calls when invoking a program. Velas supports multiple versions of the BPF loader and the entrypoints may vary between them. Programs must be written for and deployed to the same loader. For more details see the [overview].
Currently there are two supported loaders BPF Loader and BPF loader deprecated.
They both have the same raw entrypoint definition, the following is the raw symbol that the runtime looks up and calls:
This entrypoint takes a generic byte array which contains the serialized program parameters (program id, accounts, instruction data, etc...). To deserialize the parameters each loader contains its own wrapper macro that exports the raw entrypoint, deserializes the parameters, calls a user defined instruction processing function, and returns the results.
You can find the entrypoint macros here:
The program defined instruction processing function that the entrypoint macros call must be of this form:
Refer to helloworld's use of the entrypoint as an example of how things fit together.
Each loader provides a helper function that deserializes the program's input parameters into Rust types. The entrypoint macros automatically calls the deserialization helper:
- BPF Loader deserialization
- BPF Loader deprecated deserialization Some programs may want to perform deserialization themselves and they can by providing their own implementation of the raw entrypoint. Take note that the provided deserialization functions retain references back to the serialized byte array for variables that the program is allowed to modify (lamports, account data). The reason for this is that upon return the loader will read those modifications so they may be committed. If a program implements their own deserialization function they need to ensure that any modifications the program wishes to commit be written back into the input byte array.
Details on how the loader serializes the program inputs can be found in the Input Parameter Serialization docs.
The loader's entrypoint macros call the program defined instruction processor function with the following parameters:
The program id is the public key of the currently executing program.
The accounts is an ordered slice of the accounts referenced by the instruction and represented as an AccountInfo structures. An account's place in the array signifies its meaning, for example, when transferring lamports an instruction may define the first account as the source and the second as the destination.
The members of the
AccountInfo structure are read-only except for
data. Both may be modified by the program in accordance with the runtime enforcement policy. Both of these members are protected by the Rust
RefCell construct, so they must be borrowed to read or write to them. The reason for this is they both point back to the original input byte array, but there may be multiple entries in the accounts slice that point to the same account. Using
RefCell ensures that the program does not accidentally perform overlapping read/writes to the same underlying data via multiple
AccountInfo structures. If a program implements their own deserialization function care should be taken to handle duplicate accounts appropriately.
The instruction data is the general purpose byte array from the instruction's instruction data being processed.
Rust programs implement the heap directly by defining a custom
Programs may implement their own
global_allocator based on its specific needs. Refer to the custom heap example for more information.
On-chain Rust programs support most of Rust's libstd, libcore, and liballoc, as well as many 3rd party crates.
There are some limitations since these programs run in a resource-constrained, single-threaded environment, and must be deterministic:
- No access to
- Limited access to:
- Bincode is extremely computationally expensive in both cycles and call depth and should be avoided
- String formatting should be avoided since it is also computationally expensive.
- No support for
print!, the Velas logging helpers should be used instead.
- The runtime enforces a limit on the number of instructions a program can execute during the processing of one instruction. See computation budget for more information.
Depending on Rand
Programs are constrained to run deterministically, so random numbers are not available. Sometimes a program may depend on a crate that depends itself on
rand even if the program does not use any of the random number functionality. If a program depends on
rand, the compilation will fail because there is no
get-random support for Velas. The error will typically look like this:
To work around this dependency issue, add the following dependency to the program's
println! macro is computationally expensive and not supported. Instead the helper macro
msg! is provided.
msg! has two forms:
Both forms output the results to the program logs. If a program so wishes they can emulate println! by using
The debugging section has more information about working with program logs the [Rust examples]developing-rust.md#examples) contains a logging example.
assert!, and internal panic results are printed to the program logs by default.
Custom Panic Handler
Programs can override the default panic handler by providing their own implementation.
First define the
custom-panic feature in the program's
Then provide a custom implementation of the panic handler:
In the above snippit, the default implementation is shown, but developers may replace that with something that better suits their needs.
One of the side effects of supporting full panic messages by default is that programs incur the cost of pulling in more of Rust's
libstd implementation into program's shared object. Typical programs will already be pulling in a fair amount of
libstd and may not notice much of an increase in the shared object size. But programs that explicitly attempt to be very small by avoiding
libstd may take a significant impact (~25kb). To eliminate that impact, programs can provide their own custom panic handler with an empty implementation.
Use the system call
sol_log_compute_units() to log a message containing the remaining number of compute units the program may consume before execution is halted
See compute budget for more information.
The BPF shared object internals can be dumped to a text file to gain more insight into a program's composition and what it may be doing at runtime. The dump will contain both the ELF information as well as a list of all the symbols and the instructions that implement them. Some of the BPF loader's error log messages will reference specific instruction numbers where the error occurred. These references can be looked up in the ELF dump to identify the offending instruction and its context.
To create a dump file:
Examples# The Velas Program Library github repo contains a collection of Rust examples.