Skip to content

Development setup

To develop and compile contracts for the Partisia Platform, you need to install the following

  • Rust version 1.85.0
    • Build target wasm32-unknown-unknown
  • Java 17
  • Git
  • Cargo Partisia Contract

Install Rust

To install Rust for your platform follow the instructions on https://rustup.rs/.

Instruct rust to use the latest stable version by running:

rustup install stable
rustup default stable

The wasm32-unknown-unknown target needs to be added manually, you add the target by running:

rustup target add wasm32-unknown-unknown

If you are using a Windows machine you must get Visual Studio with C++ build tools - In Visual Studio Installer choose Desktop development with C++.

We recommend you make sure these optionals are enabled:

  • MSVC x64/x86 build tools
  • Windows 11 SDK
  • C++ CMake tools for Windows
  • Testing tools core features
  • Build Tools
  • C++ AddressSanitizer

Git

To compile contracts you will also need to install the version control system, Git. Rust uses Git to fetch dependencies from remote repositories.

Java

Install Java 17 by following the instructions here.

Installing the cargo partisia-contract/pbc command

The partisia-contract tool is a commandline tool that helps you compile a contract, view ABIs, chain state and the state of deployed smart contracts. To compile it and install it using cargo, run the following command:

cargo install cargo-partisia-contract

The cargo partisia-contract and cargo pbc are interchangeable commands, cargo pbc is just an alias. To verify the tool you can locally execute:

cargo partisia-contract --version

and

cargo pbc --version

Smart contract tools overview

This section provides an overview of the tools designed to help developers working with smart contracts on the blockchain. These tools offer a range of capabilities, from testing smart contracts to facilitating command-line interactions with the blockchain, and even integrating the blockchain with your own applications.

Partisia Platform browser

Partisia platform browser is a web-based interface which translates the private blockchains data into a user-friendly application. Partisia Platform browser is essentially a complete UI for a private deployment.

Partisia Platform browser can be used to:

  • Display details for the entire ledger: blocks and transactions.
  • Interact with any smart contract.
  • Deploy your own new smart contracts.
  • Create local references of contracts and accounts to help you keep track of already deployed contracts.

Command-line tools

cargo pbc is an umbrella for multiple sub-tools. The tools assist you in interacting with the blockchain and working with smart contracts. These tools are thoroughly documented when using them within cargo pbc, enabling you to explore their capabilities inside cargo pbc. Below are a short description and use case for each of these sub-tools.

Pre requisite to use any cargo pbc commands

If you want to use any of the command-line tools or below commands you need to install the smart contract compiler "cargo pbc".

To use the Partisia CLI tool with a local deployment you must first configure it to target your chain. This can be done by running the following command

cargo pbc config net local "http://localhost:9432,http://localhost:8300" --default

Where

  • http://localhost:9432 is the url of the reader endpoint
  • http://localhost:8300 is the url of the browser

Any following command will now target the deployment

The Compiler build

This is a primary part of developings smart contracts. The build command compiles rust smart contracts and ZK Rust smart contracts. It compiles and returns .abi file and a .wasm for rust contracts or .zkwa for ZK rust contracts.

Blockchain interaction

To interact with the blockchain you can use the command line tool: cargo pbc. There are 3 main commands:

  • transaction
  • account
  • contract

It can help you specifically with:

  • Sending transactions to smart contracts
  • Deploying your own smart contracts
  • Showing smart contracts state
  • Sending secret inputs and viewing secret variables

The ABI tool abi

This tool is focused on helping you understand the ABI, actions and state of a contract. By using the command cargo pbc abi show, you can view information about a compiled contract's state type, initialization, actions, and variables. It simplifies the process of identifying shortnames for existing contracts using optional arguments. This tool is using the abi-client.

Example command:

cargo pbc abi show example-contracts/target/wasm32-unknown-unknown/release/auction_contract.pbc
Response from example command 
pub struct Bid {
bidder: Address,
amount: u128,
}
pub struct SecretVarId {
raw_id: u32,
}
pub struct TokenClaim {
tokens_for_bidding: u128,
tokens_for_sale: u128,
}
#[state]
pub struct AuctionContractState {
contract_owner: Address,
start_time_millis: i64,
end_time_millis: i64,
token_amount_for_sale: u128,
token_for_sale: Address,
token_for_bidding: Address,
highest_bidder: Bid,
reserve_price: u128,
min_increment: u128,
claim_map: Map<Address, TokenClaim>,
status: u8,
}
#[init]
pub fn initialize (
token_amount_for_sale: u128,
token_for_sale: Address,
token_for_bidding: Address,
reserve_price: u128,
min_increment: u128,
auction_duration_hours: u32,
)
#[action(shortname = 0x01)]
pub fn start ()
#[action(shortname = 0x03)]
pub fn bid (
bid_amount: u128,
)
#[action(shortname = 0x05)]
pub fn claim ()
#[action(shortname = 0x06)]
pub fn execute ()
#[action(shortname = 0x07)]
pub fn cancel ()
#[callback(shortname = 0x02)]
pub fn start_callback ()
#[callback(shortname = 0x04)]
pub fn bid_callback (
bid: Bid,
)

