Crate pop_contracts

Expand description

§pop-contracts

A crate for generating, building, deploying, and calling ink! Smart Contracts. Used by pop-cli.

§Usage

Generate a new Smart Contract:

use pop_contracts::{create_smart_contract, Contract};
use std::path::Path;

let contract_path = Path::new("./");
create_smart_contract("my_contract", &contract_path, &Contract::Standard);

Build an existing Smart Contract:

use pop_contracts::build_smart_contract;
use std::path::Path;
pub use contract_build::{Verbosity, MetadataSpec};

let contract_path = Path::new("./");
let build_release = true; // `true` for release mode, `false` for debug mode.
let result = build_smart_contract(&contract_path, build_release, Verbosity::Default, Some(MetadataSpec::Ink)); // You can build your contract with Solidity metadata using `Some(Metadata::Ink)`

Test an existing Smart Contract:

use pop_common::test_project;
use pop_contracts::test_e2e_smart_contract;
use std::path::Path;

let contract_path = Path::new("./");
let contracts_node_path = Path::new("./path-to-contracts-node-binary");

//unit testing
test_project(&contract_path, None);
//e2e testing
test_e2e_smart_contract(&contract_path, Some(contracts_node_path), None);

Deploy and instantiate an existing Smart Contract:

use pop_contracts::{ dry_run_gas_estimate_instantiate, instantiate_smart_contract, set_up_deployment, UpOpts};
use std::path::PathBuf;
use tokio_test;
use url::Url;

tokio_test::block_on(async {
    let contract_path = PathBuf::from("./");
    // prepare extrinsic for deployment
    let up_opts = UpOpts {
            path: contract_path,
            constructor: "new".to_string(),
            args: ["false".to_string()].to_vec(),
            value: "1000".to_string(),
            gas_limit: None,
            proof_size: None,
            url: Url::parse("ws://localhost:9944").unwrap(),
            suri: "//Alice".to_string(),
            salt: None,
    };
    let instantiate_exec = set_up_deployment(up_opts).await.unwrap();

    // If you don't know the `gas_limit` and `proof_size`, you can perform a dry run to estimate the gas amount before instatianting the Smart Contract.
    let weight = dry_run_gas_estimate_instantiate(&instantiate_exec).await.unwrap();

    let contract_address = instantiate_smart_contract(instantiate_exec, weight).await.unwrap();
});

Upload a Smart Contract only:

use pop_contracts::{ dry_run_upload, set_up_upload, upload_smart_contract, UpOpts};
use std::path::PathBuf;
use tokio_test;
use url::Url;

tokio_test::block_on(async {
    // prepare extrinsic for deployment
    let contract_path = PathBuf::from("./");
    let up_opts = UpOpts {
            path: contract_path,
            constructor: "new".to_string(),
            args: ["false".to_string()].to_vec(),
            value: "1000".to_string(),
            gas_limit: None,
            proof_size: None,
            url: Url::parse("ws://localhost:9944").unwrap(),
            suri: "//Alice".to_string(),
            salt: None,
    };
    let upload_exec = set_up_upload(up_opts).await.unwrap();
    // to perform only a dry-run
    let hash_code = dry_run_upload(&upload_exec).await.unwrap();
    // to upload the smart contract
    let code_hash = upload_smart_contract(&upload_exec).await.unwrap();
});

Call a deployed (and instantiated) Smart Contract:

use pop_contracts::{call_smart_contract, dry_run_call, dry_run_gas_estimate_call, set_up_call,CallOpts};
use std::path::PathBuf;
use tokio_test;
use url::Url;

tokio_test::block_on(async {
    // prepare extrinsic for call
    let contract_path = PathBuf::from("./");
    let get_call_opts = CallOpts {
        path: contract_path.clone(),
        contract: "5CLPm1CeUvJhZ8GCDZCR7nWZ2m3XXe4X5MtAQK69zEjut36A".to_string(),
        message: "get".to_string(),
        args: [].to_vec(),
        value: "1000".to_string(),
        gas_limit: None,
        proof_size: None,
        url: Url::parse("ws://localhost:9944").unwrap(),
        suri: "//Alice".to_string(),
        execute: false
    };
    let get_call_exec = set_up_call(get_call_opts).await.unwrap();
    // For operations that only require reading from the blockchain state, it does not require to submit an extrinsic.
    let call_dry_run_result = dry_run_call(&get_call_exec).await.unwrap();

    // For operations that change a storage value, thus altering the blockchain state, requires to submit an extrinsic.
    let flip_call_opts = CallOpts {
        path: contract_path,
        contract: "5CLPm1CeUvJhZ8GCDZCR7nWZ2m3XXe4X5MtAQK69zEjut36A".to_string(),
        message: "flip".to_string(),
        args: [].to_vec(),
        value: "1000".to_string(),
        gas_limit: None,
        proof_size: None,
        url: Url::parse("ws://localhost:9944").unwrap(),
        suri: "//Alice".to_string(),
        execute: true
    };
    let flip_call_exec = set_up_call(flip_call_opts).await.unwrap();
    let url = Url::parse("ws://localhost:9944").unwrap();
    // If you don't know the `gas_limit` and `proof_size`, you can perform a dry run to estimate the gas amount before calling the Smart Contract.
    let (_, weight_limit) = dry_run_gas_estimate_call(&flip_call_exec).await.unwrap();
    // Use this weight to execute the call.
    let call_result = call_smart_contract(flip_call_exec, weight_limit, &url).await.unwrap();
});

