Ontology Rosetta Node | How to Deploy an Ontology Rosetta Node?

Overview

Here we lay out the procedure one needs to follow to deploy an Ontology node that adheres to Rosetta’s blockchain standards. By complying to the rosetta blockchain specification, we at Ontology aim to streamline the development process for blockchain developers by ensuring certain aspects of the system are structured in a manner such that basic operations such as the deployment process, communication, and certain data formats are standardized, thus increasing the overall flexibility of the system.

Environment Setup

Before running any of the commands specified below, please ensure that you are running the latest version of Docker. If you don’t have it installed on your system already, please follow this link to download Docker.

Next, clone the Ontology rosetta node source code library using the following command:


git clone https://github.com/ontio/ontology-rosetta.git

We will be building the node directly from the source code.

The Dockerfile already contains all the necessary dependencies. Within the directory, please run the following command to build the docker image:


make docker

Node Deployment

First, we create a new directory where all the node details will be stored.

Please ensure that you have enough disk space (at least 100GB free) to store the chain and operation data. This establishes the smoothness of node operation and lowers the need for maintenance over time.


mkdir Chain

Next, run the ont-rosetta image using the command specified below. Note that we mount three volumes into the container. The three volumes store log data, block data, and allow access to the host configuration file.


# you are using the default config in this repo

docker run --name ont-rosetta -d -v $(realpath Log):/data/Log -v $(realpath Chain):/data/Chain -v $(realpath rosetta-config.json):/data/rosetta-config.json -p 9090:8080 ontology-rosetta:latest

In case you wish to connect to the test net, set the NETWORK_ID to 2 as such:


docker run --name ont-rosetta -d --env NETWORK_ID=2 -v $(realpath Log):/data/Log -v $(realpath Chain):/data/Chain -v $(realpath rosetta-config.json):/data/rosetta-config.json -p 9090:8080 ontology-rosetta:latest

Configuration

The default configuration in the rosetta-config.json file is as follows:


{

  "rosetta": {

    "version": "1.3.1",

    "port": 8080,

    "block_wait_time": 1

  },

  "monitorOEP4ScriptHash": []

}

version: Rosetta SDK version
port: Rosetta restful API port
block_wait_time: Time between subsequent block scans (in seconds)
monitorOEP4ScriptHash: OEP4 token contract hash to be monitored

API Reference

Based on the Rosetta specification, Ontology rosetta-compliant nodes make the following Restful APIs available.

The methods have been classified based on the return value.

Network

Fetch the list of available networks

Method: POST

URL: /network/list

Sample Request:


{

  "metadata": {}

}

Sample Response:


{

  "network_identifiers": [

    {

      "blockchain": "ont",

      "network": "mainnet"

    }

  ]

}

Fetch network options

Method: POST

URL: /network/options

Sample Request:


{

  "network_identifier": {

    "blockchain": "ont",

    "network": "mainnet"

  }

}

Sample Response:


{

  "version": {

    "rosetta_version": "1.3.1",

    "node_version": "1.9.0"

  },

  "allow": {

    "operation_statuses": [

      {

        "status": "SUCCESS",

        "successful": true

      },

      {

        "status": "FAILED",

        "successful": false

      }

    ],

    "operation_types": ["transfer"],

    "errors": [

      {

        "code": 400,

        "message": "network identifier is not supported",

        "retriable": false

      },

      {

        "code": 401,

        "message": "block identifier is empty",

        "retriable": false

      },

      {

        "code": 402,

        "message": "block index is invalid",

        "retriable": false

      },

      {

        "code": 403,

        "message": "get block failed",

        "retriable": true

      },

      {

        "code": 404,

        "message": "block hash is invalid",

        "retriable": false

      },

      {

        "code": 405,

        "message": "get transaction failed",

        "retriable": true

      },

      {

        "code": 406,

        "message": "transaction hash is invalid",

        "retriable": false

      },

      {

        "code": 407,

        "message": "commit transaction failed",

        "retriable": false

      },

      {

        "code": 408,

        "message": "tx hash is invalid",

        "retriable": false

      },

      {

        "code": 409,

        "message": "block is not exist",

        "retriable": false

      },

      {

        "code": 500,

        "message": "service not realize",

        "retriable": false

      },

      {

        "code": 501,

        "message": "addr is invalid",

        "retriable": true

      },

      {

        "code": 502,

        "message": "get balance error",

        "retriable": true

      },

      {

        "code": 503,

        "message": "parse int error",

        "retriable": true

      },

      {

        "code": 504,

        "message": "json marshal failed",

        "retriable": false

      },

      {

        "code": 505,

        "message": "parse tx payload failed",

        "retriable": false

      },

      {

        "code": 506,

        "message": "currency not config",

        "retriable": false

      },

      {

        "code": 507,

        "message": "params error",

        "retriable": true

      },

      {

        "code": 508,

        "message": "contract addr invalid",

        "retriable": true

      },

      {

        "code": 509,

        "message": "preExecute contract failed",

        "retriable": false

      },

      {

        "code": 510,

        "message": "query balance failed",

        "retriable": true

      }

    ]

  }

}

