Phat Contract Tutorial

This tutorial will demonstrate how to use Phat Contract’s HTTP request capability to associate a Phala account with a Github user. Such functionality serves as the core for Decentralized Identity (DID). Further, we will show how to deploy your contract in Phala Testnet and interact with it through our frontend SDK.

Get Things Ready

To get your application running, you will need to download our frontend and backend demo code:

  • The backend code, a.k.a. the demo Phat Contract, is available in our Phat Contract Workshop Repository;
  • The frontend SDK (JS-SDK), which already contains the frontend to interact with contract above as an example.

After your contract is ready, you should upload it to some Contract Cluster in Phala Testnet and instantiate it.

  • Available Cluster: 0x0000000000000000000000000000000000000000000000000000000000000000

Your contract will be finally deployed to our off-chain Secure Workers. You will need two endpoints to config your frontend to interact with your contract:

  • A Phala node WebSocket endpoint to read the on-chain data and send Command: wss://poc5.phala.network/ws
  • Secure Worker endpoints to send Query to your deployed contract and get results, now we deploy one Secure Worker for our Testnet
    • Worker 0x94a2ded4c77fbb910943f7e452e4d243ee5b60bf1a838a911acf2ffd4bae9b63
      • Endpoint https://poc5.phala.network/tee-api-1

Note that the node endpoint is generally stable, while the available cluster and Secure Workers can change due to Testnet update. Report in the #dev channel of our Discord if they are down.

Environment Preparation

An operating system of macOS or Linux systems like Ubuntu 18.04/20.04 is recommended for the workshop.

  • For macOS users, we recommend to use the Homebrew package manager to install the dependencies
  • For other Linux distribution users, use the package manager with the system like Apt/Yum

The following toolchains are needed:

  • Rust toolchain
    • Install rustup, rustup is the “package manager” of different versions of Rust compilers: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
    • This will install rustup and cargo
  • Ink! Contract toolchain
    • Install binaryen with
      • Homebrew for macOS: brew install binaryen
      • Apt for Ubuntu: sudo apt install binaryen
      • or download the release and put it under your $PATH
    • Install dylint-link toolchain: cargo install cargo-dylint dylint-link
    • Install contract toolchain: cargo install cargo-contract --force
    • For macOS M1 chip users: rustup component add rust-src --toolchain nightly-aarch64-apple-darwin
  • Install frontend toolchain

Check your installation with

$ rustup toolchain list
# stable-x86_64-unknown-linux-gnu (default)
# nightly-x86_64-unknown-linux-gnu

$ cargo --version
# cargo 1.58.0 (f01b232bc 2022-01-19)

$ cargo contract --version
# cargo-contract 0.17.0-unknown-x86_64-linux-gnu

$ node --version
# v17.5.0

$ yarn --version
# 1.22.17

Create Polkadot Account to Use Phala Testnet

Our Testnet is launched in the dev mode, so there are some pre-defined development accounts with enough tokens for you to use.

Also you can install Polkadot.js extension and create/import the Phala gas account following the official tutorial

  • Connect to Phala Testnet
  • Send some coins to your own account (limited, don’t be evil);
    • Send some coins from the development accounts above .

Compile the Contract

In the fat-contract-workshop folder, run the following commands

cargo +nightly contract build

Also test to ensure everything is fine

cargo +nightly contract test

You will find the compile result at ./target/ink:

$ ls -h target/ink
# fat_sample.wasm  metadata.json ...

fat_sample.wasm contains the compiled contract code, and will be uploaded for execution; metadata.json contains the information of your contract, especially all the interfaces and their 4-byte selectors. You will use these selectors when interacting with the contract so it will know which function to call.

Deploy

Collect the above two files and create the contract in Phala Testnet (PoC 5). The contract deployment can be divided into two steps: code upload and contract instantiation.

We recommend to keep a tab for Explorer so you will not miss any historical events.

Code Upload

Choose Developer - Extrinsics, and select the extrinsic phalaFatContracts and uploadCodeToCluster.

  • Drag the fat_sample.wasm file;
  • Use the available Cluster mentioned above;

and send the transaction.

A event of phalaFatContracts.CodeUploaded should be observed in the block explorer with the code hash, record the code hash for future use.