The ABI codegen tool abi codegen

Codegen produces autogenerated code in both Java & TypeScript to streamline interactions with contract actions and deserializing contracts states. The autogenerated code provides methods to interact with actions based on a smart contracts abi. If you are working with Java, we recommend you follow the readme here to automate your usage of abi codegen.

Abi codegen can also be used manually. Here is an example of how:

cargo pbc abi codegen --ts mySmartContract/target/wasm32-unknown-unknown/release/auction_contract.pbc mySmartContract/AutogeneratedCode/auction_contract.ts
Response from example command 
/* eslint-disable @typescript-eslint/no-unused-vars */
/* eslint-disable @typescript-eslint/no-non-null-assertion */
import BN from "bn.js";
import {
AbiParser,
AbstractBuilder, BigEndianReader,
FileAbi, FnKinds, FnRpcBuilder, RpcReader,
ScValue,
ScValueEnum, ScValueOption,
ScValueStruct,
StateReader, TypeIndex,
BlockchainAddress,
Hash,
BlockchainPublicKey,
Signature,
BlsPublicKey,
BlsSignature
} from "@privacyblockchain/ts-abi";
import {BigEndianByteOutput} from "@secata-public/bitmanipulation-ts";

const fileAbi: FileAbi = new AbiParser(Buffer.from(
"50424341424909040005020000000004010000000342696400000002000000066269646465720d00000006616d6f756e7405010000000a546f6b656e436c61696d0000000200000012746f6b656e735f666f725f62696464696e67050000000f746f6b656e735f666f725f73616c6505010000001441756374696f6e436f6e747261637453746174650000000b0000000e636f6e74726163745f6f776e65720d0000001173746172745f74696d655f6d696c6c6973090000000f656e645f74696d655f6d696c6c69730900000015746f6b656e5f616d6f756e745f666f725f73616c65050000000e746f6b656e5f666f725f73616c650d00000011746f6b656e5f666f725f62696464696e670d0000000e686967686573745f62696464657200000000000d726573657276655f7072696365050000000d6d696e5f696e6372656d656e740500000009636c61696d5f6d61700f0d00010000000673746174757301010000000b536563726574566172496400000001000000067261775f69640300000008010000000a696e697469616c697a65ffffffff0f0000000600000015746f6b656e5f616d6f756e745f666f725f73616c65050000000e746f6b656e5f666f725f73616c650d00000011746f6b656e5f666f725f62696464696e670d0000000d726573657276655f7072696365050000000d6d696e5f696e6372656d656e74050000001661756374696f6e5f6475726174696f6e5f686f75727303020000000573746172740100000000030000000e73746172745f63616c6c6261636b0200000000020000000362696403000000010000000a6269645f616d6f756e7405030000000c6269645f63616c6c6261636b04000000010000000362696400000200000005636c61696d05000000000200000007657865637574650600000000020000000663616e63656c07000000000002",
"hex"
)).parseAbi();

type Option<K> = K | undefined;

export interface Bid {
bidder: BlockchainAddress;
amount: BN;
}

export function newBid(bidder: BlockchainAddress, amount: BN): Bid {
return {bidder, amount}
}

function fromScValueBid(structValue: ScValueStruct): Bid {
return {
bidder: BlockchainAddress.fromBuffer(structValue.getFieldValue("bidder")!.addressValue().value),
amount: structValue.getFieldValue("amount")!.asBN(),
};
}

function buildRpcBid(value: Bid, builder: AbstractBuilder) {
const structBuilder = builder.addStruct();
structBuilder.addAddress(value.bidder.asBuffer());
structBuilder.addU128(value.amount);
}

export interface TokenClaim {
tokensForBidding: BN;
tokensForSale: BN;
}

export function newTokenClaim(tokensForBidding: BN, tokensForSale: BN): TokenClaim {
return {tokensForBidding, tokensForSale}
}

