Skip to main content
Version: 0.5.0

Casper

The Casper backend allows you to compile your contracts into WASM files which can be deployed onto Casper Blockchain and lets you to easily run them against Casper's Execution Engine locally.

Types​

A struct to be written into the storage must implement OdraType which is defined as follow:

pub trait OdraType: 
    casper_types::CLTyped + 
    casper_types::bytesrepr::ToBytes + 
    casper_types::bytesrepr::FromBytes {}

The other exposed types are:

Contract Env​

As with any other backend, Casper Backend must implement the same features, but some do not have native support. Let's take a closer look at how Odra overcomes these hindrances.

Events​

An event is not a first-class citizen in Casper like in Ethereum, so Odra mimics it. As you've already learned from the events article, in Odra you emit an event, similarly, you would do it in Solidity.

Under the hood, Odra integrates with Casper Event Standard and creates a few URefs in the global state when a contract is being installed:

  1. __events - a dictionary that stores events' data.
  2. __events_length - the evens count.
  3. __events_ces_version - the version of Casper Event Standard.
  4. __events_schema - a dictionary that stores event schemas.

Besides that, all the events the contract emits are registered - events schemas are written to the storage under the __events_schema key.

note

Don't forget to expose events in the module using #[odra::module(events = [...])].

So, Events are nothing different from any other data stored by a contract.

A struct to be an event must implement SerializableEvent which is defined as follow:

pub trait SerializableEvent: 
    odra_types::event::OdraEvent + 
    casper_types::CLTyped + 
    casper_types::bytesrepr::ToBytes + 
    casper_types::bytesrepr::FromBytes {}

Payable​

The first Odra idiom is a Contract Main Purse. It is a purse associated with a contract. The purse is created lazily - when the first transfer to the contract occurs, a proper URef and a purse are created and stored under the __contract_main_purse key.

Casper does not allow direct transfers from an account to a contract, so Odra comes up with the second idiom - a Cargo Purse. It is a one-time-use purse proxy between an account and a contract. First, motes go from the account to the cargo purse and then to the contract's main purse.

Behind the scenes, Odra handles an account-contract transfer via a cargo purse when a function is marked as payable. If under the way something goes wrong with the transfer, the contract reverts.

The transferred amount can be read inside the contract by calling contract_env::attached_value().

note

Odra expects the cargo_purse runtime argument to be attached to a contract call. In case of its absence, the contract_env::attached_value() returns zero.

Revert​

In Casper, we can stop the execution pretty straightforwardly - call the runtime::revert(). Odra adds an extra abstraction layer - in a contract ExecutionErrors are defined, which ultimately are transformed into Casper's ApiError::User.

Context​

Casper equips developers with very low-level tooling, which can be cumbersome for newcomers. If you want to check who called the contract or its address, you can not do it off-hand - you must analyze the call stack.

The contract_env::self_address() function takes the first element of the callstack (runtime::get_call_stack()) and casts it to Address.

The contract_env::caller() function takes the second element of the call stack (runtime::get_call_stack()) and casts it to Address.

As mentioned in the [Payable] section, to store CSPR, each contract creates its purse. To read the contract balance, you call contract_env::self_balance, which checks the balance of the purse stored under __contract_main_purse.

Test Env​

Test environment allows you to test wasm contracts before you deploy them onto the testnet or livenet. It is built on top of the Casper Execution Engine.

In your test, you can freely switch execution context by setting as a caller (test_env::set_caller()) one of the 20 predefined accounts. Each account possesses the default amount of Motes (100_000_000_000_000_000).

The Test Env internally keeps track of the current block time, error and attached value.

Each test is executed on a fresh instance of the Test Env.

Usage​

Name of the Casper backend in Odra is casper, so to run the tests against it, simply pass it as a -b parameter:

cargo odra test -b casper

If you want to just generate a wasm file, simply run:

cargo odra build -b casper

Constructors​

Let's define a basic Odra module that includes a constructor:

#[odra::module]
struct Counter {
    value: Variable<u32>
}

#[odra::module]
impl Counter {
    #[odra(init)]
    pub initialize(&mut self, value: u32) {
        self.value.set(value);
    }
}

Read more about constructors here.

WASM arguments​

When deploying a new contract you have to specify following arguments.

Required arguments:

  • odra_cfg_package_hash_key_name - String type. The key under which the package hash of the contract will be stored.
  • odra_cfg_allow_key_override - Bool type. If true and the key specified in odra_cfg_package_hash_key_name already exists, it will be overwritten.
  • odra_cfg_is_upgradable - Bool type. If true, the contract will be deployed as upgradable.