Fetch the network status

Method: POST

URL: /network/status

Sample Request:


{

  "network_identifier": {

    "blockchain": "ont",

    "network": "mainnet"

  }

}

Sample Response:


{

  "current_block_identifier": {

    "index": 4789126,

    "hash": "76fcf0fbd5e979721fe52e472ac79eb26f4bc502c371508574c0e03386be20e6"

  },

  "current_block_timestamp": 1560312815000,

  "genesis_block_identifier": {

    "index": 0,

    "hash": "1b8fa7f242d0eeb4395f89cbb59e4c29634047e33245c4914306e78a88e14ce5"

  },

  "peers": [

    {

      "peer_id": "000000000000000000000000b41fe9ceaaaa4d7b",

      "metadata": {

        "address": "40.113.237.243:20338",

        "height": 8454242

      }

    },

    {

      "peer_id": "000000000000000000000000a4f0c524d8efd6a8",

      "metadata": {

        "address": "139.219.141.104:20338",

        "height": 8454242

      }

    },

    {

      "peer_id": "0000000000000000000000008e6528f4659f3112",

      "metadata": {

        "address": "50.18.219.74:20338",

        "height": 8454242

      }

    }

  ]

}

Account

Fetch account balance

Method: POST

URL: /account/balance

Sample Request:


{

  "network_identifier": {

    "blockchain": "ont",

    "network": "mainnet"

  },

  "account_identifier": {

    "address": "AFmseVrdL9f9oyCzZefL9tG6UbviEH9ugK",

    "metadata": {}

  },

  "block_identifier": {

    "index": 310

  }

}

Sample Response:


{

  "block_identifier": {

    "index": 310,

    "hash": "11405500403779cff364803bbd7fe4dc74ba9119015fd79473c188b727769c52"

  },

  "balances": [

    {

      "value": "14700000",

      "currency": {

        "symbol": "ONT",

        "decimals": 0,

        "metadata": {

          "ContractAddress": "0100000000000000000000000000000000000000",

          "TokenType": "Governance Token"

        }

      }

    },

    {

      "value": "1750000140000",

      "currency": {

        "symbol": "ONG",

        "decimals": 9,

        "metadata": {

          "ContractAddress": "0200000000000000000000000000000000000000",

          "TokenType": "Utility Token"

        }

      }

    }

  ]

}

Block

Fetch block details

Method: POST

URL: /block

Sample Request:


{

  "network_identifier": {

    "blockchain": "ont",

    "network": "mainnet"

  },

  "block_identifier": {

    "index": 54

  }

}


{

  "block": {

    "block_identifier": {

      "index": 54,

      "hash": "790ea8942e5722c75ba638312caa8c1380c41da4c145d6493ae510eb6017c5f3"

    },

    "parent_block_identifier": {

      "index": 53,

      "hash": "2b52c7fcdbdcd362211e1646fa6351c8f6fd4cbfa520fe7857133e59061ff348"

    },

    "timestamp": 1530389834000,

    "transactions": [

      {

        "transaction_identifier": {

          "hash": "20247d9df50d830b8978a5c49313a6f8a118fd5bb9c2950e3c7f95f5ac6410f6"

        },

        "operations": [

          {

            "operation_identifier": {

              "index": 0

            },

            "type": "transfer",

            "status": "SUCCESS",

            "account": {

              "address": "AJMFNZL5jGjZJEhBrJfVLHJeJ3KwiczJ6B"

            },

            "amount": {

              "value": "-1000000000",

              "currency": {

                "symbol": "ONT",

                "decimals": 0,

                "metadata": {

                  "ContractAddress": "0100000000000000000000000000000000000000",

                  "TokenType": "Governance Token"

                }

              }

            }

          },

          {

            "operation_identifier": {

              "index": 1

            },

            "related_operations": [

              {

                "index": 0

              }

            ],

            "type": "transfer",

            "status": "SUCCESS",

            "account": {

              "address": "AWyEMxiLUVr5MeVJe3Fw5Xsij7iZUmfYyk"

            },

            "amount": {

              "value": "1000000000",

              "currency": {

                "symbol": "ONT",

                "decimals": 0,

                "metadata": {

                  "ContractAddress": "0100000000000000000000000000000000000000",

                  "TokenType": "Governance Token"

                }

              }

            }

          }

        ]

      }

    ]

  }

}

Fetch transaction information from a block

Method: POST

URL: /block/transaction

Sample Request:


