Home Guides Product References Compute Providers

🏗️Customizing Your Phat Contract

For detailed docs on phat_js , go here for the latest.

What Can You Do With Your Phat Contract?

In the README.md link, you learned how to generate a new default function template and execute the 3 separate ways to test and validate your the results of the function. Now we will dive into what you can do with your function to extend the capabilities.

What you will learn:

  • Available Capabilities of @phala/pink-env

    • Call into a contract (Phat Contract).

    • Invoke a delegate call on a contract code by a code hash (Phat Contract).

    • Send an HTTP request and returns the response as either a Uint8Array or a string.

      • Single HTTP request

      • Batch HTTP requests

      • Error Handling

    • Derive a secret key from a salt.

    • Hash a message using the specified algorithm.

      • blake2b128

      • blake2b256

      • sha256

      • keccak256

  • Customize Your Default Function and Test Locally.

  • Handle the abi encoding/decoding with viem.

Getting Started

First you will need to install the @phala/fn CLI tool using your node package manager (npm) or use node package execute (npx). In this tutorial we use npx.

Now create your first template with the CLI tool command:

npx @phala/fn init example

We currently have only one template. Just press enter to see something similar to the example below:

npx @phala/fn init example
# ? Please select one of the templates for your "example" project: phala-oracle-consumer-contract. Polygon Consumer Contract for LensAPI Oracle
# Downloading the template: https://github.com/Phala-Network/phala-oracle-consumer-contract... ✔
# The project is created in ~/Projects/Phala/example

cd into the newly created template and ls the directory which will look similar to below.

cd example
ls                                                                                                                      ~/Projects/Phala/example
# total 736
# drwxr-xr-x  18 hashwarlock  staff   576B Sep  6 15:32 .
# drwxr-xr-x  35 hashwarlock  staff   1.1K Sep  6 15:32 ..
# -rw-r--r--   1 hashwarlock  staff   2.1K Sep  6 15:32 .env.local
# -rw-r--r--   1 hashwarlock  staff   227B Sep  6 15:32 .gitignore
# -rw-r--r--   1 hashwarlock  staff    34K Sep  6 15:32 LICENSE
# -rw-r--r--   1 hashwarlock  staff   8.9K Sep  6 15:32 README.md
# drwxr-xr-x   5 hashwarlock  staff   160B Sep  6 15:32 abis
# drwxr-xr-x   4 hashwarlock  staff   128B Sep  6 15:32 assets
# drwxr-xr-x   5 hashwarlock  staff   160B Sep  6 15:32 contracts
# -rw-r--r--   1 hashwarlock  staff   1.3K Sep  6 15:32 hardhat.config.ts
# -rw-r--r--   1 hashwarlock  staff    95B Sep  6 15:32 mumbai.arguments.ts
# -rw-r--r--   1 hashwarlock  staff   2.6K Sep  6 15:32 package.json
# -rw-r--r--   1 hashwarlock  staff    96B Sep  6 15:32 polygon.arguments.ts
# drwxr-xr-x   5 hashwarlock  staff   160B Sep  6 15:32 scripts
# drwxr-xr-x   3 hashwarlock  staff    96B Sep  6 15:32 src
# drwxr-xr-x   3 hashwarlock  staff    96B Sep  6 15:32 test
# -rw-r--r--   1 hashwarlock  staff   201B Sep  6 15:32 tsconfig.json
# -rw-r--r--   1 hashwarlock  staff   290K Sep  6 15:32 package-lock.json

Lastly, we will cd into ./src where the index.ts file resides. This file will be where we customize our function logic.

cd src

Available Capabilities of @phala/pink-env

In the GETTING_STARTED.md we introduced the basic functionality of making a single HTTP request to Lens API. The example code can be seen below:

