Walkthrough for deploying a module to Kadena's Testnet

deploy-testnet-module.md

Deploy Module to Testnet Using Command Line

This document will walk you through how to deploy your first module to Testnet using the Command Line. To achieve this, we will use the pact command line tool's API Request formatter (pact -a) and the curl command line tool.

Step 0: Install the Prerequisites

• Install Pact

Step 1: Create the Pact Module

We will be deploying the following pact module. For simplicity's sake, this walkthrough expects that the pact code we are deploying is not using a transaction's data field (read-keyset is one such pact function that makes use of this field). Otherwise, the accompanying YAML file will have to change. We also assume that this pact code is saved as test.pact.

(namespace 'free)

(module someModuleName AUTONOMOUS

  (defcap AUTONOMOUS ()
    true)

  (defun dummy ()
    (+ 1 2)
  )
)

Step 2: Create the YAML file

The following YAML file will be used along with pact -a to sign and produce the escaped JSON needed to submit a transaction to Testnet.

codeFile: /Users/linda.ortega.cordoves/pact/test.pact
networkId: testnet04
publicMeta:
  chainId: "0"
  gasLimit: 1000
  ttl: 28000
  creationTime: 1585056536
  sender: "testing"
  gasPrice: 0.00001

keyPairs:
  - public: 1d877a7b4524b6724a6ae708cf9ea7396d6ee9d17b10098b7793800177669c1d
    secret: 33fcd94b8a42057bd4e3190f8983e3a73ec96c3f60df95c9e2aa3f13602c714f
nonce: step02

This file makes a couple of assumptions that might change depending on your specific implementation:

• The full path of the pact we want to upload is: /Users/linda.ortega.cordoves/pact/test.pact

• We want to submit a transaction to Testnet, whose network id is testnet04

• We want to submit to the zero'th chain on Testnet, which has a chain id of "0"

• That the current creation time in UNIX Epoch time is 1585056536 seconds. This value MUST CHANGE, so calculate it by either navigating to this website or running date +%s on the command line.

• That "testing" is the account paying for gas (aka the "sender") on the Testnet network. To create a Testnet account and fund it some coins, navigate to the Testnet Coin Faucet. You will need to have generated an ED22519 public-private key pair to use the faucet. You can use pact -g to generate this key pair. Make sure to save it somewhere save.

• That the key pair specified in "keyPairs" corresponds to the key pair used to create the gas payer account, which in this example is "testing". This must change from the defaults provided.

• That we saved this YAML file as /Users/linda.ortega.cordoves/pact/test.yaml.

Step 3: Submit Transaction to Testnet

We will now submit the example pact module we created by hitting the /send endpoint of a Testnet node. In the command line, run the following command:

pact -a /Users/linda.ortega.cordoves/pact/test.yaml | curl -H "Content-Type: application/json" -d @- https://us1.testnet.chainweb.com/chainweb/0.0/testnet04/chain/0/pact/api/v1/send

Some of the assumptions we made when creating the YAML file become important here:

• The network id must match the node endpoint we submit to. Since the network id we chose is testnet04, we must submit to /chainweb/0.0/testnet04/. And the node we submit to (in this case us1.testnet.chainweb.com) must have this network id.
• The chain id must also match. We chose chain id of "0", so we must submit to /chain/0/.
• That we saved the yaml file to /Users/linda.ortega.cordoves/pact/test.yaml.

If we submitted the transaction successfully we will see the following:

{"requestKeys":["Vetli41gi_S4-dZlro0visI8QT15brHoPe4vxMmhdek"]}

This means that our transaction was successfully added to the blockchain's mempool and is waiting to be mined. Make note of the request key returned from /send as we will use it when polling for the result of the transaction.

It is also possible that our transaction will fail node validation when we attempt to submit it. If this happens, you will receive a validation failure message instead of the request key.

Step 4: Verify the Result of the Transaction

We will now try to get the results of the transaction we submitted to the Testnet network by hitting the /poll endpoint. In the command line, run the following command:

curl -H "Content-Type: application/json" -d '{"requestKeys":["Vetli41gi_S4-dZlro0visI8QT15brHoPe4vxMmhdek"]}' -X POST https://us1.testnet.chainweb.com/chainweb/0.0/testnet04/chain/0/pact/api/v1/poll

Again, we make a couple of assumptions in this step:

• That the Testnet node we want to poll from is us1.testnet.chainweb.com.
• That the network id is testnet04. Note that part of the endpoint is /chainweb/0.0/testnet04/.
• That the chain id we are polling from is chain "0". Note that part of the endpoint is /chain/0/.
• That the request key we are polling for is Vetli41gi_S4-dZlro0visI8QT15brHoPe4vxMmhdek.

If the transaction was successfully mined and thus added to the blockchain, then /poll will return the following JSON object:

{
  "Vetli41gi_S4-dZlro0visI8QT15brHoPe4vxMmhdek": {
    "gas": 58,
    "result": {
      "status": "success",
      "data": "Loaded module free.linda-test, hash n0g99JhWnO2F7X7f8o_zcAiSHBAWS_QSAfn4yUaqpps"
    },
    "reqKey": "Vetli41gi_S4-dZlro0visI8QT15brHoPe4vxMmhdek",
    "logs": "0KzZQDJmEgnAKvPnO20UeGoE7KGCIN22nhjraeyp1aw",
    "metaData": {
      "blockTime": 1585056990071469,
      "prevBlockHash": "dIYmpjBQge9yw0Yzhn0Sau-wJFwsLOFBmGbV3_0xYeE",
      "blockHash": "yULpC5C-7tzRcc9sWm-f1bOC3JDvtxwT61hruW0aXrA",
      "blockHeight": 261712
    },
    "continuation": null,
    "txId": 266084
  }
}

Please note that it is possible that a transaction fails at the pact level, but still gets added to the blockchain and gas gets charged. If this happens the result.status field will be failure.

If a transaction has not be mined yet, /poll will return {}. Keep retrying until you receive the JSON object shown above.

Step 5: Further Reading

• API Request Formatter. More information on how to use the pact -a tool we used in this example.
• Pact Endpoints. More details on Pact's endpoints. Please note that this documentation is Pact-specific and not Chainweb specific. For example, Chainweb expects pact endpoints to be appended to the following: https://us1.testnet.chainweb.com/chainweb/0.0/testnet04/chain/0/pact/.
• Pact Transaction. A schema of a Pact Command (aka a Pact Transaction), which is the JSON object submitted to the /send endpoint.
• Pact Transaction Result. A schema of the Pact Command Result (aka the result of executing a pact transaction), which is the JSON object returned by /poll.