{

  "network_identifier": {

    "blockchain": "ont",

    "network": "mainnet"

  },

  "block_identifier": {

    "index": 54,

    "hash": "790ea8942e5722c75ba638312caa8c1380c41da4c145d6493ae510eb6017c5f3"

  },

  "transaction_identifier": {

    "hash": "20247d9df50d830b8978a5c49313a6f8a118fd5bb9c2950e3c7f95f5ac6410f6"

  }

}

Sample Response:


{

  "transaction": {

    "transaction_identifier": {

      "hash": "20247d9df50d830b8978a5c49313a6f8a118fd5bb9c2950e3c7f95f5ac6410f6"

    },

    "operations": [

      {

        "operation_identifier": {

          "index": 0

        },

        "type": "transfer",

        "status": "SUCCESS",

        "account": {

          "address": "AJMFNZL5jGjZJEhBrJfVLHJeJ3KwiczJ6B"

        },

        "amount": {

          "value": "-1000000000",

          "currency": {

            "symbol": "ONT",

            "decimals": 0,

            "metadata": {

              "ContractAddress": "0100000000000000000000000000000000000000",

              "TokenType": "Governance Token"

            }

          }

        }

      },

      {

        "operation_identifier": {

          "index": 1

        },

        "related_operations": [

          {

            "index": 0

          }

        ],

        "type": "transfer",

        "status": "SUCCESS",

        "account": {

          "address": "AWyEMxiLUVr5MeVJe3Fw5Xsij7iZUmfYyk"

        },

        "amount": {

          "value": "1000000000",

          "currency": {

            "symbol": "ONT",

            "decimals": 0,

            "metadata": {

              "ContractAddress": "0100000000000000000000000000000000000000",

              "TokenType": "Governance Token"

            }

          }

        }

      }

    ]

  }

}

Construction

Fetch transaction creation metadata

Method: POST

URL: /construction/metadata

Sample Request:


{

  "network_identifier": {

    "blockchain": "ont",

    "network": "mainnet"

  },

  "options": {}

}

Sample Response:


{

  "metadata": {

    "calcul_history_block_height": 3627077,

    "current_block_hash": "832ed41b4e79641288ea8cd341b7949ee4773c8abb8288f4386422f9248df911",

    "current_block_height": 3627179

  }

}

calcul_history_block_height: Current account balance for synchronized block height
current_block_hash: Block hash
current_block_height: Current block height

Submit a signed transaction

Method: POST

URL: /construction/submit

Sample Request:


{

  "network_identifier": {

    "blockchain": "ont",

    "network": "mainnet"

  },

  "signed_transaction": "<signed tx hex>"

}

Sample Response:


{

  "transaction_identifier": {

    "hash": "<tx hash>"

  },

  "metadata": {}

}

Mempool

Fetch all mempool transactions

Method: POST

URL: /mempool

Sample Request:


{

  "network_identifier": {

    "blockchain": "ont",

    "network": "mainnet"

  }

}

Sample Response:


{

  "transaction_identifiers": [

    {

      "hash": "<tx hash>"

    }

  ]

}

Fetch details for a mempool transaction

Method: POST

URL: /mempool/transaction

Sample Request:


{

  "network_identifier": {

    "blockchain": "ont",

    "network": "mainnet"

  },

  "transaction_identifier": {

    "hash": "20247d9df50d830b8978a5c49313a6f8a118fd5bb9c2950e3c7f95f5ac6410f6"

  }

}

Sample Response:


{

  "transaction": {

    "transaction_identifier": {

      "hash": "20247d9df50d830b8978a5c49313a6f8a118fd5bb9c2950e3c7f95f5ac6410f6"

    },

    "operations": [

      {

        "operation_identifier": {

          "index": 0

        },

        "type": "transfer",

        "status": "SUCCESS",

        "account": {

          "address": "AJMFNZL5jGjZJEhBrJfVLHJeJ3KwiczJ6B"

        },

        "amount": {

          "value": "-1000000000",

          "currency": {

            "symbol": "ONT",

            "decimals": 0,

            "metadata": {

              "ContractAddress": "0100000000000000000000000000000000000000",

              "TokenType": "Governance Token"

            }

          }

        }

      },

      {

        "operation_identifier": {

          "index": 1

        },

        "related_operations": [

          {

            "index": 0

          }

        ],

        "type": "transfer",

        "status": "SUCCESS",

        "account": {

          "address": "AWyEMxiLUVr5MeVJe3Fw5Xsij7iZUmfYyk"

        },

        "amount": {

          "value": "1000000000",

          "currency": {

            "symbol": "ONT",

            "decimals": 0,

            "metadata": {

              "ContractAddress": "0100000000000000000000000000000000000000",

              "TokenType": "Governance Token"

            }

          }

        }

      }

    ]

  }

}

Thanks for sharing @Ontology!

Appreciate the walkthrough to help developers get started with your implementation.

1 Like

You can also access it on our document center :sunglasses: :point_down::


2 Likes