function fromScValueTokenClaim(structValue: ScValueStruct): TokenClaim {
return {
tokensForBidding: structValue.getFieldValue("tokens_for_bidding")!.asBN(),
tokensForSale: structValue.getFieldValue("tokens_for_sale")!.asBN(),
};
}

export interface AuctionContractState {
contractOwner: BlockchainAddress;
startTimeMillis: BN;
endTimeMillis: BN;
tokenAmountForSale: BN;
tokenForSale: BlockchainAddress;
tokenForBidding: BlockchainAddress;
highestBidder: Bid;
reservePrice: BN;
minIncrement: BN;
claimMap: Map<BlockchainAddress, TokenClaim>;
status: number;
}

export function newAuctionContractState(contractOwner: BlockchainAddress, startTimeMillis: BN, endTimeMillis: BN, tokenAmountForSale: BN, tokenForSale: BlockchainAddress, tokenForBidding: BlockchainAddress, highestBidder: Bid, reservePrice: BN, minIncrement: BN, claimMap: Map<BlockchainAddress, TokenClaim>, status: number): AuctionContractState {
return {contractOwner, startTimeMillis, endTimeMillis, tokenAmountForSale, tokenForSale, tokenForBidding, highestBidder, reservePrice, minIncrement, claimMap, status}
}

function fromScValueAuctionContractState(structValue: ScValueStruct): AuctionContractState {
return {
contractOwner: BlockchainAddress.fromBuffer(structValue.getFieldValue("contract_owner")!.addressValue().value),
startTimeMillis: structValue.getFieldValue("start_time_millis")!.asBN(),
endTimeMillis: structValue.getFieldValue("end_time_millis")!.asBN(),
tokenAmountForSale: structValue.getFieldValue("token_amount_for_sale")!.asBN(),
tokenForSale: BlockchainAddress.fromBuffer(structValue.getFieldValue("token_for_sale")!.addressValue().value),
tokenForBidding: BlockchainAddress.fromBuffer(structValue.getFieldValue("token_for_bidding")!.addressValue().value),
highestBidder: fromScValueBid(structValue.getFieldValue("highest_bidder")!.structValue()),
reservePrice: structValue.getFieldValue("reserve_price")!.asBN(),
minIncrement: structValue.getFieldValue("min_increment")!.asBN(),
claimMap: new Map([...structValue.getFieldValue("claim_map")!.mapValue().map].map(([k1, v2]) => [BlockchainAddress.fromBuffer(k1.addressValue().value), fromScValueTokenClaim(v2.structValue())])),
status: structValue.getFieldValue("status")!.asNumber(),
};
}

export function deserializeAuctionContractState(bytes: Buffer): AuctionContractState {
const scValue = new StateReader(bytes, fileAbi.contract).readState();
return fromScValueAuctionContractState(scValue);
}

export interface SecretVarId {
rawId: number;
}

export function newSecretVarId(rawId: number): SecretVarId {
return {rawId}
}

function fromScValueSecretVarId(structValue: ScValueStruct): SecretVarId {
return {
rawId: structValue.getFieldValue("raw_id")!.asNumber(),
};
}

export function initialize(tokenAmountForSale: BN, tokenForSale: BlockchainAddress, tokenForBidding: BlockchainAddress, reservePrice: BN, minIncrement: BN, auctionDurationHours: number): Buffer {
const fnBuilder = new FnRpcBuilder("initialize", fileAbi.contract);
fnBuilder.addU128(tokenAmountForSale);
fnBuilder.addAddress(tokenForSale.asBuffer());
fnBuilder.addAddress(tokenForBidding.asBuffer());
fnBuilder.addU128(reservePrice);
fnBuilder.addU128(minIncrement);
fnBuilder.addU32(auctionDurationHours);
return fnBuilder.getBytes();
}

export function start(): Buffer {
const fnBuilder = new FnRpcBuilder("start", fileAbi.contract);
return fnBuilder.getBytes();
}

export function bid(bidAmount: BN): Buffer {
const fnBuilder = new FnRpcBuilder("bid", fileAbi.contract);
fnBuilder.addU128(bidAmount);
return fnBuilder.getBytes();
}

export function claim(): Buffer {
const fnBuilder = new FnRpcBuilder("claim", fileAbi.contract);
return fnBuilder.getBytes();
}

export function execute(): Buffer {
const fnBuilder = new FnRpcBuilder("execute", fileAbi.contract);
return fnBuilder.getBytes();
}

export function cancel(): Buffer {
const fnBuilder = new FnRpcBuilder("cancel", fileAbi.contract);
return fnBuilder.getBytes();
}