§Acknowledgements

pop-contracts would not be possible without the awesome crate: cargo-contract.

Structs§

AccountMapper: A helper struct for performing account mapping operations.
Bytes: Hex-serialized shim for Vec<u8>.
CallExec
CallOpts: Attributes for the call command.
ContractFunction: Describes a contract function.
ContractInfo: Type to represent information about a deployed smart contract.
ContractStorage: Describes a contract storage item.
ExtrinsicOpts: Arguments required for creating and sending an extrinsic to a Substrate node.
Param: Describes a parameter.
UpOpts: Attributes for the up command
UploadCode: A raw call to pallet-contracts’s upload_code.
Weight

Enums§

Contract: A smart contract template.
ContractCallable: Represents a callable entity within a smart contract, either a function or storage item.
DefaultEnvironment: The fundamental types of the default configuration.
Error: Represents the various errors that can occur in the crate.
FunctionType: Specifies the type of contract function, either a constructor or a message.
MetadataSpec: Specification to use for contract metadata.
Verbosity: Denotes if output should be printed to stdout.

Traits§

Environment: The environmental types usable by contracts defined with ink!.

Functions§

build_smart_contract: Build the smart contract located at the specified path in build_release mode.
call_smart_contract: Call a smart contract on the blockchain.
call_smart_contract_from_signed_payload: Executes a smart contract call using a signed payload.
create_smart_contract: Create a new smart contract.
dry_run_call: Simulate a smart contract call without modifying the state of the blockchain.
dry_run_gas_estimate_call: Estimate the gas required for a contract call without modifying the state of the blockchain.
dry_run_gas_estimate_instantiate: Estimate the gas required for instantiating a contract without modifying the state of the blockchain.
dry_run_upload: Performs a dry-run for uploading a contract without modifying the state of the blockchain.
eth_rpc_generator: Retrieves the latest release of the Ethereum RPC binary, resolves its version, and constructs a Binary::Source with the specified cache path.
extract_function: Extracts the information of a smart contract function (message or constructor) parsing the contract artifact.
fetch_contract_storage: Fetches and decodes a storage value from a deployed smart contract.
get_call_payload: Generates the payload for executing a smart contract call.
get_contract_code: Reads the contract code from contract file.
get_contract_storage_info: Extracts a list of smart contract storage items parsing the contract artifact.
get_instantiate_payload: Gets the encoded payload call data for a contract instantiation.
get_message: Extracts the information of a smart contract message parsing the contract artifact.
get_messages: Extracts a list of smart contract messages parsing the contract artifact.
get_upload_payload: Gets the encoded payload call data for contract upload (not instantiate).
ink_node_generator: Retrieves the latest release of the contracts node binary, resolves its version, and constructs a Binary::Source with the specified cache path.
instantiate_contract_signed: Submit a pre-signed payload for instantiating a contract.
instantiate_smart_contract: Instantiate a contract.
is_chain_alive: Checks if the specified node is alive and responsive.
is_supported: Determines whether the manifest at the supplied path is a supported smart contract project.
is_valid_contract_name: Determines whether the provided name is valid for a smart contract.
mock_build_process: Mocks the build process by generating contract artifacts in a specified temporary directory.
new_environment: Generates a smart contract test environment.
parse_hex_bytes: Parse hex encoded bytes.
run_eth_rpc_node: Runs the latest version of the eth_rpc in the background.
run_ink_node: Runs the latest version of the ink-node in the background.
set_up_call: Prepare the preprocessed data for a contract call.
set_up_deployment: Prepare InstantiateExec data to upload and instantiate a contract.
set_up_upload: Prepare UploadExec data to upload a contract.
submit_signed_payload: Submit a pre-signed payload.
test_e2e_smart_contract: Run e2e tests of a smart contract.
upload_contract_signed: Submit a pre-signed payload for uploading a contract.
upload_smart_contract: Upload a contract.

Crate pop_contracts

Crate pop_contracts Copy item path

§pop-contracts

§Usage

§Acknowledgements

Structs§

Enums§

Traits§

Functions§

Crate pop_contracts