function fetchApiStats(lensApi: string, profileId: string): any {
  // profile_id should be like 0x0001
  let headers = {
    "Content-Type": "application/json",
    "User-Agent": "phat-contract",
  };
  let query = JSON.stringify({
    query: `query Profile {
      profile(request: { forProfileId: "0x01" }) {
        stats {
            followers
            following
            comments
            countOpenActions
            posts
            quotes
            mirrors
            publications
            reacted
            reactions
        }
      }
    }`,
  });
  let body = stringToHex(query);
  //
  // In Phat Function runtime, we not support async/await, you need use `pink.batchHttpRequest` to
  // send http request. The function will return an array of response.
  //
  let response = pink.batchHttpRequest(
    [
      {
        url: lensApi,
        method: "POST",
        headers,
        body,
        returnTextBody: true,
      },
    ],
    2000
  )[0];
  if (response.statusCode !== 200) {
    console.log(
      `Fail to read Lens api with status code: ${response.statusCode}, error: ${
        response.error || response.body
      }}`
    );
    throw Error.FailedToFetchData;
  }
  let respBody = response.body;
  if (typeof respBody !== "string") {
    throw Error.FailedToDecode;
  }
  return JSON.parse(respBody);
}

Here we utilize the pink.batchHttpRequest() function, but we only use a single HTTP request. Before going any further, let's clarify what is available with @phala/pink-env.

pink.invokeContract() & pink.invokeContractDelegate()

  • pink.invokeContract() allows for a call to a specified address of a Phat contract deployed on Phala's Mainnet or PoC6 Testnet depending on where you deploy your function.

  • pink.invokeContractDelegate() is similar but instead the call on a Phat Contract is targeted by the code hash.

// Delegate calling
const delegateOutput = pink.invokeContractDelegate({
  codeHash:
    "0x0000000000000000000000000000000000000000000000000000000000000000",
  selector: 0xdeadbeef,
  input: "0x00",
});

// Instance calling
const contractOutput = pink.invokeContract({
  callee: "0x0000000000000000000000000000000000000000000000000000000000000000",
  input: "0x00",
  selector: 0xdeadbeef,
  gasLimit: 0n,
  value: 0n,
});

This is the low-level API for cross-contract call. If you have the contract metadata file, there is a script to help generate the high-level API for cross-contract call. For example run the following command:

python meta2js.py --keep System::version /path/to/system.contract

Would generate the following code:

function invokeContract(callee, selector, args, metadata, registry) {
    const inputCodec = pink.SCALE.codec(metadata.inputs, registry);
    const outputCodec = pink.SCALE.codec(metadata.output, registry);
    const input = inputCodec.encode(args ?? []);
    const output = pink.invokeContract({ callee, selector, input });
    return outputCodec.decode(output);
}
class System {
    constructor(address) {
        this.typeRegistryRaw = '#u16\n(0,0,0)\n<CouldNotReadInput::1>\n<Ok:1,Err:2>'
        this.typeRegistry = pink.SCALE.parseTypes(this.typeRegistryRaw);
        this.address = address;
    }
   
    system$Version() {
        const io = {"inputs": [], "output": 3};
        return invokeContract(this.address, 2278132365, [], io, this.typeRegistry);
    }
}

Then you can use the high-level API to call the contract:

const system = new System(systemAddress);
const version = system.system$Version();
console.log("version:", version);

pink.httpRequest()

HTTP request is supported in the JS environment. However, the API is sync rather than async. This is different from other JavaScript engines.

The pink.httpRequest() allows for you to make a single HTTP request from your function to an HTTP endpoint. You will have to define your args:

  • url: string – The URL to send the request to.

  • method?: string – (Optional) The HTTP method to use for the request (e.g. GET, POST, PUT). Defaults to GET.

  • headers?: Headers – (Optional) An map-like object containing the headers to send with the request.

  • body?: Uint8Array | string – (Optional) The body of the request, either as a Uint8Array or a string.

  • returnTextBody?: boolean – (Optional) A flag indicating whether the response body should be returned as a string (true) or a Uint8Array (false).