Optional arguments:

  • odra_cfg_constructor - String type. If the contract has the constructor entry point marked with #[odra(init)], this should be set to the constructor name.
  • constructor arguments that match entry point set in odra_cfg_constructor.

Contract Deploys​

Example: Deploy Counter​

To deploy your contract with a constructor using casper-client, you need to pass the above arguments. Additionally, you need to pass the value argument, which sets the arbitrary initial value for the counter.

casper-client put-deploy \
  --node-address [NODE_ADDRESS] \
  --chain-name casper-test \
  --secret-key [PATH_TO_YOUR_KEY]/secret_key.pem \
  --payment-amount 5000000000000 \
  --session-path ./wasm/counter.wasm \
  --session-arg "odra_cfg_package_hash_key_name:string:'counter_package_hash'" \
  --session-arg "odra_cfg_allow_key_override:bool:'true'" \
  --session-arg "odra_cfg_is_upgradable:bool:'true'" \
  --session-arg "odra_cfg_constructor:string:'initialize'" \
  --session-arg "value:u32:42"

For a more in-depth tutorial, please refer to the Casper's 'Writing On-Chain Code'.

Example: Deploy ERC721​

Odra comes with a standard ERC721 token implementation. Clone the main Odra repo and navigate to the modules directory.

Firstly contract needs to be compiled.

cargo odra build -b casper -c erc721_token

It produces the erc721_token.wasm file in the wasm directory.

Now it's time to deploy the contract.

casper-client put-deploy \
  --node-address [NODE_ADDRESS] \
  --chain-name casper-test \
  --secret-key [PATH_TO_YOUR_KEY]/secret_key.pem \
  --payment-amount 300000000000 \
  --session-path ./wasm/erc721_token.wasm \
  --session-arg "odra_cfg_package_hash_key_name:string:'my_nft'" \
  --session-arg "odra_cfg_allow_key_override:bool:'false'" \
  --session-arg "odra_cfg_is_upgradable:bool:'true'" \
  --session-arg "odra_cfg_constructor:string:'init'" \
  --session-arg "name:string:'MyNFT'" \
  --session-arg "symbol:string:'NFT'" \
  --session-arg "base_uri:string:'https://example.com/'"

It's done. The contract is deployed and ready to use. Your account is the owner of the contract and you can mint and burn tokens. For more details see the code of the ERC721 module.

To obtain the package hash of the contract search for my_nft key in your account's named keys.

Example: Deploy ERC1155​

The process is similar to the one described in the previous section.

Contract compilation:

cargo odra build -b casper -c erc1155_token

Contract deployment:

casper-client put-deploy \
  --node-address [NODE_ADDRESS] \
  --chain-name casper-test \
  --secret-key [PATH_TO_YOUR_KEY]/secret_key.pem \
  --payment-amount 300000000000 \
  --session-path ./wasm/erc1155_token.wasm \
  --session-arg "odra_cfg_package_hash_key_name:string:'my_tokens'" \
  --session-arg "odra_cfg_allow_key_override:bool:'false'" \
  --session-arg "odra_cfg_is_upgradable:bool:'true'" \
  --session-arg "odra_cfg_constructor:string:'init'" \

As previously, your account is the owner and can mint and burn tokens. For more details see the code of the ERC1155 module.

Sending CSPR to a contract​

Defining payable entry points is described in Native Token section.

What is happening under the hood is that Odra creates a new cargo_purse argument for each payable entry point. The cargo_purse needs to be top-upped with CSPR before calling the contract. When a contract adds CSPR to another contract call, Odra handles it for you. The problem arises when you want to call an entry point and attach CSPR as an account. The only way of doing that is by executing code in the sessions context, that top-ups the cargo_purse and then calls the contract.

Odra provides a generic proxy_caller.wasm that does exactly that. You can build it by yourself from the main Odra repository, or use the proxy_caller.wasm we maintain.

Using proxy_caller.wasm​

To use the proxy_caller.wasm you need to attach the following arguments:

  • contract_package_hash - BytesArray(32) type. The package hash of the contract you want to call. Result of to_bytes on CasperPackageHash.
  • entry_point - String type. The name of the entry point you want to call.
  • args - Bytes type. It is a serialized RuntimeArgs with the arguments you want to pass to the entry point. To be specific it is the result of to_bytes method wrapped with Bytes type.
  • attached_value. Option<U512> type. The amount of CSPR you want to attach to the call.
  • amount. U512 type. Should be the same value as attached_value if not None. It is a special Casper argument that enables the access to account's main purse.

Currently casper-client doesn't allow building such arguments. You have to build it using your SDK.

Execution​

First thing Odra does with your code, is similar to the one used in MockVM - a list of entrypoints is generated, thanks to the #[odra::module] macro.