Code upload could failed if there are illegal instructions in your compiled wasm. Report in the #dev channel of our Discord and we will help you find the reason.

Contract Instantiation

Choose Developer - Extrinsics, and select the extrinsic phalaFatContracts and instantiateContract. We explain the arguments as follow:

  • codeIndex: the code to use, choose WasmCode and type in the hash of you uploaded code
  • data: the instantiation argument. We shall call the constructor function of the contract will the specific function selector, This can be found in the metadata.json (in this case, 0xed4b9d1b)
...
    "constructors": [
    {
        "args": [],
        "docs": [],
        "label": "default",
        "payable": false,
        "selector": "0xed4b9d1b"
    }
],
...
  • salt: some random bytes to prevent collision, like 0x0 or 0x1234
  • clusterId: this must be the same as the one when you upload your code, since the code is stored in the cluster level

There are three events to observe, all these events contain your Contract ID

  • phalaFatContracts.Instantiating, the chain has receive your request and start instanting;
  • phalaFatContracts.ContractPubkeyAvailable, the gatekeeper has generated the contract key to encrypt its state and input/output;
  • phalaFatContracts.Instantiated, your contract is successfully instantiated.

You can go to Developer - Chain state and select the extrinsic phalaFatContracts and contracts to see all the contracts.

Handle Instantiation Failure

For now, the contract execution log is not directly available to the developers. Join our Discord and we can help forward the Worker logs if necessary.

Run the Frontend

Phala provides js-sdk to simplified the frontend development. It already contains the frontend for the demo contract, check its example folder.

Follow the steps to run the frontend

  1. Download Phala-Network/js-sdk

    git clone --branch ethdenver-2022 https://github.com/Phala-Network/js-sdk.git
    
  2. Compile and run the frontend. By default it will serve the app at http://localhost:3000:

    cd js-sdk
    
    yarn
    yarn dev
    

Play with Your Contract

Open the Frontend, by default it’s in http://localhost:3000

  1. Connect your wallet;
  2. Load the deployed contract;
    • Substrate endpoint: wss://poc5.phala.network/ws
    • Secure Worker endpoint: https://poc5.phala.network/tee-api-1
    • Contract ID: available during Contract Instantiation
    • ABI: copy from metadata.json (prebuilt copy)
  3. Click Sign a Certificate, this will generate a certificate to encrypt your traffic to/from the contract;
  4. Follow the instruction, copy the contents and create a public Github Gist with it;
  5. Open the RAW file, and copy the link;
  6. Paste the link to the box and click Verify;
  7. The redeem code box in will refresh every 5s. It should show your code once the verification is successful.

Attention

By default, the poap_code pool is empty, so the users can only get empty string even if they have passed the verification. The contract admin need to invoke the admin_set_poap_code() first to fill in the redeem code pool so the users can really get something.

Challenge: Fill in the Missing Code

We leave two challenges (labeled by TODO) for you to explore.

  • The first is about adding the necessary access control to the update redeem code function, you will learn about how to access the contract metadata through the self.env() function;
  • The second is about check to prevent a double redemption of the code.

Solution

Please check the ethdenver-2022-solution branch.

Appendix

Endpoints

  • Chain: wss://poc5.phala.network/ws
  • Workers (with their identity key)
    • https://poc5.phala.network/tee-api-1
      • 0x94a2ded4c77fbb910943f7e452e4d243ee5b60bf1a838a911acf2ffd4bae9b63
    • https://poc5.phala.network/tee-api-2
      • 0x50ede2dd7c65716a2d55bb945dfa28d951879154f832e049851d7882c288db76
    • https://poc5.phala.network/tee-api-3
      • 0xfe26077a6030e505136855100f335503ca40f6e8afa149b0c6c618e81c1cb53b
    • https://poc5.phala.network/tee-api-4
      • 0x6cfc1282880305c7691f0941b98089b9da17acde43b66ef2220022797bb3e370
    • https://poc5.phala.network/tee-api-5
      • 0xbed94c30d660a1de5a499e38f9f3afe9ccc1ef5f901530efd48de641679fbc7d

Edit this page on GitHub