Returned is the Object response from the HTTP request containing the following fields:

  • {number} statusCode - The HTTP status code of the response.

  • {string} reasonPhrase - The reason phrase of the response.

  • {Headers} headers - An object containing the headers of the response.

  • {(Uint8Array|string)} body - The response body, either as a Uint8Array or a string depending on the value of args.returnTextBody.

Here is an example:

const response = pink.httpRequest({
  url: "https://httpbin.org/ip",
  method: "GET",
  returnTextBody: true,
});
console.log(response.body);

pink.batchHttpRequest()

Now you may need to call multiple APIs at once, this would require you to use the pink.batchHttpRequest() function to ensure you do not timeout (timeouts for Phat Contract is 10 seconds) on your response. The args and returned Object are the same as pink.httpRequest(), but instead you can create an array of HTTP requests within the function. Since we have an example above of how to use a pink.batchHttpRequest(), before an examples let's look at the syntax. You will have to define your array of args:

  • url: string – The URL to send the request to.

  • method?: string – (Optional) The HTTP method to use for the request (e.g. GET, POST, PUT). Defaults to GET.

  • headers?: Headers – (Optional) An map-like object containing the headers to send with the request.

  • body?: Uint8Array | string – (Optional) The body of the request, either as a Uint8Array or a string.

  • returnTextBody?: boolean – (Optional) A flag indicating whether the response body should be returned as a string (true) or a Uint8Array (false).

  • [x] - this value is what you will see below as [0] which points to index 0 in the array of HTTP requests.

  • timeout_ms?: number - (Optional) a number representing the number of milliseconds before the batch HTTP requests timeout. Returned is the Object response from the HTTP request containing the following fields:

  • {number} statusCode - The HTTP status code of the response.

  • {string} reasonPhrase - The reason phrase of the response.

  • {Headers} headers - An object containing the headers of the response.

  • {(Uint8Array|string)} body - The response body, either as a Uint8Array or a string depending on the value of args.returnTextBody.

  • error?: string - (Optional) The error string that will be mapped to the error corresponding to the index of the HTTP request in the batch HTTP requests.

  • [x] - this value is what you will see below as [0] which points to index 0 in the array of HTTP requests.

Let's create a unique example. In this example, we will:

  • Use pink.batchHttpRequest() to:

  • Take response body of The Odds API query and send to a Telegram Group in a single pink.httpRequest()

const sportName = 'baseball_mlb'
const odds_http_endpoint = `https://api.the-odds-api.com/v4/sports/${sportName}/scores/?apiKey=37af51c4c3d1823308ae2966bcfe7`;
const kvdb_http_endpoint = `https://kvdb.io/AwA4DS6fJN69q4erVyjKzY`;
const tg_bot_http_endpoint = `https://api.telegram.org/bot4876363250:A1W7F0jeyMmvJAGd7K_12y_5qFjbXwPgpTQ/sendMessage?chat_id=-1001093498619&text=`;
// headers for the HTTP request args
let headers = {
    "Content-Type": "application/json",
    "User-Agent": "phat-contract",
};
// Create body for updating kvdb.io
const kvdbUpdate = JSON.stringify({
    "txn": [
        {"set": "hello", "value": "world"}
    ]
});
const body2 = stringToHex(kvdbUpdate);
// Notice that depending on the number of queries, you will define and array of responses from the response.
const [res1, res2] = pink.batchHttpRequest([
    {
        url: odds_http_endpoint,
        method: "GET",
        headers,
        returnTextBody: true,
    },
    {
        url: `${kvdb_http_endpoint}/hello`,
        method: "POST",
        headers: headers2,
        body: body2,
        returnTextBody: true,
    }
]);
// Notice that the single HTTP request uses the response data from the first HTTP request in the batchHttpRequest function.
const res3 = pink.httpRequest({
    url: `${tg_bot_http_endpoint}${res1.body}`,
    method: "POST",
    headers,
    returnTextBody: true,
});

Here are the expected result of executing this:

  • KV DB on kvdb.io

  • Telegram Bot Updates Telegram Group

Pretty nifty, right? This is the power of the customized function with the ability to make single or batch HTTP requests. However, this example is missing some error handling which is our next topic.

Error Handling

To add some error handling to an HTTP request, you can check the default example with the query to Lens API above.

A simple example can be defined:

try {
  const response = pink.httpReqeust({
    url: "https://httpbin.org/ip",
    method: 42,
    returnTextBody: true,
  });
  console.log(response.body);
} catch (err) {
  console.log("Some error ocurred:", err);
}

This would send an error to the logserver:

JS: Some error ocurred: TypeError: invalid value for field 'method'

pink.deriveSecret()

pink.deriveSecret() takes in a salt of either UInt8Array | string and generates a secret key response of type UInt8Array.

Let's build an example that will derive a secret from a salt howdy and update the Telegram group from above about the secret.

const tg_bot_http_endpoint = `https://api.telegram.org/bot4876363250:A1W7F0jeyMmvJAGd7K_12y_5qFjbXwPgpTQ/sendMessage?chat_id=-1001093498619&text=`;
// headers for the HTTP request args
let headers = {
    "Content-Type": "application/json",
    "User-Agent": "phat-contract",
};
const res3 = pink.httpRequest({
    url: `${tg_bot_http_endpoint}shhhhhhh\nthis_is_a_secret:\n[${secret}]`,
    method: "POST",
    headers,
    returnTextBody: true,
});

Here is the result 😜

pink.hash()

pink.hash() generates a hash based on the following params:

  • algorithm- the hash algorithm to use. Supported values are “blake2b128”, “blake2b256”, “sha256”, “keccak256”.

  • message – The message to hash, either as a Uint8Array or a string.

Let's create an example to hash the values of hello and world to store in the KVDB we used earlier. We can also send the mapping to Telegram group to show a pink.batchHttpRequest().

const kvdb_http_endpoint = `https://kvdb.io/AwA4DS6fJN69q4erVyjKzY`;
const tg_bot_http_endpoint = `https://api.telegram.org/bot4876363250:A1W7F0jeyMmvJAGd7K_12y_5qFjbXwPgpTQ/sendMessage?chat_id=-1001093498619&text=`;
// headers for the HTTP request args
let headers = {
    "Content-Type": "application/json",
    "User-Agent": "phat-contract",
};
// Generate a hash for each algorithm for hello
const blake2b128Hello = pink.hash('blake2b128', 'hello');
const blake2b256Hello = pink.hash('blake2b256', 'hello');
const sha256Hello = pink.hash('sha256', 'hello');
const keccak256Hello = pink.hash('keccak256', 'hello');
const tgText = JSON.stringify({
    blake2b128Hello: blake2b128Hello,
    blake2b256Hello: blake2b256Hello,
    sha256Hello: sha256Hello,
    keccak256Hello: keccak256Hello
});
// KV Update Body
const kvdbUpdate = JSON.stringify({
    "txn": [
        {"set": "blake2b128Hello", "value": `${blake2b128Hello}`},
        {"set": "blake2b256Hello", "value": `${blake2b256Hello}`},
        {"set": "sha256Hello", "value": `${sha256Hello}`},
        {"set": "keccak256Hello", "value": `${keccak256Hello}`}
    ]
});
const body2 = stringToHex(kvdbUpdate);
// Batch HTTP request
const [res1, res2] = pink.batchHttpRequest([
    {
        url: `${kvdb_http_endpoint}/hello`,
        method: "POST",
        headers: headers2,
        body: body2,
        returnTextBody: true,
    },
    {
        url: `${tg_bot_http_endpoint}\n${tgText}`,
        method: "POST",
        headers,
        returnTextBody: true,
    }
]);

Let's see how the results look.

  • KVDB hashes for hello

  • Telegram bot sends hashes for hello

SCALE Codec

Let’s introduce the details of the SCALE codec API which is not documented in the above link.

The SCALE codec API is mounted on the global object pink.SCALE which contains the following functions:

  • pink.SCALE.parseTypes(types: string): TypeRegistry

  • pink.SCALE.codec(type: string | number | number[], typeRegistry?: TypeRegistry): Codec

Let’s make a basice example to show how to use the SCALE codec API:

const types = `
  Hash=[u8;32]
  Info={hash:Hash,size:u32}
`;
const typeRegistry = pink.SCALE.parseTypes(types);
const infoCodec = pink.SCALE.codec(`Info`, typeRegistry);
const encoded = infoCodec.encode({
 hash: "0x1234567890123456789012345678901234567890123456789012345678901234",
 size: 1234,
});
console.log("encoded:", encoded);
const decoded = infoCodec.decode(encoded);
pink.inspect("decoded:", decoded);

The above code will output:

JS: encoded: 18,52,86,120,144,18,52,86,120,144,18,52,86,120,144,18,52,86,120,144,18,52,86,120,144,18,52,86,120,144,18,52,210,4,0,0
JS: decoded: {
JS: hash: 0x1234567890123456789012345678901234567890123456789012345678901234,
JS: size: 1234
JS: }

Or using the direct encode/decode api which support literal type definition as well as a typename or id, for example:

const data = { name: "Alice", age: 18 };
const encoded = pink.SCALE.encode(data, "{ name: str, age: u8 }");
const decoded = pink.SCALE.decode(encoded, "{ name: str, age: u8 }");

Grammar of The Type Definition

In the above example, we use the following type definition:

Hash=[u8;32]
Info={hash:Hash,size:u32}

where we define a type Hash which is an array of 32 bytes, and a type Info which is a struct containing a Hash and a u32.

The grammar is defined as follows:

Each entry is type definition, which is of the form name=type. Where name must be a valid identifier, and type is a valid type expression described below.

Type expression can be one of the following:

Type ExpressionDescriptionExampleJS type

bool

Primitive type bool

true, false

u8, u16, u32, u64, u128, i8, i16, i32, i64, i128

Primitive number types

number or bigint

str

Primitive type str

string

[type;size]

Array type with element type type and size size.

[u8; 32]

Array of elements. (Uint8Array or 0x prefixed hex string is allowed for [u8; N])

[type]

Sequence type with element type type.

[u8]

Array of elements. (Uint8Array or 0x prefixed hex string is allowed for u8)

(type1, type2, ...)

Tuple type with elements of type type1, type2, …

(u8, str)

Array of value for inner type. (e.g. [42, 'foobar'])

{field1:type1, field2:type2, ...}

Struct type with fields and types.

{age:u32, name:str}

Object with field name as key

<variant1:type1, variant2:type2, ...>

Enum type with variants and types. if the variant is a unit variant, then the type expression can be omitted.

<Success:i32, Error:str>, <None,Some:u32>

Object with variant name as key. (e.g. {Some: 42})

@type

Compact number types. Only unsigned number types is supported

@u64

number or bigint

Generic Type Support

Generic parameters can be added to the type definition, for example:

Vec<T>=[T]

Option Type

The Option type is not a special type, but a vanilla enum type. It is needed to be defined by the user explicitly. Same for the Result type.

Option<T>=<None,Some:T>
Result<T,E>=<Ok:T,Err:E>

There is one special syntax for the Option type:

Option<T>=<_None,_Some:T>

If the Option type is defined in this way, then the None variant would be decoded as null instead of {None: null} and the Some variant would be decoded as the inner value directly instead of {Some: innerValue}. For example:

const encoded = pink.SCALE.encode(42, "<_None,_Some:u32>");
const decoded = pink.SCALE.decode(encoded, "<_None,_Some:u32>");
console.log(decoded); // 42

Nested Type Definition

Type definition can be nested, for example:

Block={header:{hash:[u8;32],size:u32}}

Handle EVM Smart Contract Encoding & Decoding

For TypeScript/JavaScript example scripts, check out @phala/pink-env examples.

Note: @phala/ethers will be no longer be maintained in favor of native support of viem.

Why viem

viem is a TypeScript Interface for Ethereum that provides low-level stateless primitives for interacting with Ethereum. An alternative to ethers.js and web3.js with a focus on reliability, efficiency, and excellent developer experience.

Using native viem in Phat Contract 2.0 to handle EVM Smart Contract encoding/decoding helps reduce the friction of maintaining custom code. For more information on the viem's why, check out the link below.

LogoWhy viemwagmi_sh
Why viem

For docs on how to use viem, check out the ABI section of the viem docs.

Example

In the Phat Contract 2.0 Starter Kit, there is a file in src/viem/coder.ts which will look like the following:

import {decodeAbiParameters, encodeAbiParameters, parseAbiParameters} from "viem";

export type HexString = `0x${string}`
export const encodeReplyAbiParams = 'uint respType, uint id, uint256 data';
export const decodeRequestAbiParams = 'uint id, string reqData';

export function encodeReply(abiParams: string, reply: [bigint, bigint, bigint]): HexString {
    return encodeAbiParameters(parseAbiParameters(abiParams),
        reply
    );
}

export function decodeRequest(abiParams: string, request: HexString): any {
    return decodeAbiParameters(parseAbiParameters(abiParams),
        request
    );
}

The 2 important functions in this file are:

  • decodeRequest(abiParams, request) - decodes the action request HexString that is passed into the main(request, secrets) entry function of the Phat Contract. You can find the expected encoded HexString in the OracleConsumerContract.sol request(string calldata reqData) function where the action is encoded with a uint id and string reqData in the _pushMessage(abi.encode(id, reqData)) function.

  • encodeReply(abiParams, reply) - encodes the action reply to be sent back to the Consumer Contract on the EVM change. The Consumer Contract consumes the action reply via the _onMessageReceived(bytes calldata action) function where data encoded can be decoded and handled based on the Consumer Contract logic. The default example encodes a tuple of uint respType, uint id, and uint256 data that in turn gets decoded in OracleConsumerContract.sol _onMessageReceived(bytes calldata action) function with (uint respType, uint id, uint256 data) = abi.decode(action, (uint, uint, uint256).

Let's breakdown the example and step through the process.

  1. encode action request in request(string calldata) of OracleConsumerContract.sol

  2. decode action request when parsing the encoded action in the Phat Contract 2.0 main(request, secrets) entry function in the src/index.ts file.

  3. encode the action reply in the Phat Contract to send to the OracleConsumerContract.sol

  4. decode the action reply in the OracleConsumerContract.sol function _onMessageReceived(bytes calldata action)

Here is a snippet of the code to encode a tuple that includes the uint id representing the request id and string calldata reqData that is the request data string.

For the example, we will pass in:

  • id = 1

  • reqData = "0x01"

OracleConsumerContract.sol

function request(string calldata reqData) public {
   // assemble the request
   uint id = nextRequest;
   requests[id] = reqData;
   _pushMessage(abi.encode(id, reqData));
   nextRequest += 1;
}

This will produce a HexString 0x0000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000043078303100000000000000000000000000000000000000000000000000000000 representing (1, "0x01")

Closing

Congratulations! You now possess the power to extend the functionality of your functions in many unique ways. If this sparks some ideas that require some extensive functionality that is not supported in @phala/pink-env, jump in our discord, and we can help you learn a little rust to build some Phat Contracts with the Rust SDK then leverage the functions pink.invokeContract() & pink.invokeContractDelegate() to make calls to the Rust SDK deployed Phat Contracts.

PreviousConnect Phat Contract to EVM Consumer ContractNextHandling Secrets

Last updated

Logo

Participate

Compute ProvidersNodeCommunityAbout Us

Resources

Technical WhitepaperToken EconomicsDocsGitHub

More

TestnetExplorerCareersResponsible Disclosure

COPYRIGHT © 2024 PHALA.LTD ALL RIGHTS RESERVED. May Phala be with you!