diff --git a/api/admin/service.md b/api/admin/service.md new file mode 100644 index 000000000000..94afbf370451 --- /dev/null +++ b/api/admin/service.md @@ -0,0 +1,442 @@ +--- +tags: [AvalancheGo APIs] +description: This page is an overview of the Admin API associated with AvalancheGo. +sidebar_label: Admin API +pagination_label: Admin API +--- + +# Admin API + +This API can be used for measuring node health and debugging. + +:::info +The Admin API is disabled by default for security reasons. To run a node with the Admin API +enabled, use [config flag `--api-admin-enabled=true`](/nodes/configure/avalanchego-config-flags.md#--api-admin-enabled-boolean). + +This API set is for a specific node, it is unavailable on the [public server](/tooling/rpc-providers.md). + +::: + +## Format + +This API uses the `json 2.0` RPC format. For details, see [here](/reference/standards/guides/issuing-api-calls.md). + +## Endpoint + +```text +/ext/admin +``` + +## Methods + +### `admin.alias` + +Assign an API endpoint an alias, a different endpoint for the API. The original endpoint will still +work. This change only affects this node; other nodes will not know about this alias. + +**Signature:** + +```text +admin.alias({endpoint:string, alias:string}) -> {} +``` + +- `endpoint` is the original endpoint of the API. `endpoint` should only include the part of the + endpoint after `/ext/`. +- The API being aliased can now be called at `ext/alias`. +- `alias` can be at most 512 characters. + +**Example Call:** + +```bash +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"admin.alias", + "params": { + "alias":"myAlias", + "endpoint":"bc/X" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": {} +} +``` + +Now, calls to the X-Chain can be made to either `/ext/bc/X` or, equivalently, to `/ext/myAlias`. + +### `admin.aliasChain` + +Give a blockchain an alias, a different name that can be used any place the blockchain’s ID is used. + +:::note Aliasing a chain can also be done via the [Node API](https://docs.avax.network/nodes/configure/avalanchego-config-flags.md#--chain-aliases-file-string). +Note that the alias is set for each chain on each node individually. In a multi-node Subnet, the +same alias should be configured on each node to use an alias across a Subnet successfully. Setting +an alias for a chain on one node does not register that alias with other nodes automatically. + +::: + +**Signature:** + +```text +admin.aliasChain( + { + chain:string, + alias:string + } +) -> {} +``` + +- `chain` is the blockchain’s ID. +- `alias` can now be used in place of the blockchain’s ID (in API endpoints, for example.) + +**Example Call:** + +```bash +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"admin.aliasChain", + "params": { + "chain":"sV6o671RtkGBcno1FiaDbVcFv2sG5aVXMZYzKdP4VQAWmJQnM", + "alias":"myBlockchainAlias" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": {} +} +``` + +Now, instead of interacting with the blockchain whose ID is +`sV6o671RtkGBcno1FiaDbVcFv2sG5aVXMZYzKdP4VQAWmJQnM` by making API calls to +`/ext/bc/sV6o671RtkGBcno1FiaDbVcFv2sG5aVXMZYzKdP4VQAWmJQnM`, one can also make calls to +`ext/bc/myBlockchainAlias`. + +### `admin.getChainAliases` + +Returns the aliases of the chain + +**Signature:** + +```text +admin.getChainAliases( + { + chain:string + } +) -> {aliases:string[]} +``` + +- `chain` is the blockchain’s ID. + +**Example Call:** + +```bash +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"admin.getChainAliases", + "params": { + "chain":"sV6o671RtkGBcno1FiaDbVcFv2sG5aVXMZYzKdP4VQAWmJQnM" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "aliases": [ + "X", + "avm", + "2eNy1mUFdmaxXNj1eQHUe7Np4gju9sJsEtWQ4MX3ToiNKuADed" + ] + }, + "id": 1 +} +``` + +### `admin.getLoggerLevel` + +Returns log and display levels of loggers. + +**Signature:** + +```text +admin.getLoggerLevel( + { + loggerName:string // optional + } +) -> { + loggerLevels: { + loggerName: { + logLevel: string, + displayLevel: string + } + } + } +``` + +- `loggerName` is the name of the logger to be returned. This is an optional argument. If not + specified, it returns all possible loggers. + +**Example Call:** + +```bash +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"admin.getLoggerLevel", + "params": { + "loggerName": "C" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "loggerLevels": { + "C": { + "logLevel": "DEBUG", + "displayLevel": "INFO" + } + } + }, + "id": 1 +} +``` + +### `admin.loadVMs` + +Dynamically loads any virtual machines installed on the node as plugins. See +[here](/build/vm/intro#installing-a-vm) for more information on how to install a +virtual machine on a node. + +**Signature:** + +```sh +admin.loadVMs() -> { + newVMs: map[string][]string + failedVMs: map[string]string, +} +``` + +- `failedVMs` is only included in the response if at least one virtual machine fails to be loaded. + +**Example Call:** + +```bash +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"admin.loadVMs", + "params" :{} +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "newVMs": { + "tGas3T58KzdjLHhBDMnH2TvrddhqTji5iZAMZ3RXs2NLpSnhH": ["foovm"] + }, + "failedVMs": { + "rXJsCSEYXg2TehWxCEEGj6JU2PWKTkd6cBdNLjoe2SpsKD9cy": "error message" + } + }, + "id": 1 +} +``` + +### `admin.lockProfile` + +Writes a profile of mutex statistics to `lock.profile`. + +**Signature:** + +```text +admin.lockProfile() -> {} +``` + +**Example Call:** + +```bash +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"admin.lockProfile", + "params" :{} +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": {} +} +``` + +### `admin.memoryProfile` + +Writes a memory profile of the to `mem.profile`. + +**Signature:** + +```text +admin.memoryProfile() -> {} +``` + +**Example Call:** + +```bash +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"admin.memoryProfile", + "params" :{} +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": {} +} +``` + +### `admin.setLoggerLevel` + +Sets log and display levels of loggers. + +**Signature:** + +```text +admin.setLoggerLevel( + { + loggerName: string, // optional + logLevel: string, // optional + displayLevel: string, // optional + } +) -> {} +``` + +- `loggerName` is the logger's name to be changed. This is an optional parameter. If not specified, + it changes all possible loggers. +- `logLevel` is the log level of written logs, can be omitted. +- `displayLevel` is the log level of displayed logs, can be omitted. + +`logLevel` and `displayLevel` cannot be omitted at the same time. + +**Example Call:** + +```bash +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"admin.setLoggerLevel", + "params": { + "loggerName": "C", + "logLevel": "DEBUG", + "displayLevel": "INFO" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": {} +} +``` + +### `admin.startCPUProfiler` + +Start profiling the CPU utilization of the node. To stop, call `admin.stopCPUProfiler`. On stop, +writes the profile to `cpu.profile`. + +**Signature:** + +```text +admin.startCPUProfiler() -> {} +``` + +**Example Call:** + +```bash +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"admin.startCPUProfiler", + "params" :{} +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": {} +} +``` + +### `admin.stopCPUProfiler` + +Stop the CPU profile that was previously started. + +**Signature:** + +```text +admin.stopCPUProfiler() -> {} +``` + +**Example Call:** + +```bash +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"admin.stopCPUProfiler" +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": {} +} +``` diff --git a/api/health/service.md b/api/health/service.md new file mode 100644 index 000000000000..bd14b0424280 --- /dev/null +++ b/api/health/service.md @@ -0,0 +1,214 @@ +--- +tags: [AvalancheGo APIs] +description: This page is an overview of the Health API associated with AvalancheGo. This API can be used for measuring node health. +sidebar_label: Health API +pagination_label: Health API +--- + +# Health API + +This API can be used for measuring node health. + +:::info + +This API set is for a specific node, it is unavailable on the [public server](/tooling/rpc-providers.md). + +::: + +## Filterable Health Checks + +The health checks that are run by the node are filterable. You can specify which health checks +you want to see by using `tags` filters. Returned results will only include health checks that +match the specified tags and global +health checks like `network`, `database` etc. +When filtered, the returned results will not show the full node health, +but only a subset of filtered health checks. +This means the node can be still unhealthy in unfiltered checks, even if the returned results show that +the node is healthy. +AvalancheGo supports filtering tags by subnetIDs. For more information check Filtering sections below. + +## GET Request + +To get an HTTP status code response that indicates the node’s health, make a `GET` request to +`/ext/health`. If the node is healthy, it will return a `200` status code. If you want more in-depth +information about a node’s health, use the JSON RPC methods. + +### Filtering + +To filter GET health checks, add a `tag` query parameter to the request. The `tag` parameter is a +string. +To filter health results by subnetID, use the +`subnetID` tag. For example, +to filter health results by subnetID `29uVeLPJB1eQJkzRemU8g8wZDw5uJRqpab5U2mX9euieVwiEbL`, +use the following query: + +```sh +curl --location --request GET 'http://localhost:9650/ext/health?tag=29uVeLPJB1eQJkzRemU8g8wZDw5uJRqpab5U2mX9euieVwiEbL' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"health.health", +}' +``` + +In this example returned results will contain global health checks and health checks that are +related to subnetID `29uVeLPJB1eQJkzRemU8g8wZDw5uJRqpab5U2mX9euieVwiEbL`. + +**Note:** This filtering can show healthy results even if the node is unhealthy in other Chains/Subnets. + +In order to filter results by multiple tags, use multiple `tag` query parameters. For example, to +filter health results by subnetID `29uVeLPJB1eQJkzRemU8g8wZDw5uJRqpab5U2mX9euieVwiEbL` and +`28nrH5T2BMvNrWecFcV3mfccjs6axM1TVyqe79MCv2Mhs8kxiY` use the following query: + +```sh +curl --location --request GET 'http://localhost:9650/ext/health?tag=29uVeLPJB1eQJkzRemU8g8wZDw5uJRqpab5U2mX9euieVwiEbL&tag=28nrH5T2BMvNrWecFcV3mfccjs6axM1TVyqe79MCv2Mhs8kxiY' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"health.health", +}' +``` + +Returned results will contain checks for both subnetIDs and global health checks. + +## JSON RPC Request + +### Format + +This API uses the `json 2.0` RPC format. For more information on making JSON RPC calls, see +[here](/reference/standards/guides/issuing-api-calls.md). + +### Endpoint + +```text +/ext/health +``` + +### Methods + +#### `health.health` + +The node runs a set of health checks every 30 seconds, including a health check for each chain. This +method returns the last set of health check results. + +**Signature:** + +```sh +health.health() -> { + checks: []{ + checkName: { + message: JSON, + error: JSON, + timestamp: string, + duration: int, + contiguousFailures: int, + timeOfFirstFailure: int + } + }, + healthy: bool +} +``` + +`healthy` is true if the node if all health checks are passing. + +`checks` is a list of health check responses. + +- A check response may include a `message` with additional context. +- A check response may include an `error` describing why the check failed. +- `timestamp` is the timestamp of the last health check. +- `duration` is the execution duration of the last health check, in nanoseconds. +- `contiguousFailures` is the number of times in a row this check failed. +- `timeOfFirstFailure` is the time this check first failed. + +More information on these measurements can be found in the documentation for the +[go-sundheit](https://github.com/AppsFlyer/go-sundheit) library. + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"health.health" +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/health +``` + +**Example Response:** + +In this example response, the C-Chain’s health check is failing. + +```json +{ + "jsonrpc": "2.0", + "result": { + "checks": { + "C": { + "message": null, + "error": { + "message": "example error message" + }, + "timestamp": "2020-10-14T14:04:20.57759662Z", + "duration": 465253, + "contiguousFailures": 50, + "timeOfFirstFailure": "2020-10-14T13:16:10.576435413Z" + }, + "P": { + "message": { + "percentConnected": 0.9967694992864075 + }, + "timestamp": "2020-10-14T14:04:08.668743851Z", + "duration": 433363830, + "contiguousFailures": 0, + "timeOfFirstFailure": null + }, + "X": { + "timestamp": "2020-10-14T14:04:20.3962705Z", + "duration": 1853, + "contiguousFailures": 0, + "timeOfFirstFailure": null + }, + "chains.default.bootstrapped": { + "timestamp": "2020-10-14T14:04:04.238623814Z", + "duration": 8075, + "contiguousFailures": 0, + "timeOfFirstFailure": null + }, + "network.validators.heartbeat": { + "message": { + "heartbeat": 1602684245 + }, + "timestamp": "2020-10-14T14:04:05.610007874Z", + "duration": 6124, + "contiguousFailures": 0, + "timeOfFirstFailure": null + } + }, + "healthy": false + }, + "id": 1 +} +``` + +### Filtering + +JSON RPC methods in Health API supports filtering by tags. In order to filter results use `tags` +params in the +request body. `tags` accepts a list of tags. Currently only `subnetID`s are supported as tags. +For example, to filter health results by subnetID `29uVeLPJB1eQJkzRemU8g8wZDw5uJRqpab5U2mX9euieVwiEbL` +use the following request: + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"health.health", + "params":{ + "tags": ["29uVeLPJB1eQJkzRemU8g8wZDw5uJRqpab5U2mX9euieVwiEbL"] + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/health +``` + +Returned results will contain checks for subnetID `29uVeLPJB1eQJkzRemU8g8wZDw5uJRqpab5U2mX9euieVwiEbL` +and global health checks. diff --git a/api/info/service.md b/api/info/service.md new file mode 100644 index 000000000000..d7e70e269dff --- /dev/null +++ b/api/info/service.md @@ -0,0 +1,689 @@ +--- +tags: [AvalancheGo APIs] +description: This page is an overview of the Info API associated with AvalancheGo. +sidebar_label: Info API +pagination_label: Info API +--- + +# Info API + +This API can be used to access basic information about the node. + +## Format + +This API uses the `json 2.0` RPC format. For more information on making JSON RPC calls, see +[here](/reference/standards/guides/issuing-api-calls.md). + +## Endpoint + +```text +/ext/info +``` + +## Methods + +### `info.acps` + +Returns peer preferences for Avalanche Community Proposals (ACPs) + +**Signature:** + +```go +info.acps() -> { + acps: map[uint32]{ + supportWeight: uint64 + supporters: set[string] + objectWeight: uint64 + objectors: set[string] + abstainWeight: uint64 + } +} +``` + +**Example Call:** + +```sh +curl -sX POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"info.acps", + "params" :{} +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "acps": { + "23": { + "supportWeight": "0", + "supporters": [], + "objectWeight": "0", + "objectors": [], + "abstainWeight": "161147778098286584" + }, + "24": { + "supportWeight": "0", + "supporters": [], + "objectWeight": "0", + "objectors": [], + "abstainWeight": "161147778098286584" + }, + "25": { + "supportWeight": "0", + "supporters": [], + "objectWeight": "0", + "objectors": [], + "abstainWeight": "161147778098286584" + }, + "30": { + "supportWeight": "0", + "supporters": [], + "objectWeight": "0", + "objectors": [], + "abstainWeight": "161147778098286584" + }, + "31": { + "supportWeight": "0", + "supporters": [], + "objectWeight": "0", + "objectors": [], + "abstainWeight": "161147778098286584" + }, + "41": { + "supportWeight": "0", + "supporters": [], + "objectWeight": "0", + "objectors": [], + "abstainWeight": "161147778098286584" + }, + "62": { + "supportWeight": "0", + "supporters": [], + "objectWeight": "0", + "objectors": [], + "abstainWeight": "161147778098286584" + } + } + }, + "id": 1 +} +``` + +### `info.isBootstrapped` + +Check whether a given chain is done bootstrapping + +**Signature:** + +```sh +info.isBootstrapped({chain: string}) -> {isBootstrapped: bool} +``` + +`chain` is the ID or alias of a chain. + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"info.isBootstrapped", + "params": { + "chain":"X" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "isBootstrapped": true + }, + "id": 1 +} +``` + +### `info.getBlockchainID` + +Given a blockchain’s alias, get its ID. (See [`admin.aliasChain`](/reference/avalanchego/admin-api.md#adminaliaschain).) + +**Signature:** + +```sh +info.getBlockchainID({alias:string}) -> {blockchainID:string} +``` + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"info.getBlockchainID", + "params": { + "alias":"X" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "blockchainID": "sV6o671RtkGBcno1FiaDbVcFv2sG5aVXMZYzKdP4VQAWmJQnM" + } +} +``` + +### `info.getNetworkID` + +Get the ID of the network this node is participating in. + +**Signature:** + +```sh +info.getNetworkID() -> {networkID:int} +``` + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"info.getNetworkID" +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "networkID": "2" + } +} +``` + +Network ID of 1 = Mainnet +Network ID of 5 = Fuji (testnet) + +### `info.getNetworkName` + +Get the name of the network this node is participating in. + +**Signature:** + +```sh +info.getNetworkName() -> {networkName:string} +``` + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"info.getNetworkName" +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "networkName": "local" + } +} +``` + +### `info.getNodeID` + +Get the ID, the BLS key, and the proof of possession(BLS signature) of this node. + +:::info +This endpoint set is for a specific node, it is unavailable on the [public server](/tooling/rpc-providers.md). +::: + +**Signature:** + +```sh +info.getNodeID() -> { + nodeID: string, + nodePOP: { + publicKey: string, + proofOfPossession: string + } +} +``` + +- `nodeID` Node ID is the unique identifier of the node that you set to act as a validator on the + Primary Network. +- `nodePOP` is this node's BLS key and proof of possession. Nodes must register a BLS key to act as + a validator on the Primary Network. Your node's POP is logged on startup and is accessible over this endpoint. + - `publicKey` is the 48 byte hex representation of the BLS key. + - `proofOfPossession` is the 96 byte hex representation of the BLS signature. + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"info.getNodeID" +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "nodeID": "NodeID-5mb46qkSBj81k9g9e4VFjGGSbaaSLFRzD", + "nodePOP": { + "publicKey": "0x8f95423f7142d00a48e1014a3de8d28907d420dc33b3052a6dee03a3f2941a393c2351e354704ca66a3fc29870282e15", + "proofOfPossession": "0x86a3ab4c45cfe31cae34c1d06f212434ac71b1be6cfe046c80c162e057614a94a5bc9f1ded1a7029deb0ba4ca7c9b71411e293438691be79c2dbf19d1ca7c3eadb9c756246fc5de5b7b89511c7d7302ae051d9e03d7991138299b5ed6a570a98" + } + }, + "id": 1 +} +``` + +### `info.getNodeIP` + +Get the IP of this node. + +:::info +This endpoint set is for a specific node, it is unavailable on the [public server](/tooling/rpc-providers.md). +::: + +**Signature:** + +```text +info.getNodeIP() -> {ip: string} +``` + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"info.getNodeIP" +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "ip": "192.168.1.1:9651" + }, + "id": 1 +} +``` + +### `info.getNodeVersion` + +Get the version of this node. + +**Signature:** + +```sh +info.getNodeVersion() -> { + version: string, + databaseVersion: string, + gitCommit: string, + vmVersions: map[string]string, + rpcProtocolVersion: string, +} +``` + +where: + +- `version` is this node's version +- `databaseVersion` is the version of the database this node is using +- `gitCommit` is the Git commit that this node was built from +- `vmVersions` is map where each key/value pair is the name of a VM, and the version of that VM this + node runs +- `rpcProtocolVersion` is the RPCChainVM protocol version + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"info.getNodeVersion" +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "version": "avalanche/1.9.1", + "databaseVersion": "v1.4.5", + "rpcProtocolVersion": "18", + "gitCommit": "79cd09ba728e1cecef40acd60702f0a2d41ea404", + "vmVersions": { + "avm": "v1.9.1", + "evm": "v0.11.1", + "platform": "v1.9.1" + } + }, + "id": 1 +} +``` + +### `info.getTxFee` + +Get the fees of the network. + +**Signature:** + +```sh +info.getTxFee() -> +{ + txFee: uint64, + createAssetTxFee: uint64, + createSubnetTxFee: uint64, + transformSubnetTxFee: uint64, + createBlockchainTxFee: uint64, + addPrimaryNetworkValidatorFee: uint64, + addPrimaryNetworkDelegatorFee: uint64, + addSubnetValidatorFee: uint64, + addSubnetDelegatorFee: uint64 +} +``` + +- `txFee` is the default fee for making transactions. +- `createAssetTxFee` is the fee for creating a new asset. +- `createSubnetTxFee` is the fee for creating a new Subnet. +- `transformSubnetTxFee` is the fee for converting a PoA Subnet into a PoS Subnet. +- `createBlockchainTxFee` is the fee for creating a new blockchain. +- `addPrimaryNetworkValidatorFee` is the fee for adding a new primary network validator. +- `addPrimaryNetworkDelegatorFee` is the fee for adding a new primary network delegator. +- `addSubnetValidatorFee` is the fee for adding a new Subnet validator. +- `addSubnetDelegatorFee` is the fee for adding a new Subnet delegator. + +All fees are denominated in nAVAX. + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"info.getTxFee" +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "txFee": "1000000", + "createAssetTxFee": "10000000", + "createSubnetTxFee": "1000000000", + "transformSubnetTxFee": "10000000000", + "createBlockchainTxFee": "1000000000", + "addPrimaryNetworkValidatorFee": "0", + "addPrimaryNetworkDelegatorFee": "0", + "addSubnetValidatorFee": "1000000", + "addSubnetDelegatorFee": "1000000" + } +} +``` + +### `info.getVMs` + +Get the virtual machines installed on this node. + +:::info +This endpoint set is for a specific node, it is unavailable on the [public server](/tooling/rpc-providers.md). +::: + +**Signature:** + +```sh +info.getVMs() -> { + vms: map[string][]string +} +``` + +**Example Call:** + +```bash +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"info.getVMs", + "params" :{} +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "vms": { + "jvYyfQTxGMJLuGWa55kdP2p2zSUYsQ5Raupu4TW34ZAUBAbtq": ["avm"], + "mgj786NP7uDwBCcq6YwThhaN8FLyybkCa4zBWTQbNgmK6k9A6": ["evm"], + "qd2U4HDWUvMrVUeTcCHp6xH3Qpnn1XbU5MDdnBoiifFqvgXwT": ["nftfx"], + "rWhpuQPF1kb72esV2momhMuTYGkEb1oL29pt2EBXWmSy4kxnT": ["platform"], + "rXJsCSEYXg2TehWxCEEGj6JU2PWKTkd6cBdNLjoe2SpsKD9cy": ["propertyfx"], + "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ": ["secp256k1fx"] + } + }, + "id": 1 +} +``` + +### `info.peers` + +Get a description of peer connections. + +**Signature:** + +```sh +info.peers({ + nodeIDs: string[] // optional +}) -> +{ + numPeers: int, + peers:[]{ + ip: string, + publicIP: string, + nodeID: string, + version: string, + lastSent: string, + lastReceived: string, + benched: string[], + observedUptime: int, + observedSubnetUptime: map[string]int, + } +} +``` + +- `nodeIDs` is an optional parameter to specify what NodeID's descriptions should be returned. If + this parameter is left empty, descriptions for all active connections will be returned. If the + node is not connected to a specified NodeID, it will be omitted from the response. +- `ip` is the remote IP of the peer. +- `publicIP` is the public IP of the peer. +- `nodeID` is the prefixed Node ID of the peer. +- `version` shows which version the peer runs on. +- `lastSent` is the timestamp of last message sent to the peer. +- `lastReceived` is the timestamp of last message received from the peer. +- `benched` shows chain IDs that the peer is being benched. +- `observedUptime` is this node's primary network uptime, observed by the peer. +- `observedSubnetUptime` is a map of Subnet IDs to this node's Subnet uptimes, observed by the peer. + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"info.peers", + "params": { + "nodeIDs": [] + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "numPeers": 3, + "peers": [ + { + "ip": "206.189.137.87:9651", + "publicIP": "206.189.137.87:9651", + "nodeID": "NodeID-8PYXX47kqLDe2wD4oPbvRRchcnSzMA4J4", + "version": "avalanche/1.9.4", + "lastSent": "2020-06-01T15:23:02Z", + "lastReceived": "2020-06-01T15:22:57Z", + "benched": [], + "observedUptime": "99", + "observedSubnetUptimes": {}, + "trackedSubnets": [], + "benched": [] + }, + { + "ip": "158.255.67.151:9651", + "publicIP": "158.255.67.151:9651", + "nodeID": "NodeID-C14fr1n8EYNKyDfYixJ3rxSAVqTY3a8BP", + "version": "avalanche/1.9.4", + "lastSent": "2020-06-01T15:23:02Z", + "lastReceived": "2020-06-01T15:22:34Z", + "benched": [], + "observedUptime": "75", + "observedSubnetUptimes": { + "29uVeLPJB1eQJkzRemU8g8wZDw5uJRqpab5U2mX9euieVwiEbL": "100" + }, + "trackedSubnets": [ + "29uVeLPJB1eQJkzRemU8g8wZDw5uJRqpab5U2mX9euieVwiEbL" + ], + "benched": [] + }, + { + "ip": "83.42.13.44:9651", + "publicIP": "83.42.13.44:9651", + "nodeID": "NodeID-LPbcSMGJ4yocxYxvS2kBJ6umWeeFbctYZ", + "version": "avalanche/1.9.3", + "lastSent": "2020-06-01T15:23:02Z", + "lastReceived": "2020-06-01T15:22:55Z", + "benched": [], + "observedUptime": "95", + "observedSubnetUptimes": {}, + "trackedSubnets": [], + "benched": [] + } + ] + } +} +``` + +### `info.uptime` + +Returns the network's observed uptime of this node. +This is the only reliable source of data for your node's uptime. +Other sources may be using data gathered with incomplete (limited) information. + +**Signature:** + +```sh +info.uptime({ + subnetID: string // optional +}) -> +{ + rewardingStakePercentage: float64, + weightedAveragePercentage: float64 +} +``` + +- `subnetID` is the Subnet to get the uptime of. If not provided, returns the uptime of the node on + the primary network. + +- `rewardingStakePercentage` is the percent of stake which thinks this node is above the uptime + requirement. +- `weightedAveragePercentage` is the stake-weighted average of all observed uptimes for this node. + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"info.uptime" +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "rewardingStakePercentage": "100.0000", + "weightedAveragePercentage": "99.0000" + } +} +``` + +#### **Example Subnet Call** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"info.uptime", + "params" :{ + "subnetID":"29uVeLPJB1eQJkzRemU8g8wZDw5uJRqpab5U2mX9euieVwiEbL" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info +``` + +#### **Example Subnet Response** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "rewardingStakePercentage": "74.0741", + "weightedAveragePercentage": "72.4074" + } +} +``` diff --git a/api/keystore/service.md b/api/keystore/service.md new file mode 100644 index 000000000000..76cc2ce69a56 --- /dev/null +++ b/api/keystore/service.md @@ -0,0 +1,290 @@ +--- +tags: [AvalancheGo APIs] +description: This page is an overview of the Keystore API associated with AvalancheGo. +sidebar_label: Keystore API +pagination_label: Keystore API +--- + +# Keystore API + +:::warning +Because the node operator has access to your plain-text password, you should only create a +keystore user on a node that you operate. If that node is breached, you could lose all your tokens. +Keystore APIs are not recommended for use on Mainnet. +::: + +Every node has a built-in keystore. Clients create users on the keystore, which act as identities to +be used when interacting with blockchains. A keystore exists at the node level, so if you create a +user on a node it exists _only_ on that node. However, users may be imported and exported using this +API. + +For validation and cross-chain transfer on the Mainnet, you should issue transactions through +[AvalancheJS](/tooling/avalanchejs-overview). That way control keys for your funds won't be stored on +the node, which significantly lowers the risk should a computer running a node be compromised. See +following docs for details: + +- Transfer AVAX Tokens Between Chains: + + - C-Chain: [export](https://github.com/ava-labs/avalanchejs/blob/master/examples/c-chain/export.ts) and + [import](https://github.com/ava-labs/avalanchejs/blob/master/examples/c-chain/import.ts) + - P-Chain: [export](https://github.com/ava-labs/avalanchejs/blob/master/examples/p-chain/export.ts) and + [import](https://github.com/ava-labs/avalanchejs/blob/master/examples/p-chain/import.ts) + - X-Chain: [export](https://github.com/ava-labs/avalanchejs/blob/master/examples/x-chain/export.ts) and + [import](https://github.com/ava-labs/avalanchejs/blob/master/examples/x-chain/import.ts) + +- [Add a Node to the Validator Set](/nodes/validate/add-a-validator) + +:::info + +This API set is for a specific node, it is unavailable on the [public server](/tooling/rpc-providers.md). + +::: + +## Format + +This API uses the `json 2.0` API format. For more information on making JSON RPC calls, see +[here](/reference/standards/guides/issuing-api-calls.md). + +## Endpoint + +```text +/ext/keystore +``` + +## Methods + +### keystore.createUser + +:::caution + +Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12). + +::: + +Create a new user with the specified username and password. + +**Signature:** + +```sh +keystore.createUser( + { + username:string, + password:string + } +) -> {} +``` + +- `username` and `password` can be at most 1024 characters. +- Your request will be rejected if `password` is too weak. `password` should be at least 8 + characters and contain upper and lower case letters as well as numbers and symbols. + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"keystore.createUser", + "params" :{ + "username":"myUsername", + "password":"myPassword" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/keystore +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": {} +} +``` + +### keystore.deleteUser + +:::caution + +Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12). + +::: + +Delete a user. + +**Signature:** + +```sh +keystore.deleteUser({username: string, password:string}) -> {} +``` + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"keystore.deleteUser", + "params" : { + "username":"myUsername", + "password":"myPassword" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/keystore +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": {} +} +``` + +### keystore.exportUser + +:::caution + +Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12). + +::: + +Export a user. The user can be imported to another node with +[`keystore.importUser`](/reference/avalanchego/keystore-api.md#keystoreimportuser). The user’s password +remains encrypted. + +**Signature:** + +```sh +keystore.exportUser( + { + username:string, + password:string, + encoding:string //optional + } +) -> { + user:string, + encoding:string +} +``` + +`encoding` specifies the format of the string encoding user data. Can only be `hex` when a value is +provided. + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"keystore.exportUser", + "params" :{ + "username":"myUsername", + "password":"myPassword" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/keystore +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "user": "7655a29df6fc2747b0874e1148b423b954a25fcdb1f170d0ec8eb196430f7001942ce55b02a83b1faf50a674b1e55bfc00000000", + "encoding": "hex" + } +} +``` + +### keystore.importUser + +:::caution + +Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12). + +::: + +Import a user. `password` must match the user’s password. `username` doesn’t have to match the +username `user` had when it was exported. + +**Signature:** + +```sh +keystore.importUser( + { + username:string, + password:string, + user:string, + encoding:string //optional + } +) -> {} +``` + +`encoding` specifies the format of the string encoding user data. Can only be `hex` when a value is +provided. + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"keystore.importUser", + "params" :{ + "username":"myUsername", + "password":"myPassword", + "user" :"0x7655a29df6fc2747b0874e1148b423b954a25fcdb1f170d0ec8eb196430f7001942ce55b02a83b1faf50a674b1e55bfc000000008cf2d869" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/keystore +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": {} +} +``` + +### keystore.listUsers + +:::caution + +Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12). + +::: + +List the users in this keystore. + +**Signature:** + +```sh +keystore.ListUsers() -> {users:[]string} +``` + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"keystore.listUsers" +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/keystore +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "users": ["myUsername"] + } +} +``` diff --git a/api/metrics/service.md b/api/metrics/service.md new file mode 100644 index 000000000000..08b211d33dde --- /dev/null +++ b/api/metrics/service.md @@ -0,0 +1,40 @@ +--- +tags: [AvalancheGo APIs] +description: This page is an overview of the Metrics API associated with AvalancheGo. +sidebar_label: Metrics API +pagination_label: Metrics API +--- + +# Metrics API + +The API allows clients to get statistics about a node’s health and performance. + +:::info + +This API set is for a specific node, it is unavailable on the [public server](/tooling/rpc-providers.md). + +::: + +## Endpoint + +```text +/ext/metrics +``` + +## Usage + +To get the node metrics: + +```sh +curl -X POST 127.0.0.1:9650/ext/metrics +``` + +## Format + +This API produces Prometheus compatible metrics. See +[here](https://github.com/prometheus/docs/blob/master/content/docs/instrumenting/exposition_formats.md) +for information on Prometheus’ formatting. + +[Here](/nodes/maintain/setting-up-node-monitoring) is a tutorial that +shows how to set up Prometheus and Grafana to monitor AvalancheGo node using the +Metrics API. diff --git a/config/config.md b/config/config.md new file mode 100644 index 000000000000..0ceb6ab362cd --- /dev/null +++ b/config/config.md @@ -0,0 +1,1418 @@ +--- +tags: [Nodes] +description: This document lists all available configuration and flags for AvalancheGo. +sidebar_label: AvalancheGo Configs + Flags +pagination_label: AvalancheGo Configs and Flags +sidebar_position: 0 +--- + +# AvalancheGo Configs and Flags + + + +You can specify the configuration of a node with the arguments below. + +## Data Directory + +#### `--data-dir` (string) + +Sets the base data directory where default sub-directories will be placed unless otherwise specified. +Defaults to `$HOME/.avalanchego`. + +## Config File + +#### `--config-file` (string) + +Path to a JSON file that specifies this node's configuration. Command line +arguments will override arguments set in the config file. This flag is ignored +if `--config-file-content` is specified. + +Example JSON config file: + +```json +{ + "log-level": "debug" +} +``` + +:::tip +[Install Script](/nodes/run/with-installer/installing-avalanchego.md) creates the +node config file at `~/.avalanchego/configs/node.json`. No default file is +created if [AvalancheGo is built from source](/nodes/run/node-manually.md), you +would need to create it manually if needed. +::: + +#### `--config-file-content` (string) + +As an alternative to `--config-file`, it allows specifying base64 encoded config +content. + +#### `--config-file-content-type` (string) + +Specifies the format of the base64 encoded config content. JSON, TOML, YAML are +among currently supported file format (see +[here](https://github.com/spf13/viper#reading-config-files) for full list). Defaults to `JSON`. + +## Avalanche Community Proposals + +#### `--acp-support` (array of integers) + +The `--acp-support` flag allows an AvalancheGo node to indicate support for a +set of [Avalanche Community Proposals](https://github.com/avalanche-foundation/ACPs). + +#### `--acp-object` (array of integers) + +The `--acp-object` flag allows an AvalancheGo node to indicate objection for a +set of [Avalanche Community Proposals](https://github.com/avalanche-foundation/ACPs). + +## APIs + +#### `--api-admin-enabled` (boolean) + +If set to `true`, this node will expose the Admin API. Defaults to `false`. +See [here](/reference/avalanchego/admin-api.md) for more information. + +#### `--api-health-enabled` (boolean) + +If set to `false`, this node will not expose the Health API. Defaults to `true`. See +[here](/reference/avalanchego/health-api.md) for more information. + +#### `--index-enabled` (boolean) + +If set to `true`, this node will enable the indexer and the Index API will be +available. Defaults to `false`. See +[here](/reference/avalanchego/index-api.md) for more information. + +#### `--api-info-enabled` (boolean) + +If set to `false`, this node will not expose the Info API. Defaults to `true`. See +[here](/reference/avalanchego/info-api.md) for more information. + +#### `--api-keystore-enabled` (boolean) + +If set to `true`, this node will expose the Keystore API. Defaults to `false`. +See [here](/reference/avalanchego/keystore-api.md) for more information. + +#### `--api-metrics-enabled` (boolean) + +If set to `false`, this node will not expose the Metrics API. Defaults to +`true`. See [here](/reference/avalanchego/metrics-api.md) for more information. + +#### `--http-shutdown-wait` (duration) + +Duration to wait after receiving SIGTERM or SIGINT before initiating shutdown. +The `/health` endpoint will return unhealthy during this duration (if the Health +API is enabled.) Defaults to `0s`. + +#### `--http-shutdown-timeout` (duration) + +Maximum duration to wait for existing connections to complete during node +shutdown. Defaults to `10s`. + +## Bootstrapping + +#### `--bootstrap-beacon-connection-timeout` (duration) + +Timeout when attempting to connect to bootstrapping beacons. Defaults to `1m`. + +#### `--bootstrap-ids` (string) + +Bootstrap IDs is a comma-separated list of validator IDs. These IDs will be used +to authenticate bootstrapping peers. An example setting of this field would be +`--bootstrap-ids="NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg,NodeID-MFrZFVCXPv5iCn6M9K6XduxGTYp891xXZ"`. +The number of given IDs here must be same with number of given +`--bootstrap-ips`. The default value depends on the network ID. + +#### `--bootstrap-ips` (string) + +Bootstrap IPs is a comma-separated list of IP:port pairs. These IP Addresses +will be used to bootstrap the current Avalanche state. An example setting of +this field would be `--bootstrap-ips="127.0.0.1:12345,1.2.3.4:5678"`. The number +of given IPs here must be same with number of given `--bootstrap-ids`. The +default value depends on the network ID. + +#### `--bootstrap-retry-enabled` (boolean) + +If set to `false`, will not retry bootstrapping if it fails. Defaults to `true`. + +#### `--bootstrap-retry-warn-frequency` (uint) + +Specifies how many times bootstrap should be retried before warning the operator. Defaults to `50`. + +#### `--bootstrap-ancestors-max-containers-sent` (uint) + +Max number of containers in an `Ancestors` message sent by this node. Defaults to `2000`. + +#### `--bootstrap-ancestors-max-containers-received` (unit) + +This node reads at most this many containers from an incoming `Ancestors` message. Defaults to `2000`. + +#### `--bootstrap-max-time-get-ancestors` (duration) + +Max Time to spend fetching a container and its ancestors when responding to a GetAncestors message. +Defaults to `50ms`. + +## State Syncing + +#### `--state-sync-ids` (string) + +State sync IDs is a comma-separated list of validator IDs. The specified +validators will be contacted to get and authenticate the starting point (state +summary) for state sync. An example setting of this field would be +`--state-sync-ids="NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg,NodeID-MFrZFVCXPv5iCn6M9K6XduxGTYp891xXZ"`. +The number of given IDs here must be same with number of given +`--state-sync-ips`. The default value is empty, which results in all validators +being sampled. + +#### `--state-sync-ips` (string) + +State sync IPs is a comma-separated list of IP:port pairs. These IP Addresses +will be contacted to get and authenticate the starting point (state summary) for +state sync. An example setting of this field would be +`--state-sync-ips="127.0.0.1:12345,1.2.3.4:5678"`. The number of given IPs here +must be the same with the number of given `--state-sync-ids`. + +## Partial Sync Primary Network + +#### `--partial-sync-primary-network` (string) + +Partial sync enables non-validators to optionally sync only the P-chain on the primary network. + +## Chain Configs + +Some blockchains allow the node operator to provide custom configurations for +individual blockchains. These custom configurations are broken down into two +categories: network upgrades and optional chain configurations. AvalancheGo +reads in these configurations from the chain configuration directory and passes +them into the VM on initialization. + +#### `--chain-config-dir` (string) + +Specifies the directory that contains chain configs, as described +[here](/nodes/configure/chain-configs/chain-config-flags.md). Defaults to `$HOME/.avalanchego/configs/chains`. +If this flag is not provided and the default directory does not exist, +AvalancheGo will not exit since custom configs are optional. However, if the +flag is set, the specified folder must exist, or AvalancheGo will exit with an +error. This flag is ignored if `--chain-config-content` is specified. + +:::note +Please replace `chain-config-dir` and `blockchainID` with their actual values. +::: + +Network upgrades are passed in from the location: +`chain-config-dir`/`blockchainID`/`upgrade.*`. +Upgrade files are typically json encoded and therefore named `upgrade.json`. +However, the format of the file is VM dependent. +After a blockchain has activated a network upgrade, the same upgrade +configuration must always be passed in to ensure that the network upgrades +activate at the correct time. + +The chain configs are passed in from the location +`chain-config-dir`/`blockchainID`/`config.*`. +Upgrade files are typically json encoded and therefore named `upgrade.json`. +However, the format of the file is VM dependent. +This configuration is used by the VM to handle optional configuration flags such +as enabling/disabling APIs, updating log level, etc. +The chain configuration is intended to provide optional configuration parameters +and the VM will use default values if nothing is passed in. + +Full reference for all configuration options for some standard chains can be +found in a separate [chain config flags](/nodes/configure/chain-configs/chain-config-flags.md) document. + +Full reference for `subnet-evm` upgrade configuration can be found in a separate +[Customize a Subnet](/build/subnet/upgrade/customize-a-subnet.md) document. + +#### `--chain-config-content` (string) + +As an alternative to `--chain-config-dir`, chains custom configurations can be +loaded altogether from command line via `--chain-config-content` flag. Content +must be base64 encoded. + +Example: + +```bash +cchainconfig="$(echo -n '{"log-level":"trace"}' | base64)" +chainconfig="$(echo -n "{\"C\":{\"Config\":\"${cchainconfig}\",\"Upgrade\":null}}" | base64)" +avalanchego --chain-config-content "${chainconfig}" +``` + +#### `--chain-aliases-file` (string) + +Path to JSON file that defines aliases for Blockchain IDs. Defaults to +`~/.avalanchego/configs/chains/aliases.json`. This flag is ignored if +`--chain-aliases-file-content` is specified. Example content: + +```json +{ + "q2aTwKuyzgs8pynF7UXBZCU7DejbZbZ6EUyHr3JQzYgwNPUPi": ["DFK"] +} +``` + +The above example aliases the Blockchain whose ID is +`"q2aTwKuyzgs8pynF7UXBZCU7DejbZbZ6EUyHr3JQzYgwNPUPi"` to `"DFK"`. Chain +aliases are added after adding primary network aliases and before any changes to +the aliases via the admin API. This means that the first alias included for a +Blockchain on a Subnet will be treated as the `"Primary Alias"` instead of the +full blockchainID. The Primary Alias is used in all metrics and logs. + +#### `--chain-aliases-file-content` (string) + +As an alternative to `--chain-aliases-file`, it allows specifying base64 encoded +aliases for Blockchains. + +#### `--chain-data-dir` (string) + +Chain specific data directory. Defaults to `$HOME/.avalanchego/chainData`. + +## Database + +##### `--db-dir` (string, file path) + +Specifies the directory to which the database is persisted. Defaults to `"$HOME/.avalanchego/db"`. + +##### `--db-type` (string) + +Specifies the type of database to use. Must be one of `LevelDB` or `memdb`. +`memdb` is an in-memory, non-persisted database. + +:::note + +`memdb` stores everything in memory. So if you have a 900 GiB LevelDB instance, then using `memdb` +you’d need 900 GiB of RAM. +`memdb` is useful for fast one-off testing, not for running an actual node (on Fuji or Mainnet). +Also note that `memdb` doesn’t persist after restart. So any time you restart the node it would +start syncing from scratch. + +::: + +### Database Config + +#### `--db-config-file` (string) + +Path to the database config file. Ignored if `--config-file-content` is specified. + +#### `--db-config-file-content` (string) + +As an alternative to `--db-config-file`, it allows specifying base64 encoded database config content. + +#### LevelDB Config + +A LevelDB config file must be JSON and may have these keys. +Any keys not given will receive the default value. + +```go +{ + // BlockCacheCapacity defines the capacity of the 'sorted table' block caching. + // Use -1 for zero. + // + // The default value is 12MiB. + "blockCacheCapacity": int + + // BlockSize is the minimum uncompressed size in bytes of each 'sorted table' + // block. + // + // The default value is 4KiB. + "blockSize": int + + // CompactionExpandLimitFactor limits compaction size after expanded. + // This will be multiplied by table size limit at compaction target level. + // + // The default value is 25. + "compactionExpandLimitFactor": int + + // CompactionGPOverlapsFactor limits overlaps in grandparent (Level + 2) + // that a single 'sorted table' generates. This will be multiplied by + // table size limit at grandparent level. + // + // The default value is 10. + "compactionGPOverlapsFactor": int + + // CompactionL0Trigger defines number of 'sorted table' at level-0 that will + // trigger compaction. + // + // The default value is 4. + "compactionL0Trigger": int + + // CompactionSourceLimitFactor limits compaction source size. This doesn't apply to + // level-0. + // This will be multiplied by table size limit at compaction target level. + // + // The default value is 1. + "compactionSourceLimitFactor": int + + // CompactionTableSize limits size of 'sorted table' that compaction generates. + // The limits for each level will be calculated as: + // CompactionTableSize * (CompactionTableSizeMultiplier ^ Level) + // The multiplier for each level can also fine-tuned using CompactionTableSizeMultiplierPerLevel. + // + // The default value is 2MiB. + "compactionTableSize": int + + // CompactionTableSizeMultiplier defines multiplier for CompactionTableSize. + // + // The default value is 1. + "compactionTableSizeMultiplier": float + + // CompactionTableSizeMultiplierPerLevel defines per-level multiplier for + // CompactionTableSize. + // Use zero to skip a level. + // + // The default value is nil. + "compactionTableSizeMultiplierPerLevel": []float + + // CompactionTotalSize limits total size of 'sorted table' for each level. + // The limits for each level will be calculated as: + // CompactionTotalSize * (CompactionTotalSizeMultiplier ^ Level) + // The multiplier for each level can also fine-tuned using + // CompactionTotalSizeMultiplierPerLevel. + // + // The default value is 10MiB. + "compactionTotalSize": int + + // CompactionTotalSizeMultiplier defines multiplier for CompactionTotalSize. + // + // The default value is 10. + "compactionTotalSizeMultiplier": float + + // DisableSeeksCompaction allows disabling 'seeks triggered compaction'. + // The purpose of 'seeks triggered compaction' is to optimize database so + // that 'level seeks' can be minimized, however this might generate many + // small compaction which may not preferable. + // + // The default is true. + "disableSeeksCompaction": bool + + // OpenFilesCacheCapacity defines the capacity of the open files caching. + // Use -1 for zero, this has same effect as specifying NoCacher to OpenFilesCacher. + // + // The default value is 1024. + "openFilesCacheCapacity": int + + // WriteBuffer defines maximum size of a 'memdb' before flushed to + // 'sorted table'. 'memdb' is an in-memory DB backed by an on-disk + // unsorted journal. + // + // LevelDB may held up to two 'memdb' at the same time. + // + // The default value is 6MiB. + "writeBuffer": int + + // FilterBitsPerKey is the number of bits to add to the bloom filter per + // key. + // + // The default value is 10. + "filterBitsPerKey": int + + // MaxManifestFileSize is the maximum size limit of the MANIFEST-****** file. + // When the MANIFEST-****** file grows beyond this size, LevelDB will create + // a new MANIFEST file. + // + // The default value is infinity. + "maxManifestFileSize": int + + // MetricUpdateFrequency is the frequency to poll LevelDB metrics in + // nanoseconds. + // If <= 0, LevelDB metrics aren't polled. + // + // The default value is 10s. + "metricUpdateFrequency": int +} +``` + +## Genesis + +#### `--genesis-file` (string) + +Path to a JSON file containing the genesis data to use. Ignored when running +standard networks (Mainnet, Fuji Testnet), or when `--genesis-content` is +specified. If not given, uses default genesis data. + +These are the main properties in the JSON file: + +- `networkID`: A unique identifier for the blockchain, must be a number in the range [0, 2^32). +- `allocations`: The list of initial addresses, their initial balances and the unlock schedule for each. +- `startTime`: The time of the beginning of the blockchain, it must be a Unix + timestamp and it can't be a time in the future. +- `initialStakeDuration`: The stake duration, in seconds, of the validators that exist at network genesis. +- `initialStakeDurationOffset`: The offset, in seconds, between the start times + of the validators that exist at genesis. +- `initialStakedFunds`: A list of addresses that own the funds staked at genesis + (each address must be present in `allocations` as well) +- `initialStakers`: The validators that exist at genesis. Each element contains + the `rewardAddress`, NodeID and the `delegationFee` of the validator. +- `cChainGenesis`: The genesis info to be passed to the C-Chain. +- `message`: A message to include in the genesis. Not required. + +For an example of a JSON representation of genesis data, see [genesis_local.json](https://github.com/ava-labs/avalanchego/blob/master/genesis/genesis_local.json). + +#### `--genesis-file-content` (string) + +As an alternative to `--genesis-file`, it allows specifying base64 encoded genesis data to use. + +## HTTP Server + +#### `--http-host` (string) + +The address that HTTP APIs listen on. Defaults to `127.0.0.1`. This means that +by default, your node can only handle API calls made from the same machine. To +allow API calls from other machines, use `--http-host=`. You can also enter +domain names as parameter. + +#### `--http-port` (int) + +Each node runs an HTTP server that provides the APIs for interacting with the +node and the Avalanche network. This argument specifies the port that the HTTP +server will listen on. The default value is `9650`. + +#### `--http-tls-cert-file` (string, file path) + +This argument specifies the location of the TLS certificate used by the node for +the HTTPS server. This must be specified when `--http-tls-enabled=true`. There +is no default value. This flag is ignored if `--http-tls-cert-file-content` is +specified. + +#### `--http-tls-cert-file-content` (string) + +As an alternative to `--http-tls-cert-file`, it allows specifying base64 encoded +content of the TLS certificate used by the node for the HTTPS server. Note that +full certificate content, with the leading and trailing header, must be base64 +encoded. This must be specified when `--http-tls-enabled=true`. + +#### `--http-tls-enabled` (boolean) + +If set to `true`, this flag will attempt to upgrade the server to use HTTPS. Defaults to `false`. + +#### `--http-tls-key-file` (string, file path) + +This argument specifies the location of the TLS private key used by the node for +the HTTPS server. This must be specified when `--http-tls-enabled=true`. There +is no default value. This flag is ignored if `--http-tls-key-file-content` is +specified. + +#### `--http-tls-key-file-content` (string) + +As an alternative to `--http-tls-key-file`, it allows specifying base64 encoded +content of the TLS private key used by the node for the HTTPS server. Note that +full private key content, with the leading and trailing header, must be base64 +encoded. This must be specified when `--http-tls-enabled=true`. + +#### `--http-read-timeout` (string) + +Maximum duration for reading the entire request, including the body. A zero or +negative value means there will be no timeout. + +#### `--http-read-header-timeout` (string) + +Maximum duration to read request headers. The connection’s read deadline is +reset after reading the headers. If `--http-read-header-timeout` is zero, the +value of `--http-read-timeout` is used. If both are zero, there is no timeout. + +#### `--http-write-timeout` (string) + +Maximum duration before timing out writes of the response. It is reset whenever +a new request’s header is read. A zero or negative value means there will be no +timeout. + +#### `--http-idle-timeout` (string) + +Maximum duration to wait for the next request when keep-alives are enabled. If +`--http-idle-timeout` is zero, the value of `--http-read-timeout` is used. If both are zero, +there is no timeout. + +#### `--http-allowed-origins` (string) + +Origins to allow on the HTTP port. Defaults to `*` which allows all origins. Example: +`"https://*.avax.network https://*.avax-test.network"` + +#### `--http-allowed-hosts` (string) + +List of acceptable host names in API requests. Provide the wildcard (`'*'`) to accept +requests from all hosts. API requests where the `Host` field is empty or an IP address +will always be accepted. An API call whose HTTP `Host` field isn't acceptable will +receive a 403 error code. Defaults to `localhost`. + +## File Descriptor Limit + +#### `--fd-limit` (int) + +Attempts to raise the process file descriptor limit to at least this value and +error if the value is above the system max. Linux default `32768`. + +## Logging + +#### `--log-level` (string, `{verbo, debug, trace, info, warn, error, fatal, off}`) + +The log level determines which events to log. There are 8 different levels, in +order from highest priority to lowest. + +- `off`: No logs have this level of logging. Turns off logging. +- `fatal`: Fatal errors that are not recoverable. +- `error`: Errors that the node encounters, these errors were able to be recovered. +- `warn`: A Warning that might be indicative of a spurious byzantine node, or potential future error. +- `info`: Useful descriptions of node status updates. +- `trace`: Traces container (block, vertex, transaction) job results. Useful for + tracing container IDs and their outcomes. +- `debug`: Debug logging is useful when attempting to understand possible bugs + in the code. More information that would be typically desired for normal usage + will be displayed. +- `verbo`: Tracks extensive amounts of information the node is processing. This + includes message contents and binary dumps of data for extremely low level + protocol analysis. + +When specifying a log level note that all logs with the specified priority or +higher will be tracked. Defaults to `info`. + +#### `--log-display-level` (string, `{verbo, debug, trace, info, warn, error, fatal, off}`) + +The log level determines which events to display to stdout. If left blank, +will default to the value provided to `--log-level`. + +#### `--log-format` (string, `{auto, plain, colors, json}`) + +The structure of log format. Defaults to `auto` which formats terminal-like +logs, when the output is a terminal. Otherwise, should be one of `{auto, plain, colors, json}` + +#### `--log-dir` (string, file path) + +Specifies the directory in which system logs are kept. Defaults to `"$HOME/.avalanchego/logs"`. +If you are running the node as a system service (ex. using the installer script) logs will also be +stored in `$HOME/var/log/syslog`. + +#### `--log-disable-display-plugin-logs` (boolean) + +Disables displaying plugin logs in stdout. Defaults to `false`. + +#### `--log-rotater-max-size` (uint) + +The maximum file size in megabytes of the log file before it gets rotated. Defaults to `8`. + +#### `--log-rotater-max-files` (uint) + +The maximum number of old log files to retain. 0 means retain all old log files. Defaults to `7`. + +#### `--log-rotater-max-age` (uint) + +The maximum number of days to retain old log files based on the timestamp +encoded in their filename. 0 means retain all old log files. Defaults to `0`. + +#### `--log-rotater-compress-enabled` (boolean) + +Enables the compression of rotated log files through gzip. Defaults to `false`. + +## Network ID + +#### `--network-id` (string) + +The identity of the network the node should connect to. Can be one of: + +- `--network-id=mainnet` -> Connect to Mainnet (default). +- `--network-id=fuji` -> Connect to the Fuji test-network. +- `--network-id=testnet` -> Connect to the current test-network. (Right now, this is Fuji.) +- `--network-id=local` -> Connect to a local test-network. +- `--network-id=network-{id}` -> Connect to the network with the given ID. + `id` must be in the range `[0, 2^32)`. + +## OpenTelemetry + +AvalancheGo supports collecting and exporting [OpenTelemetry](https://opentelemetry.io/) traces. +This might be useful for debugging, performance analysis, or monitoring. + +#### `--tracing-enabled` (boolean) + +If true, enable OpenTelemetry tracing. Defaults to `false`. + +#### `--tracing-endpoint` (string) + +The endpoint to export trace data to. Defaults to `localhost:4317`. + +#### `--tracing-insecure` (string) + +If true, don't use TLS when exporting trace data. Defaults to `true`. + +#### `--tracing-sample-rate` (float) + +The fraction of traces to sample. If >= 1, always sample. If `<= 0`, never sample. +Defaults to `0.1`. + +#### `--tracing-exporter-type`(string) + +Type of exporter to use for tracing. Options are [`grpc`,`http`]. Defaults to `grpc`. + +## Public IP + +Validators must know one of their public facing IP addresses so they can enable +other nodes to connect to them. + +By default, the node will attempt to perform NAT traversal to get the node's IP +according to its router. + +#### `--public-ip` (string) + +If this argument is provided, the node assume this is its public IP. + +:::tip +When running a local network it may be easiest to set this value to `127.0.0.1`. +::: + +#### `--public-ip-resolution-frequency` (duration) + +Frequency at which this node resolves/updates its public IP and renew NAT +mappings, if applicable. Default to 5 minutes. + +#### `--public-ip-resolution-service` (string) + +When provided, the node will use that service to periodically resolve/update its +public IP. Only acceptable values are `ifconfigCo`, `opendns` or `ifconfigMe`. + +## Staking + +#### `--staking-port` (int) + +The port through which the network peers will connect to this node externally. +Having this port accessible from the internet is required for correct node +operation. Defaults to `9651`. + +#### `--sybil-protection-enabled` (boolean) + +Avalanche uses Proof of Stake (PoS) as sybil resistance to make it prohibitively +expensive to attack the network. If false, sybil resistance is disabled and all +peers will be sampled during consensus. Defaults to `true`. Note that this can +not be disabled on public networks (`Fuji` and `Mainnet`). + +Setting this flag to `false` **does not** mean "this node is not a validator." +It means that this node will sample all nodes, not just validators. +**You should not set this flag to false unless you understand what you are doing.** + +#### `--sybil-protection-disabled-weight` (uint) + +Weight to provide to each peer when staking is disabled. Defaults to `100`. + +#### `--staking-tls-cert-file` (string, file path) + +Avalanche uses two-way authenticated TLS connections to securely connect nodes. +This argument specifies the location of the TLS certificate used by the node. By +default, the node expects the TLS certificate to be at +`$HOME/.avalanchego/staking/staker.crt`. This flag is ignored if +`--staking-tls-cert-file-content` is specified. + +#### `--staking-tls-cert-file-content` (string) + +As an alternative to `--staking-tls-cert-file`, it allows specifying base64 +encoded content of the TLS certificate used by the node. Note that full +certificate content, with the leading and trailing header, must be base64 +encoded. + +#### `--staking-tls-key-file` (string, file path) + +Avalanche uses two-way authenticated TLS connections to securely connect nodes. +This argument specifies the location of the TLS private key used by the node. By +default, the node expects the TLS private key to be at +`$HOME/.avalanchego/staking/staker.key`. This flag is ignored if +`--staking-tls-key-file-content` is specified. + +#### `--staking-tls-key-file-content` (string) + +As an alternative to `--staking-tls-key-file`, it allows specifying base64 +encoded content of the TLS private key used by the node. Note that full private +key content, with the leading and trailing header, must be base64 encoded. + +## Subnets + +### Subnet Tracking + +#### `--track-subnets` (string) + +Comma separated list of Subnet IDs that this node would track if added to. +Defaults to empty (will only validate the Primary Network). + +### Subnet Configs + +It is possible to provide parameters for Subnets. Parameters here apply to all +chains in the specified Subnets. Parameters must be specified with a +`{subnetID}.json` config file under `--subnet-config-dir`. AvalancheGo loads +configs for Subnets specified in +`--track-subnets` parameter. + +Full reference for all configuration options for a Subnet can be found in a +separate [Subnet Configs](./subnet-configs) document. + +#### `--subnet-config-dir` (`string`) + +Specifies the directory that contains Subnet configs, as described above. +Defaults to `$HOME/.avalanchego/configs/subnets`. If the flag is set explicitly, +the specified folder must exist, or AvalancheGo will exit with an error. This +flag is ignored if `--subnet-config-content` is specified. + +Example: Let's say we have a Subnet with ID +`p4jUwqZsA2LuSftroCd3zb4ytH8W99oXKuKVZdsty7eQ3rXD6`. We can create a config file +under the default `subnet-config-dir` at +`$HOME/.avalanchego/configs/subnets/p4jUwqZsA2LuSftroCd3zb4ytH8W99oXKuKVZdsty7eQ3rXD6.json`. +An example config file is: + +```json +{ + "validatorOnly": false, + "consensusParameters": { + "k": 25, + "alpha": 18 + } +} +``` + +:::tip +By default, none of these directories and/or files exist. You would need to create them manually if needed. +::: + +#### `--subnet-config-content` (string) + +As an alternative to `--subnet-config-dir`, it allows specifying base64 encoded parameters for a Subnet. + +## Version + +#### `--version` (boolean) + +If this is `true`, print the version and quit. Defaults to `false`. + +## Advanced Options + +The following options may affect the correctness of a node. Only power users should change these. + +### Gossiping + +#### `--consensus-accepted-frontier-gossip-validator-size` (uint) + +Number of validators to gossip to when gossiping accepted frontier. Defaults to `0`. + +#### `--consensus-accepted-frontier-gossip-non-validator-size` (uint) + +Number of non-validators to gossip to when gossiping accepted frontier. Defaults to `0`. + +#### `--consensus-accepted-frontier-gossip-peer-size` (uint) + +Number of peers to gossip to when gossiping accepted frontier. Defaults to `15`. + +#### `--consensus-accepted-frontier-gossip-frequency` (duration) + +Time between gossiping accepted frontiers. Defaults to `10s`. + +#### `--consensus-on-accept-gossip-validator-size` (uint) + +Number of validators to gossip to each accepted container to. Defaults to `0`. + +#### `--consensus-on-accept-gossip-non-validator-size` (uint) + +Number of non-validators to gossip to each accepted container to. Defaults to `0`. + +#### `--consensus-on-accept-gossip-peer-size` (uint) + +Number of peers to gossip to each accepted container to. Defaults to `10`. + +### Benchlist + +#### `--benchlist-duration` (duration) + +Maximum amount of time a peer is benchlisted after surpassing +`--benchlist-fail-threshold`. Defaults to `15m`. + +#### `--benchlist-fail-threshold` (int) + +Number of consecutive failed queries to a node before benching it (assuming all +queries to it will fail). Defaults to `10`. + +#### `--benchlist-min-failing-duration` (duration) + +Minimum amount of time queries to a peer must be failing before the peer is benched. Defaults to `150s`. + +### Consensus Parameters + +:::note +Some of these parameters can only be set on a local or private network, not on Fuji Testnet or Mainnet +::: + +#### `--consensus-shutdown-timeout` (duration) + +Timeout before killing an unresponsive chain. Defaults to `5s`. + +#### `--create-asset-tx-fee` (int) + +Transaction fee, in nAVAX, for transactions that create new assets. Defaults to +`10000000` nAVAX (.01 AVAX) per transaction. This can only be changed on a local +network. + +#### `--create-subnet-tx-fee` (int) + +Transaction fee, in nAVAX, for transactions that create new Subnets. Defaults to +`1000000000` nAVAX (1 AVAX) per transaction. This can only be changed on a local +network. + +#### `--create-blockchain-tx-fee` (int) + +Transaction fee, in nAVAX, for transactions that create new blockchains. +Defaults to `1000000000` nAVAX (1 AVAX) per transaction. This can only be +changed on a local network. + +#### `--transform-subnet-tx-fee` (int) + +Transaction fee, in nAVAX, for transactions that transform Subnets. Defaults to +`1000000000` nAVAX (1 AVAX) per transaction. This can only be changed on a local network. + +#### `--add-primary-network-validator-fee` (int) + +Transaction fee, in nAVAX, for transactions that add new primary network validators. Defaults to 0. +This can only be changed on a local network. + +#### `--add-primary-network-delegator-fee` (int) + +Transaction fee, in nAVAX, for transactions that add new primary network delegators. Defaults to 0. +This can only be changed on a local network. + +#### `--add-subnet-validator-fee` (int) + +Transaction fee, in nAVAX, for transactions that add new Subnet validators. +Defaults to `10000000` nAVAX (.01 AVAX). + +#### `--add-subnet-delegator-fee` (int) + +Transaction fee, in nAVAX, for transactions that add new Subnet delegators. +Defaults to `10000000` nAVAX (.01 AVAX). + +#### `--min-delegator-stake` (int) + +The minimum stake, in nAVAX, that can be delegated to a validator of the Primary Network. + +Defaults to `25000000000` (25 AVAX) on Mainnet. Defaults to `5000000` (.005 +AVAX) on Test Net. This can only be changed on a local network. + +#### `--min-delegation-fee` (int) + +The minimum delegation fee that can be charged for delegation on the Primary +Network, multiplied by `10,000` . Must be in the range `[0, 1000000]`. Defaults +to `20000` (2%) on Mainnet. This can only be changed on a local network. + +#### `--min-stake-duration` (duration) + +Minimum staking duration. The Default on Mainnet is `336h` (two weeks). This can only be changed on +a local network. This applies to both delegation and validation periods. + +#### `--min-validator-stake` (int) + +The minimum stake, in nAVAX, required to validate the Primary Network. This can +only be changed on a local network. + +Defaults to `2000000000000` (2,000 AVAX) on Mainnet. Defaults to `5000000` (.005 AVAX) on Test Net. + +#### `--max-stake-duration` (duration) + +The maximum staking duration, in hours. Defaults to `8760h` (365 days) on +Mainnet. This can only be changed on a local network. + +#### `--max-validator-stake` (int) + +The maximum stake, in nAVAX, that can be placed on a validator on the primary +network. Defaults to `3000000000000000` (3,000,000 AVAX) on Mainnet. This +includes stake provided by both the validator and by delegators to the +validator. This can only be changed on a local network. + +#### `--stake-minting-period` (duration) + +Consumption period of the staking function, in hours. The Default on Mainnet is +`8760h` (365 days). This can only be changed on a local network. + +#### `--stake-max-consumption-rate` (uint) + +The maximum percentage of the consumption rate for the remaining token supply in +the minting period, which is 1 year on Mainnet. Defaults to `120,000` which is +12% per years. This can only be changed on a local network. + +#### `--stake-min-consumption-rate` (uint) + +The minimum percentage of the consumption rate for the remaining token supply in +the minting period, which is 1 year on Mainnet. Defaults to `100,000` which is +10% per years. This can only be changed on a local network. + +#### `--stake-supply-cap` (uint) + +The maximum stake supply, in nAVAX, that can be placed on a validator. Defaults +to `720,000,000,000,000,000` nAVAX. This can only be changed on a local network. + +#### `--tx-fee` (int) + +The required amount of nAVAX to be burned for a transaction to be valid on the +X-Chain, and for import/export transactions on the P-Chain. This parameter +requires network agreement in its current form. Changing this value from the +default should only be done on private networks or local network. Defaults to +`1,000,000` nAVAX per transaction. + +#### `--uptime-requirement` (float) + +Fraction of time a validator must be online to receive rewards. Defaults to +`0.8`. This can only be changed on a local network. + +#### `--uptime-metric-freq` (duration) + +Frequency of renewing this node's average uptime metric. Defaults to `30s`. + +#### Snow Parameters + +##### `--snow-concurrent-repolls` (int) + +Snow consensus requires repolling transactions that are issued during low time +of network usage. This parameter lets one define how aggressive the client will +be in finalizing these pending transactions. This should only be changed after +careful consideration of the tradeoffs of Snow consensus. The value must be at +least `1` and at most `--snow-rogue-commit-threshold`. Defaults to `4`. + +##### `--snow-sample-size` (int) + +Snow consensus defines `k` as the number of validators that are sampled during +each network poll. This parameter lets one define the `k` value used for +consensus. This should only be changed after careful consideration of the +tradeoffs of Snow consensus. The value must be at least `1`. Defaults to `20`. + +##### `--snow-quorum-size` (int) + +Snow consensus defines `alpha` as the number of validators that must prefer a +transaction during each network poll to increase the confidence in the +transaction. This parameter lets us define the `alpha` value used for consensus. +This should only be changed after careful consideration of the tradeoffs of Snow +consensus. The value must be at greater than `k/2`. Defaults to `15`. + +##### `--snow-virtuous-commit-threshold` (int) + +Snow consensus defines `beta1` as the number of consecutive polls that a +virtuous transaction must increase its confidence for it to be accepted. This +parameter lets us define the `beta1` value used for consensus. This should only +be changed after careful consideration of the tradeoffs of Snow consensus. The +value must be at least `1`. Defaults to `15`. + +##### `--snow-rogue-commit-threshold` (int) + +Snow consensus defines `beta2` as the number of consecutive polls that a rogue +transaction must increase its confidence for it to be accepted. This parameter +lets us define the `beta2` value used for consensus. This should only be changed +after careful consideration of the tradeoffs of Snow consensus. The value must +be at least `beta1`. Defaults to `20`. + +##### `--snow-optimal-processing` (int) + +Optimal number of processing items in consensus. The value must be at least `1`. Defaults to `50`. + +##### `--snow-max-processing` (int) + +Maximum number of processing items to be considered healthy. Reports unhealthy +if more than this number of items are outstanding. The value must be at least +`1`. Defaults to `1024`. + +##### `--snow-max-time-processing` (duration) + +Maximum amount of time an item should be processing and still be healthy. +Reports unhealthy if there is an item processing for longer than this duration. +The value must be greater than `0`. Defaults to `2m`. + +### ProposerVM Parameters + +#### `--proposervm-use-current-height` (bool) + +Have the ProposerVM always report the last accepted P-chain block height. Defaults to `false`. + +### Continuous Profiling + +You can configure your node to continuously run memory/CPU profiles and save the +most recent ones. Continuous memory/CPU profiling is enabled if +`--profile-continuous-enabled` is set. + +#### `--profile-continuous-enabled` (boolean) + +Whether the app should continuously produce performance profiles. Defaults to the false (not enabled). + +#### `--profile-dir` (string) + +If profiling enabled, node continuously runs memory/CPU profiles and puts them +at this directory. Defaults to the `$HOME/.avalanchego/profiles/`. + +#### `--profile-continuous-freq` (duration) + +How often a new CPU/memory profile is created. Defaults to `15m`. + +#### `--profile-continuous-max-files` (int) + +Maximum number of CPU/memory profiles files to keep. Defaults to 5. + +### Health + +#### `--health-check-frequency` (duration) + +Health check runs with this frequency. Defaults to `30s`. + +#### `--health-check-averager-halflife` (duration) + +Half life of averagers used in health checks (to measure the rate of message +failures, for example.) Larger value --> less volatile calculation of +averages. Defaults to `10s`. + +### Network + +#### `--network-allow-private-ips` (bool) + +Allows the node to connect peers with private IPs. Defaults to `true`. + +#### `--network-compression-type` (string) + +The type of compression to use when sending messages to peers. Defaults to `gzip`. +Must be one of [`gzip`, `zstd`, `none`]. + +Nodes can handle inbound `gzip` compressed messages but by default send `zstd` compressed messages. + +#### `--network-initial-timeout` (duration) + +Initial timeout value of the adaptive timeout manager. Defaults to `5s`. + +#### `--network-initial-reconnect-delay` (duration) + +Initial delay duration must be waited before attempting to reconnect a peer. Defaults to `1s`. + +#### `--network-max-reconnect-delay` (duration) + +Maximum delay duration must be waited before attempting to reconnect a peer. Defaults to `1h`. + +#### `--network-minimum-timeout` (duration) + +Minimum timeout value of the adaptive timeout manager. Defaults to `2s`. + +#### `--network-maximum-timeout` (duration) + +Maximum timeout value of the adaptive timeout manager. Defaults to `10s`. + +#### `--network-maximum-inbound-timeout` (duration) + +Maximum timeout value of an inbound message. Defines duration within which an +incoming message must be fulfilled. Incoming messages containing deadline higher +than this value will be overridden with this value. Defaults to `10s`. + +#### `--network-timeout-halflife` (duration) + +Half life used when calculating average network latency. Larger value --> less +volatile network latency calculation. Defaults to `5m`. + +#### `--network-timeout-coefficient` (duration) + +Requests to peers will time out after \[`network-timeout-coefficient`\] \* +\[average request latency\]. Defaults to `2`. + +#### `--network-read-handshake-timeout` (duration) + +Timeout value for reading handshake messages. Defaults to `15s`. + +#### `--network-ping-timeout` (duration) + +Timeout value for Ping-Pong with a peer. Defaults to `30s`. + +#### `--network-ping-frequency` (duration) + +Frequency of pinging other peers. Defaults to `22.5s`. + +#### `--network-health-min-conn-peers` (uint) + +Node will report unhealthy if connected to less than this many peers. Defaults to `1`. + +#### `--network-health-max-time-since-msg-received` (duration) + +Node will report unhealthy if it hasn't received a message for this amount of time. Defaults to `1m`. + +#### `--network-health-max-time-since-msg-sent` (duration) + +Network layer returns unhealthy if haven't sent a message for at least this much time. Defaults to `1m`. + +#### `--network-health-max-portion-send-queue-full` (float) + +Node will report unhealthy if its send queue is more than this portion full. +Must be in \[0,1\]. Defaults to `0.9`. + +#### `--network-health-max-send-fail-rate` (float) + +Node will report unhealthy if more than this portion of message sends fail. Must +be in \[0,1\]. Defaults to `0.25`. + +#### `--network-health-max-outstanding-request-duration` (duration) + +Node reports unhealthy if there has been a request outstanding for this duration. Defaults to `5m`. + +#### `--network-max-clock-difference` (duration) + +Max allowed clock difference value between this node and peers. Defaults to `1m`. + +#### `--network-require-validator-to-connect` (bool) + +If true, this node will only maintain a connection with another node if this +node is a validator, the other node is a validator, or the other node is a +beacon. + +#### `--network-tcp-proxy-enabled` (bool) + +Require all P2P connections to be initiated with a TCP proxy header. Defaults to `false`. + +#### `--network-tcp-proxy-read-timeout` (duration) + +Maximum duration to wait for a TCP proxy header. Defaults to `3s`. + +#### `--network-outbound-connection-timeout` (duration) + +Timeout while dialing a peer. Defaults to `30s`. + +### Message Rate-Limiting + +These flags govern rate-limiting of inbound and outbound messages. For more +information on rate-limiting and the flags below, see package `throttling` in +AvalancheGo. + +#### CPU Based + +Rate-limiting based on how much CPU usage a peer causes. + +##### `--throttler-inbound-cpu-validator-alloc` (float) + +Number of CPU allocated for use by validators. Value should be in range (0, total core count]. +Defaults to half of the number of CPUs on the machine. + +##### `--throttler-inbound-cpu-max-recheck-delay` (duration) + +In the CPU rate-limiter, check at least this often whether the node's CPU usage +has fallen to an acceptable level. Defaults to `5s`. + +##### `--throttler-inbound-disk-max-recheck-delay` (duration) + +In the disk-based network throttler, check at least this often whether the node's disk usage has +fallen to an acceptable level. Defaults to `5s`. + +##### `--throttler-inbound-cpu-max-non-validator-usage` (float) + +Number of CPUs that if fully utilized, will rate limit all non-validators. Value should be in range +[0, total core count]. +Defaults to %80 of the number of CPUs on the machine. + +##### `--throttler-inbound-cpu-max-non-validator-node-usage` (float) + +Maximum number of CPUs that a non-validator can utilize. Value should be in range [0, total core count]. +Defaults to the number of CPUs / 8. + +##### `--throttler-inbound-disk-validator-alloc` (float) + +Maximum number of disk reads/writes per second to allocate for use by validators. Must be > 0. +Defaults to `1000 GiB/s`. + +##### `--throttler-inbound-disk-max-non-validator-usage` (float) + +Number of disk reads/writes per second that, if fully utilized, will rate limit all non-validators. +Must be >= 0. +Defaults to `1000 GiB/s`. + +##### `--throttler-inbound-disk-max-non-validator-node-usage` (float) + +Maximum number of disk reads/writes per second that a non-validator can utilize. Must be >= 0. +Defaults to `1000 GiB/s`. + +#### Bandwidth Based + +Rate-limiting based on the bandwidth a peer uses. + +##### `--throttler-inbound-bandwidth-refill-rate` (uint) + +Max average inbound bandwidth usage of a peer, in bytes per second. See +interface `throttling.BandwidthThrottler`. Defaults to `512`. + +##### `--throttler-inbound-bandwidth-max-burst-size` (uint) + +Max inbound bandwidth a node can use at once. See interface +`throttling.BandwidthThrottler`. Defaults to `2 MiB`. + +#### Message Size Based + +Rate-limiting based on the total size, in bytes, of unprocessed messages. + +##### `--throttler-inbound-at-large-alloc-size` (uint) + +Size, in bytes, of at-large allocation in the inbound message throttler. Defaults to `6291456` (6 MiB). + +##### `--throttler-inbound-validator-alloc-size` (uint) + +Size, in bytes, of validator allocation in the inbound message throttler. +Defaults to `33554432` (32 MiB). + +##### `--throttler-inbound-node-max-at-large-bytes` (uint) + +Maximum number of bytes a node can take from the at-large allocation of the +inbound message throttler. Defaults to `2097152` (2 MiB). + +#### Message Based + +Rate-limiting based on the number of unprocessed messages. + +##### `--throttler-inbound-node-max-processing-msgs` (uint) + +Node will stop reading messages from a peer when it is processing this many messages from the peer. +Will resume reading messages from the peer when it is processing less than this many messages. +Defaults to `1024`. + +#### Outbound + +Rate-limiting for outbound messages. + +##### `--throttler-outbound-at-large-alloc-size` (uint) + +Size, in bytes, of at-large allocation in the outbound message throttler. +Defaults to `33554432` (32 MiB). + +##### `--throttler-outbound-validator-alloc-size` (uint) + +Size, in bytes, of validator allocation in the outbound message throttler. +Defaults to `33554432` (32 MiB). + +##### `--throttler-outbound-node-max-at-large-bytes` (uint) + +Maximum number of bytes a node can take from the at-large allocation of the +outbound message throttler. Defaults to `2097152` (2 MiB). + +### Connection Rate-Limiting + +#### `--network-inbound-connection-throttling-cooldown` (duration) + +Node will upgrade an inbound connection from a given IP at most once within this +duration. Defaults to `10s`. If 0 or negative, will not consider recency of last +upgrade when deciding whether to upgrade. + +#### `--network-inbound-connection-throttling-max-conns-per-sec` (uint) + +Node will accept at most this many inbound connections per second. Defaults to `512`. + +#### `--network-outbound-connection-throttling-rps` (uint) + +Node makes at most this many outgoing peer connection attempts per second. Defaults to `50`. + +### Peer List Gossiping + +Nodes gossip peers to each other so that each node can have an up-to-date peer +list. A node gossips `--network-peer-list-num-validator-ips` validator IPs to +`--network-peer-list-validator-gossip-size` validators, +`--network-peer-list-non-validator-gossip-size` non-validators and +`--network-peer-list-peers-gossip-size` peers every +`--network-peer-list-gossip-frequency`. + +#### `--network-peer-list-num-validator-ips` (int) + +Number of validator IPs to gossip to other nodes Defaults to `15`. + +#### `--network-peer-list-validator-gossip-size` (int) + +Number of validators that the node will gossip peer list to. Defaults to `20`. + +#### `--network-peer-list-non-validator-gossip-size` (int) + +Number of non-validators that the node will gossip peer list to. Defaults to `0`. + +#### `--network-peer-list-peers-gossip-size` (int) + +Number of total peers (including non-validator or validator) that the node will gossip peer list to +Defaults to `0`. + +#### `--network-peer-list-gossip-frequency` (duration) + +Frequency to gossip peers to other nodes. Defaults to `1m`. + +#### ` --network-peer-read-buffer-size` (int) + +Size of the buffer that peer messages are read into (there is one buffer per +peer), defaults to `8` KiB (8192 Bytes). + +#### `--network-peer-write-buffer-size` (int) + +Size of the buffer that peer messages are written into (there is one buffer per +peer), defaults to `8` KiB (8192 Bytes). + +### Resource Usage Tracking + +#### `--meter-vm-enabled` (bool) + +Enable Meter VMs to track VM performance with more granularity. Defaults to `true`. + +#### `--system-tracker-frequency` (duration) + +Frequency to check the real system usage of tracked processes. More frequent +checks --> usage metrics are more accurate, but more expensive to track. +Defaults to `500ms`. + +#### `--system-tracker-processing-halflife` (duration) + +Half life to use for the processing requests tracker. Larger half life --> usage +metrics change more slowly. Defaults to `15s`. + +#### `--system-tracker-cpu-halflife` (duration) + +Half life to use for the CPU tracker. Larger half life --> CPU usage metrics +change more slowly. Defaults to `15s`. + +#### `--system-tracker-disk-halflife` (duration) + +Half life to use for the disk tracker. Larger half life --> disk usage metrics +change more slowly. Defaults to `1m`. + +#### `--system-tracker-disk-required-available-space` (uint) + +"Minimum number of available bytes on disk, under which the node will shutdown. +Defaults to `536870912` (512 MiB). + +#### `--system-tracker-disk-warning-threshold-available-space` (uint) + +Warning threshold for the number of available bytes on disk, under which the +node will be considered unhealthy. Must be >= +`--system-tracker-disk-required-available-space`. Defaults to `1073741824` (1 +GiB). + +### Plugins + +#### `--plugin-dir` (string) + +Sets the directory for [VM plugins](/build/vm/intro.md). The default value is `$HOME/.avalanchego/plugins`. + +### Virtual Machine (VM) Configs + +#### `--vm-aliases-file (string)` + +Path to JSON file that defines aliases for Virtual Machine IDs. Defaults to +`~/.avalanchego/configs/vms/aliases.json`. This flag is ignored if +`--vm-aliases-file-content` is specified. Example content: + +```json +{ + "tGas3T58KzdjLHhBDMnH2TvrddhqTji5iZAMZ3RXs2NLpSnhH": [ + "timestampvm", + "timerpc" + ] +} +``` + +The above example aliases the VM whose ID is +`"tGas3T58KzdjLHhBDMnH2TvrddhqTji5iZAMZ3RXs2NLpSnhH"` to `"timestampvm"` and +`"timerpc"`. + +`--vm-aliases-file-content` (string) + +As an alternative to `--vm-aliases-file`, it allows specifying base64 encoded +aliases for Virtual Machine IDs. + +### Indexing + +#### `--index-allow-incomplete` (boolean) + +If true, allow running the node in such a way that could cause an index to miss transactions. +Ignored if index is disabled. Defaults to `false`. + +### Router + +#### `--router-health-max-drop-rate` (float) + +Node reports unhealthy if the router drops more than this portion of messages. Defaults to `1`. + +#### `--router-health-max-outstanding-requests` (uint) + +Node reports unhealthy if there are more than this many outstanding consensus requests +(Get, PullQuery, etc.) over all chains. Defaults to `1024`. diff --git a/indexer/service.md b/indexer/service.md new file mode 100644 index 000000000000..416cc4e2055b --- /dev/null +++ b/indexer/service.md @@ -0,0 +1,584 @@ +--- +tags: [AvalancheGo APIs] +description: This page is an overview of the Index API associated with AvalancheGo. +sidebar_label: Index API +pagination_label: Index API +--- + +# Index API + +AvalancheGo can be configured to run with an indexer. That is, it saves (indexes) every container (a +block, vertex or transaction) it accepts on the X-Chain, P-Chain and C-Chain. To run AvalancheGo +with indexing enabled, set command line flag +[--index-enabled](/nodes/configure/avalanchego-config-flags.md#apis) to true. **AvalancheGo +will only index containers that are accepted when running with `--index-enabled` set to true.** To +ensure your node has a complete index, run a node with a fresh database and `--index-enabled` set to +true. The node will accept every block, vertex and transaction in the network history during +bootstrapping, ensuring your index is complete. It is OK to turn off your node if it is running with +indexing enabled. If it restarts with indexing still enabled, it will accept all containers that +were accepted while it was offline. The indexer should never fail to index an accepted block, vertex +or transaction. + +Indexed containers (that is, accepted blocks, vertices and transactions) are timestamped with the +time at which the node accepted that container. Note that if the container was indexed during +bootstrapping, other nodes may have accepted the container much earlier. Every container indexed +during bootstrapping will be timestamped with the time at which the node bootstrapped, not when it +was first accepted by the network. + +If `--index-enabled` is changed to `false` from `true`, AvalancheGo won't start as doing so would +cause a previously complete index to become incomplete, unless the user explicitly says to do so +with `--index-allow-incomplete`. This protects you from accidentally running with indexing disabled, +after previously running with it enabled, which would result in an incomplete index. + +This document shows how to query data from AvalancheGo's Index API. The Index API is only available +when running with `--index-enabled`. + +## Go Client + +There is a Go implementation of an Index API client. See documentation +[here](https://pkg.go.dev/github.com/ava-labs/avalanchego/indexer#Client). This client can be used +inside a Go program to connect to an AvalancheGo node that is running with the Index API enabled and +make calls to the Index API. + +## Format + +This API uses the `json 2.0` RPC format. For more information on making JSON RPC calls, see +[here](/reference/standards/guides/issuing-api-calls.md). + +## Endpoints + +Each chain has one or more index. To see if a C-Chain block is accepted, for example, send an API +call to the C-Chain block index. To see if an X-Chain vertex is accepted, for example, send an API +call to the X-Chain vertex index. + +### C-Chain Blocks + +```text +/ext/index/C/block +``` + +### P-Chain Blocks + +```text +/ext/index/P/block +``` + +### X-Chain Transactions + +```text +/ext/index/X/tx +``` + +### X-Chain Blocks + +```text +/ext/index/X/block +``` + +:::caution + +To ensure historical data can be accessed, the `/ext/index/X/vtx` is still accessible, +even though it is no longer populated with chain data since the Cortina activation. +If you are using `V1.10.0` or higher, you need to migrate to using the `/ext/index/X/block` endpoint. + +::: + +## Methods + +### `index.getContainerByID` + +Get container by ID. + +**Signature:** + +```sh +index.getContainerByID({ + id: string, + encoding: string +}) -> { + id: string, + bytes: string, + timestamp: string, + encoding: string, + index: string +} +``` + +**Request:** + +- `id` is the container's ID +- `encoding` is `"hex"` only. + +**Response:** + +- `id` is the container's ID +- `bytes` is the byte representation of the container +- `timestamp` is the time at which this node accepted the container +- `encoding` is `"hex"` only. +- `index` is how many containers were accepted in this index before this one + +**Example Call:** + +```sh +curl --location --request POST 'localhost:9650/ext/index/X/tx' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "jsonrpc": "2.0", + "method": "index.getContainerByID", + "params": { + "id": "6fXf5hncR8LXvwtM8iezFQBpK5cubV6y1dWgpJCcNyzGB1EzY", + "encoding":"hex" + }, + "id": 1 +}' +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "id": "6fXf5hncR8LXvwtM8iezFQBpK5cubV6y1dWgpJCcNyzGB1EzY", + "bytes": "0x00000000000400003039d891ad56056d9c01f18f43f58b5c784ad07a4a49cf3d1f11623804b5cba2c6bf00000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db000000070429ccc5c5eb3b80000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c00000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db00000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db000000050429d069189e0000000000010000000000000000c85fc1980a77c5da78fe5486233fc09a769bb812bcb2cc548cf9495d046b3f1b00000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db00000007000003a352a38240000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c0000000100000009000000011cdb75d4e0b0aeaba2ebc1ef208373fedc1ebbb498f8385ad6fb537211d1523a70d903b884da77d963d56f163191295589329b5710113234934d0fd59c01676b00b63d2108", + "timestamp": "2021-04-02T15:34:00.262979-07:00", + "encoding": "hex", + "index": "0" + } +} +``` + +### `index.getContainerByIndex` + +Get container by index. The first container accepted is at index 0, the second is at index 1, etc. + +**Signature:** + +```sh +index.getContainerByIndex({ + index: uint64, + encoding: string +}) -> { + id: string, + bytes: string, + timestamp: string, + encoding: string, + index: string +} +``` + +**Request:** + +- `index` is how many containers were accepted in this index before this one +- `encoding` is `"hex"` only. + +**Response:** + +- `id` is the container's ID +- `bytes` is the byte representation of the container +- `timestamp` is the time at which this node accepted the container +- `index` is how many containers were accepted in this index before this one +- `encoding` is `"hex"` only. + +**Example Call:** + +```sh +curl --location --request POST 'localhost:9650/ext/index/X/tx' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "jsonrpc": "2.0", + "method": "index.getContainerByIndex", + "params": { + "index":0, + "encoding": "hex" + }, + "id": 1 +}' +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "id": "6fXf5hncR8LXvwtM8iezFQBpK5cubV6y1dWgpJCcNyzGB1EzY", + "bytes": "0x00000000000400003039d891ad56056d9c01f18f43f58b5c784ad07a4a49cf3d1f11623804b5cba2c6bf00000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db000000070429ccc5c5eb3b80000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c00000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db00000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db000000050429d069189e0000000000010000000000000000c85fc1980a77c5da78fe5486233fc09a769bb812bcb2cc548cf9495d046b3f1b00000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db00000007000003a352a38240000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c0000000100000009000000011cdb75d4e0b0aeaba2ebc1ef208373fedc1ebbb498f8385ad6fb537211d1523a70d903b884da77d963d56f163191295589329b5710113234934d0fd59c01676b00b63d2108", + "timestamp": "2021-04-02T15:34:00.262979-07:00", + "encoding": "hex", + "index": "0" + } +} +``` + +### `index.getContainerRange` + +Returns the transactions at index [`startIndex`], [`startIndex+1`], ... , [`startIndex+n-1`] + +- If [`n`] == 0, returns an empty response (for example: null). +- If [`startIndex`] > the last accepted index, returns an error (unless the above apply.) +- If [`n`] > [`MaxFetchedByRange`], returns an error. +- If we run out of transactions, returns the ones fetched before running out. +- `numToFetch` must be in `[0,1024]`. + +**Signature:** + +```sh +index.getContainerRange({ + startIndex: uint64, + numToFetch: uint64, + encoding: string +}) -> []{ + id: string, + bytes: string, + timestamp: string, + encoding: string, + index: string +} +``` + +**Request:** + +- `startIndex` is the beginning index +- `numToFetch` is the number of containers to fetch +- `encoding` is `"hex"` only. + +**Response:** + +- `id` is the container's ID +- `bytes` is the byte representation of the container +- `timestamp` is the time at which this node accepted the container +- `encoding` is `"hex"` only. +- `index` is how many containers were accepted in this index before this one + +**Example Call:** + +```sh +curl --location --request POST 'localhost:9650/ext/index/X/tx' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "jsonrpc": "2.0", + "method": "index.getContainerRange", + "params": { + "startIndex":0, + "numToFetch":100, + "encoding": "hex" + }, + "id": 1 +}' +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { + "id": "6fXf5hncR8LXvwtM8iezFQBpK5cubV6y1dWgpJCcNyzGB1EzY", + "bytes": "0x00000000000400003039d891ad56056d9c01f18f43f58b5c784ad07a4a49cf3d1f11623804b5cba2c6bf00000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db000000070429ccc5c5eb3b80000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c00000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db00000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db000000050429d069189e0000000000010000000000000000c85fc1980a77c5da78fe5486233fc09a769bb812bcb2cc548cf9495d046b3f1b00000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db00000007000003a352a38240000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c0000000100000009000000011cdb75d4e0b0aeaba2ebc1ef208373fedc1ebbb498f8385ad6fb537211d1523a70d903b884da77d963d56f163191295589329b5710113234934d0fd59c01676b00b63d2108", + "timestamp": "2021-04-02T15:34:00.262979-07:00", + "encoding": "hex", + "index": "0" + } + ] +} +``` + +### `index.getIndex` + +Get a container's index. + +**Signature:** + +```sh +index.getIndex({ + id: string, + encoding: string +}) -> { + index: string +} +``` + +**Request:** + +- `id` is the ID of the container to fetch +- `encoding` is `"hex"` only. + +**Response:** + +- `index` is how many containers were accepted in this index before this one + +**Example Call:** + +```sh +curl --location --request POST 'localhost:9650/ext/index/X/tx' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "jsonrpc": "2.0", + "method": "index.getIndex", + "params": { + "id":"6fXf5hncR8LXvwtM8iezFQBpK5cubV6y1dWgpJCcNyzGB1EzY", + "encoding": "hex" + }, + "id": 1 +}' +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "index": "0" + }, + "id": 1 +} +``` + +### `index.getLastAccepted` + +Get the most recently accepted container. + +**Signature:** + +```sh +index.getLastAccepted({ + encoding:string +}) -> { + id: string, + bytes: string, + timestamp: string, + encoding: string, + index: string +} +``` + +**Request:** + +- `encoding` is `"hex"` only. + +**Response:** + +- `id` is the container's ID +- `bytes` is the byte representation of the container +- `timestamp` is the time at which this node accepted the container +- `encoding` is `"hex"` only. + +**Example Call:** + +```sh +curl --location --request POST 'localhost:9650/ext/index/X/tx' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "jsonrpc": "2.0", + "method": "index.getLastAccepted", + "params": { + "encoding": "hex" + }, + "id": 1 +}' +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "id": "6fXf5hncR8LXvwtM8iezFQBpK5cubV6y1dWgpJCcNyzGB1EzY", + "bytes": "0x00000000000400003039d891ad56056d9c01f18f43f58b5c784ad07a4a49cf3d1f11623804b5cba2c6bf00000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db000000070429ccc5c5eb3b80000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c00000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db00000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db000000050429d069189e0000000000010000000000000000c85fc1980a77c5da78fe5486233fc09a769bb812bcb2cc548cf9495d046b3f1b00000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db00000007000003a352a38240000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c0000000100000009000000011cdb75d4e0b0aeaba2ebc1ef208373fedc1ebbb498f8385ad6fb537211d1523a70d903b884da77d963d56f163191295589329b5710113234934d0fd59c01676b00b63d2108", + "timestamp": "2021-04-02T15:34:00.262979-07:00", + "encoding": "hex", + "index": "0" + } +} +``` + +### `index.isAccepted` + +Returns true if the container is in this index. + +**Signature:** + +```sh +index.isAccepted({ + id: string, + encoding: string +}) -> { + isAccepted: bool +} +``` + +**Request:** + +- `id` is the ID of the container to fetch +- `encoding` is `"hex"` only. + +**Response:** + +- `isAccepted` displays if the container has been accepted + +**Example Call:** + +```sh +curl --location --request POST 'localhost:9650/ext/index/X/tx' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "jsonrpc": "2.0", + "method": "index.isAccepted", + "params": { + "id":"6fXf5hncR8LXvwtM8iezFQBpK5cubV6y1dWgpJCcNyzGB1EzY", + "encoding": "hex" + }, + "id": 1 +}' +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "isAccepted": true + }, + "id": 1 +} +``` + +## Example: Iterating Through X-Chain Transaction + +Here is an example of how to iterate through all transactions on the X-Chain. + +:::warning +To help users to try out this example and other index APIs, we have set up a testing +indexer node located at [https://indexer-demo.avax.network](https://indexer-demo.avax.network). This +indexer node is not for production use. We may change or shut it down at any time without notice. +::: + +You can use the Index API to get the ID of every transaction that has been accepted on the X-Chain, +and use the X-Chain API method `avm.getTx` to get a human-readable representation of the +transaction. + +To get an X-Chain transaction by its index (the order it was accepted in), use Index API method +[index.getlastaccepted](#indexgetlastaccepted). + +For example, to get the _second_ transaction (note that `"index":1`) accepted on the X-Chain, do: + +```sh +curl --location --request POST 'https://indexer-demo.avax.network/ext/index/X/tx' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "jsonrpc": "2.0", + "method": "index.getContainerByIndex", + "params": { + "encoding":"hex", + "index":1 + }, + "id": 1 +}' +``` + +This returns the ID of the second transaction accepted in the X-Chain's history. To get the third +transaction on the X-Chain, use `"index":2`, and so on. + +The above API call gives the response below: + +```json +{ + "jsonrpc": "2.0", + "result": { + "id": "ZGYTSU8w3zUP6VFseGC798vA2Vnxnfj6fz1QPfA9N93bhjJvo", + "bytes": "0x00000000000000000001ed5f38341e436e5d46e2bb00b45d62ae97d1b050c64bc634ae10626739e35c4b0000000221e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000070000000129f6afc0000000000000000000000001000000017416792e228a765c65e2d76d28ab5a16d18c342f21e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff0000000700000222afa575c00000000000000000000000010000000187d6a6dd3cd7740c8b13a410bea39b01fa83bb3e000000016f375c785edb28d52edb59b54035c96c198e9d80f5f5f5eee070592fe9465b8d0000000021e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff0000000500000223d9ab67c0000000010000000000000000000000010000000900000001beb83d3d29f1247efb4a3a1141ab5c966f46f946f9c943b9bc19f858bd416d10060c23d5d9c7db3a0da23446b97cd9cf9f8e61df98e1b1692d764c84a686f5f801a8da6e40", + "timestamp": "2021-11-04T00:42:55.01643414Z", + "encoding": "hex", + "index": "1" + }, + "id": 1 +} +``` + +The ID of this transaction is `ZGYTSU8w3zUP6VFseGC798vA2Vnxnfj6fz1QPfA9N93bhjJvo`. + +To get the transaction by its ID, use API method `avm.getTx`: + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"avm.getTx", + "params" :{ + "txID":"ZGYTSU8w3zUP6VFseGC798vA2Vnxnfj6fz1QPfA9N93bhjJvo", + "encoding": "json" + } +}' -H 'content-type:application/json;' https://api.avax.network/ext/bc/X +``` + +Response: + +```json +{ + "jsonrpc": "2.0", + "result": { + "tx": { + "unsignedTx": { + "networkID": 1, + "blockchainID": "2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM", + "outputs": [ + { + "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z", + "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ", + "output": { + "addresses": ["X-avax1wst8jt3z3fm9ce0z6akj3266zmgccdp03hjlaj"], + "amount": 4999000000, + "locktime": 0, + "threshold": 1 + } + }, + { + "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z", + "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ", + "output": { + "addresses": ["X-avax1slt2dhfu6a6qezcn5sgtagumq8ag8we75f84sw"], + "amount": 2347999000000, + "locktime": 0, + "threshold": 1 + } + } + ], + "inputs": [ + { + "txID": "qysTYUMCWdsR3MctzyfXiSvoSf6evbeFGRLLzA4j2BjNXTknh", + "outputIndex": 0, + "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z", + "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ", + "input": { + "amount": 2352999000000, + "signatureIndices": [0] + } + } + ], + "memo": "0x" + }, + "credentials": [ + { + "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ", + "credential": { + "signatures": [ + "0xbeb83d3d29f1247efb4a3a1141ab5c966f46f946f9c943b9bc19f858bd416d10060c23d5d9c7db3a0da23446b97cd9cf9f8e61df98e1b1692d764c84a686f5f801" + ] + } + } + ] + }, + "encoding": "json" + }, + "id": 1 +} +``` diff --git a/subnets/config.md b/subnets/config.md new file mode 100644 index 000000000000..fab5e0e425fe --- /dev/null +++ b/subnets/config.md @@ -0,0 +1,111 @@ +--- +tags: [Nodes] +description: Reference for all available Subnet config options and flags. +sidebar_label: Subnet Configs +pagination_label: Subnet Configs +sidebar_position: 2 +--- + +# Subnet Configs + +It is possible to provide parameters for a Subnet. Parameters here apply to all +chains in the specified Subnet. + +AvalancheGo looks for files specified with `{subnetID}.json` under +`--subnet-config-dir` as documented +[here](/nodes/configure/avalanchego-config-flags.md#subnet-configs). + +Here is an example of Subnet config file: + +```json +{ + "validatorOnly": false, + "consensusParameters": { + "k": 25, + "alpha": 18 + } +} +``` + +## Parameters + +### Private Subnet + +#### `validatorOnly` (bool) + +If `true` this node does not expose Subnet blockchain contents to non-validators +via P2P messages. Defaults to `false`. + +Avalanche Subnets are public by default. It means that every node can sync and +listen ongoing transactions/blocks in Subnets, even they're not validating the +listened Subnet. + +Subnet validators can choose not to publish contents of blockchains via this +configuration. If a node sets `validatorOnly` to true, the node exchanges +messages only with this Subnet's validators. Other peers will not be able to +learn contents of this Subnet from this node. + +:::tip + +This is a node-specific configuration. Every validator of this Subnet has to use +this configuration in order to create a full private Subnet. + +::: + +#### `allowedNodes` (string list) + +If `validatorOnly=true` this allows explicitly specified NodeIDs to be allowed +to sync the Subnet regardless of validator status. Defaults to be empty. + +:::tip + +This is a node-specific configuration. Every validator of this Subnet has to use +this configuration in order to properly allow a node in the private Subnet. + +::: + +#### `proposerMinBlockDelay` (duration) + +The minimum delay performed when building snowman++ blocks. Default is set to 1 second. + +As one of the ways to control network congestion, Snowman++ will only build a +block `proposerMinBlockDelay` after the parent block's timestamp. Some +high-performance custom VM may find this too strict. This flag allows tuning the +frequency at which blocks are built. + +### Consensus Parameters + +Subnet configs supports loading new consensus parameters. JSON keys are +different from their matching `CLI` keys. These parameters must be grouped under +`consensusParameters` key. The consensus parameters of a Subnet default to the +same values used for the Primary Network, which are given [CLI Snow Parameters](/nodes/configure/avalanchego-config-flags.md#snow-parameters). + +| CLI Key | JSON Key | +| :------------------------------- | :-------------------- | +| --snow-sample-size | k | +| --snow-quorum-size | alpha | +| --snow-virtuous-commit-threshold | `betaVirtuous` | +| --snow-rogue-commit-threshold | `betaRogue` | +| --snow-concurrent-repolls | concurrentRepolls | +| --snow-optimal-processing | `optimalProcessing` | +| --snow-max-processing | maxOutstandingItems | +| --snow-max-time-processing | maxItemProcessingTime | +| --snow-avalanche-batch-size | `batchSize` | +| --snow-avalanche-num-parents | `parentSize` | + +### Gossip Configs + +It's possible to define different Gossip configurations for each Subnet without +changing values for Primary Network. JSON keys of these +parameters are different from their matching `CLI` keys. These parameters +default to the same values used for the Primary Network. For more information +see [CLI Gossip Configs](/nodes/configure/avalanchego-config-flags.md#gossiping). + +| CLI Key | JSON Key | +| :------------------------------------------------------ | :------------------------------------- | +| --consensus-accepted-frontier-gossip-validator-size | gossipAcceptedFrontierValidatorSize | +| --consensus-accepted-frontier-gossip-non-validator-size | gossipAcceptedFrontierNonValidatorSize | +| --consensus-accepted-frontier-gossip-peer-size | gossipAcceptedFrontierPeerSize | +| --consensus-on-accept-gossip-validator-size | gossipOnAcceptValidatorSize | +| --consensus-on-accept-gossip-non-validator-size | gossipOnAcceptNonValidatorSize | +| --consensus-on-accept-gossip-peer-size | gossipOnAcceptPeerSize | diff --git a/vms/avm/config.md b/vms/avm/config.md new file mode 100644 index 000000000000..58cbe1435c26 --- /dev/null +++ b/vms/avm/config.md @@ -0,0 +1,61 @@ +--- +tags: [Nodes, AvalancheGo] +description: Reference for all available X-chain config options and flags. +pagination_label: X-Chain Configs +sidebar_position: 2 +--- + +# X-Chain + +In order to specify a config for the X-Chain, a JSON config file should be +placed at `{chain-config-dir}/X/config.json`. + +For example if `chain-config-dir` has the default value which is +`$HOME/.avalanchego/configs/chains`, then `config.json` can be placed at +`$HOME/.avalanchego/configs/chains/X/config.json`. + +This allows you to specify a config to be passed into the X-Chain. The default +values for this config are: + +```json +{ + "index-transactions": false, + "index-allow-incomplete": false, + "checksums-enabled": false +} +``` + +Default values are overridden only if explicitly specified in the config. + +The parameters are as follows: + +## Transaction Indexing + +### `index-transactions` + +_Boolean_ + +Enables AVM transaction indexing if set to `true`. +When set to `true`, AVM transactions are indexed against the `address` and +`assetID` involved. This data is available via `avm.getAddressTxs` +[API](/reference/avalanchego/x-chain/api.md#avmgetaddresstxs). + +:::note +If `index-transactions` is set to true, it must always be set to true +for the node's lifetime. If set to `false` after having been set to `true`, the +node will refuse to start unless `index-allow-incomplete` is also set to `true` +(see below). +::: + +### `index-allow-incomplete` + +_Boolean_ + +Allows incomplete indices. This config value is ignored if there is no X-Chain indexed data in the DB and +`index-transactions` is set to `false`. + +### `checksums-enabled` + +_Boolean_ + +Enables checksums if set to `true`. diff --git a/vms/avm/service.md b/vms/avm/service.md new file mode 100644 index 000000000000..dfba13b05f0e --- /dev/null +++ b/vms/avm/service.md @@ -0,0 +1,2319 @@ +--- +tags: [X-Chain, AvalancheGo APIs] +description: This page is an overview of the Exchange Chain (X-Chain) API associated with AvalancheGo. +sidebar_label: API +pagination_label: X-Chain API +--- + +# X-Chain API + +The [X-Chain](/learn/avalanche/avalanche-platform.md#x-chain), +Avalanche’s native platform for creating and trading assets, is an instance of the Avalanche Virtual +Machine (AVM). This API allows clients to create and trade assets on the X-Chain and other instances +of the AVM. + +## Format + +This API uses the `json 2.0` RPC format. For more information on making JSON RPC calls, see +[here](/reference/standards/guides/issuing-api-calls.md). + +## Endpoints + +`/ext/bc/X` to interact with the X-Chain. + +`/ext/bc/blockchainID` to interact with other AVM instances, where `blockchainID` is the ID of a +blockchain running the AVM. + +## Methods + +### `avm.buildGenesis` + +Given a JSON representation of this Virtual Machine’s genesis state, create the byte representation +of that state. + +#### **Endpoint** + +This call is made to the AVM’s static API endpoint: + +`/ext/vm/avm` + +Note: addresses should not include a chain prefix (that is `X-`) in calls to the static API endpoint +because these prefixes refer to a specific chain. + +**Signature:** + +```sh +avm.buildGenesis({ + networkID: int, + genesisData: JSON, + encoding: string, //optional +}) -> { + bytes: string, + encoding: string, +} +``` + +Encoding specifies the encoding format to use for arbitrary bytes, that is the genesis bytes that are +returned. Can only be `hex` when a value is provided. + +`genesisData` has this form: + +```json +{ +"genesisData" : + { + "assetAlias1": { // Each object defines an asset + "name": "human readable name", + "symbol":"AVAL", // Symbol is between 0 and 4 characters + "initialState": { + "fixedCap" : [ // Choose the asset type. + { // Can be "fixedCap", "variableCap", "limitedTransfer", "nonFungible" + "amount":1000, // At genesis, address A has + "address":"A" // 1000 units of asset + }, + { + "amount":5000, // At genesis, address B has + "address":"B" // 1000 units of asset + }, + ... // Can have many initial holders + ] + } + }, + "assetAliasCanBeAnythingUnique": { // Asset alias can be used in place of assetID in calls + "name": "human readable name", // names need not be unique + "symbol": "AVAL", // symbols need not be unique + "initialState": { + "variableCap" : [ // No units of the asset exist at genesis + { + "minters": [ // The signature of A or B can mint more of + "A", // the asset. + "B" + ], + "threshold":1 + }, + { + "minters": [ // The signatures of 2 of A, B and C can mint + "A", // more of the asset + "B", + "C" + ], + "threshold":2 + }, + ... // Can have many minter sets + ] + } + }, + ... // Can list more assets + } +} +``` + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc": "2.0", + "id" : 1, + "method" : "avm.buildGenesis", + "params" : { + "networkId": 16, + "genesisData": { + "asset1": { + "name": "myFixedCapAsset", + "symbol":"MFCA", + "initialState": { + "fixedCap" : [ + { + "amount":100000, + "address": "avax13ery2kvdrkd2nkquvs892gl8hg7mq4a6ufnrn6" + }, + { + "amount":100000, + "address": "avax1rvks3vpe4cm9yc0rrk8d5855nd6yxxutfc2h2r" + }, + { + "amount":50000, + "address": "avax1ntj922dj4crc4pre4e0xt3dyj0t5rsw9uw0tus" + }, + { + "amount":50000, + "address": "avax1yk0xzmqyyaxn26sqceuky2tc2fh2q327vcwvda" + } + ] + } + }, + "asset2": { + "name": "myVarCapAsset", + "symbol":"MVCA", + "initialState": { + "variableCap" : [ + { + "minters": [ + "avax1kcfg6avc94ct3qh2mtdg47thsk8nrflnrgwjqr", + "avax14e2s22wxvf3c7309txxpqs0qe9tjwwtk0dme8e" + ], + "threshold":1 + }, + { + "minters": [ + "avax1y8pveyn82gjyqr7kqzp72pqym6xlch9gt5grck", + "avax1c5cmm0gem70rd8dcnpel63apzfnfxye9kd4wwe", + "avax12euam2lwtwa8apvfdl700ckhg86euag2hlhmyw" + ], + "threshold":2 + } + ] + } + } + }, + "encoding": "hex" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/vm/avm +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "bytes": "0x0000000000010006617373657431000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000f6d794669786564436170417373657400044d464341000000000100000000000000010000000700000000000186a10000000000000000000000010000000152b219bc1b9ab0a9f2e3f9216e4460bd5db8d153bfa57c3c", + "encoding": "hex" + }, + "id": 1 +} +``` + +### `avm.createAddress` + +:::caution + +Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12). + +::: + +:::warning +Not recommended for use on Mainnet. See warning notice in [Keystore API](/reference/avalanchego/keystore-api.md). +::: + +Create a new address controlled by the given user. + +**Signature:** + +```sh +avm.createAddress({ + username: string, + password: string +}) -> {address: string} +``` + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc": "2.0", + "method": "avm.createAddress", + "params": { + "username": "myUsername", + "password": "myPassword" + }, + "id": 1 +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "address": "X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5" + }, + "id": 1 +} +``` + + + +### `avm.createFixedCapAsset` + +:::caution + +Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12). + +::: + +:::warning +Not recommended for use on Mainnet. See warning notice in [Keystore API](/reference/avalanchego/keystore-api.md). +::: + +Create a new fixed-cap, fungible asset. A quantity of it is created at initialization and then no +more is ever created. The asset can be sent with `avm.send`. + +**Signature:** + +```sh +avm.createFixedCapAsset({ + name: string, + symbol: string, + denomination: int, //optional + initialHolders: []{ + address: string, + amount: int + }, + from: []string, //optional + changeAddr: string, //optional + username: string, + password: string +}) -> +{ + assetID: string, + changeAddr: string +} +``` + +- `name` is a human-readable name for the asset. Not necessarily unique. +- `symbol` is a shorthand symbol for the asset. Between 0 and 4 characters. Not necessarily unique. + May be omitted. +- `denomination` determines how balances of this asset are displayed by user interfaces. If + `denomination` is 0, 100 units of this asset are displayed as 100. If `denomination` is 1, 100 + units of this asset are displayed as 10.0. If `denomination` is 2, 100 units of this asset are + displayed as 1.00, etc. Defaults to 0. +- `from` are the addresses that you want to use for this operation. If omitted, uses any of your + addresses as needed. +- `changeAddr` is the address any change will be sent to. If omitted, change is sent to one of the + addresses controlled by the user. +- `username` and `password` denote the user paying the transaction fee. +- Each element in `initialHolders` specifies that `address` holds `amount` units of the asset at + genesis. +- `assetID` is the ID of the new asset. + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" : 1, + "method" :"avm.createFixedCapAsset", + "params" :{ + "name": "myFixedCapAsset", + "symbol":"MFCA", + "initialHolders": [ + { + "address": "X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", + "amount": 10000 + }, + { + "address":"X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", + "amount":50000 + } + ], + "from":["X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"], + "changeAddr":"X-avax1turszjwn05lflpewurw96rfrd3h6x8flgs5uf8", + "username":"myUsername", + "password":"myPassword" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "assetID": "ZiKfqRXCZgHLgZ4rxGU9Qbycdzuq5DRY4tdSNS9ku8kcNxNLD", + "changeAddr": "X-avax1turszjwn05lflpewurw96rfrd3h6x8flgs5uf8" + } +} +``` + +### `avm.createNFTAsset` + +:::caution + +Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12). + +::: + +:::warning +Not recommended for use on Mainnet. See warning notice in [Keystore API](/reference/avalanchego/keystore-api.md). +::: + +Create a new non-fungible asset. No units of the asset exist at initialization. Minters can mint +units of this asset using `avm.mintNFT`. + +**Signature:** + +```sh +avm.createNFTAsset({ + name: string, + symbol: string, + minterSets: []{ + minters: []string, + threshold: int + }, + from: []string, //optional + changeAddr: string, //optional + username: string, + password: string +}) -> + { + assetID: string, + changeAddr: string, +} +``` + +- `name` is a human-readable name for the asset. Not necessarily unique. +- `symbol` is a shorthand symbol for the asset. Between 0 and 4 characters. Not necessarily unique. + May be omitted. +- `minterSets` is a list where each element specifies that `threshold` of the addresses in `minters` + may together mint more of the asset by signing a minting transaction. +- `from` are the addresses that you want to use for this operation. If omitted, uses any of your + addresses as needed. +- `changeAddr` is the address any change will be sent to. If omitted, change is sent to one of the + addresses controlled by the user. +- `username` pays the transaction fee. +- `assetID` is the ID of the new asset. +- `changeAddr` in the result is the address where any change was sent. + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" : 1, + "method" :"avm.createNFTAsset", + "params" :{ + "name":"Coincert", + "symbol":"TIXX", + "minterSets":[ + { + "minters":[ + "X-avax1turszjwn05lflpewurw96rfrd3h6x8flgs5uf8" + ], + "threshold": 1 + } + ], + "from": ["X-avax1turszjwn05lflpewurw96rfrd3h6x8flgs5uf8"], + "changeAddr": "X-avax1turszjwn05lflpewurw96rfrd3h6x8flgs5uf8", + "username":"myUsername", + "password":"myPassword" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "assetID": "2KGdt2HpFKpTH5CtGZjYt5XPWs6Pv9DLoRBhiFfntbezdRvZWP", + "changeAddr": "X-avax1turszjwn05lflpewurw96rfrd3h6x8flgs5uf8" + }, + "id": 1 +} +``` + +### `avm.createVariableCapAsset` + +:::caution + +Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12). + +::: + +:::warning +Not recommended for use on Mainnet. See warning notice in [Keystore API](/reference/avalanchego/keystore-api.md). +::: + +Create a new variable-cap, fungible asset. No units of the asset exist at initialization. Minters +can mint units of this asset using `avm.mint`. + +**Signature:** + +```sh +avm.createVariableCapAsset({ + name: string, + symbol: string, + denomination: int, //optional + minterSets: []{ + minters: []string, + threshold: int + }, + from: []string, //optional + changeAddr: string, //optional + username: string, + password: string +}) -> +{ + assetID: string, + changeAddr: string, +} +``` + +- `name` is a human-readable name for the asset. Not necessarily unique. +- `symbol` is a shorthand symbol for the asset. Between 0 and 4 characters. Not necessarily unique. + May be omitted. +- `denomination` determines how balances of this asset are displayed by user interfaces. If + denomination is 0, 100 units of this asset are displayed as 100. If denomination is 1, 100 units + of this asset are displayed as 10.0. If denomination is 2, 100 units of this asset are displays as + .100, etc. +- `minterSets` is a list where each element specifies that `threshold` of the addresses in `minters` + may together mint more of the asset by signing a minting transaction. +- `from` are the addresses that you want to use for this operation. If omitted, uses any of your + addresses as needed. +- `changeAddr` is the address any change will be sent to. If omitted, change is sent to one of the + addresses controlled by the user. +- `username` pays the transaction fee. +- `assetID` is the ID of the new asset. +- `changeAddr` in the result is the address where any change was sent. + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" : 1, + "method" :"avm.createVariableCapAsset", + "params" :{ + "name":"myVariableCapAsset", + "symbol":"MFCA", + "minterSets":[ + { + "minters":[ + "X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5" + ], + "threshold": 1 + }, + { + "minters": [ + "X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", + "X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", + "X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5" + ], + "threshold": 2 + } + ], + "from":["X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"], + "changeAddr":"X-avax1turszjwn05lflpewurw96rfrd3h6x8flgs5uf8", + "username":"myUsername", + "password":"myPassword" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "assetID": "2QbZFE7J4MAny9iXHUwq8Pz8SpFhWk3maCw4SkinVPv6wPmAbK", + "changeAddr": "X-avax1turszjwn05lflpewurw96rfrd3h6x8flgs5uf8" + } +} +``` + +### `avm.export` + +:::caution + +Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12). + +::: + +::: +Not recommended for use on Mainnet. See warning notice in [Keystore API](/reference/avalanchego/keystore-api.md). +::: + +Send an asset from the X-Chain to the P-Chain or C-Chain. + +**Signature:** + +```sh +avm.export({ + to: string, + amount: int, + assetID: string, + from: []string, //optional + changeAddr: string, //optional + username: string, + password: string, +}) -> +{ + txID: string, + changeAddr: string, +} +``` + +- `to` is the P-Chain or C-Chain address the asset is sent to. +- `amount` is the amount of the asset to send. +- `assetID` is the asset id of the asset which is sent. Use `AVAX` for AVAX exports. +- `from` are the addresses that you want to use for this operation. If omitted, uses any of your + addresses as needed. +- `changeAddr` is the address any change will be sent to. If omitted, change is sent to one of the + addresses controlled by the user. +- The asset is sent from addresses controlled by `username` +- `password` is `username`‘s password. + +- `txID` is this transaction’s ID. +- `changeAddr` in the result is the address where any change was sent. + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"avm.export", + "params" :{ + "to":"C-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", + "amount": 10, + "assetID": "AVAX", + "from":["X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"], + "changeAddr":"X-avax1turszjwn05lflpewurw96rfrd3h6x8flgs5uf8", + "username":"myUsername", + "password":"myPassword" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "txID": "2Eu16yNaepP57XrrJgjKGpiEDandpiGWW8xbUm6wcTYny3fejj", + "changeAddr": "X-avax1turszjwn05lflpewurw96rfrd3h6x8flgs5uf8" + }, + "id": 1 +} +``` + + + +### `avm.exportKey` + +:::caution + +Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12). + +::: + +:::warning +Not recommended for use on Mainnet. See warning notice in [Keystore API](/reference/avalanchego/keystore-api.md). +::: + +Get the private key that controls a given address. The returned private key can be added to a user +with [`avm.importKey`](/reference/avalanchego/x-chain/api.md#avmimportkey). + +**Signature:** + +```sh +avm.exportKey({ + username: string, + password: string, + address: string +}) -> {privateKey: string} +``` + +- `username` must control `address`. +- `privateKey` is the string representation of the private key that controls `address`. + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"avm.exportKey", + "params" :{ + "username":"myUsername", + "password":"myPassword", + "address":"X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "privateKey": "PrivateKey-2w4XiXxPfQK4TypYqnohRL8DRNTz9cGiGmwQ1zmgEqD9c9KWLq" + } +} +``` + +### `avm.getAddressTxs` + +:::caution + +Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12). + +::: + +Returns all transactions that change the balance of the given address. A transaction is said to +change an address's balance if either is true: + +- A UTXO that the transaction consumes was at least partially owned by the address. +- A UTXO that the transaction produces is at least partially owned by the address. + +:::tip +Note: Indexing (`index-transactions`) must be enabled in the X-chain config. +::: + +**Signature:** + +```sh +avm.getAddressTxs({ + address: string, + cursor: uint64, // optional, leave empty to get the first page + assetID: string, + pageSize: uint64 // optional, defaults to 1024 +}) -> { + txIDs: []string, + cursor: uint64, +} +``` + +**Request Parameters:** + +- `address`: The address for which we're fetching related transactions +- `assetID`: Only return transactions that changed the balance of this asset. Must be an ID or an + alias for an asset. +- `pageSize`: Number of items to return per page. Optional. Defaults to 1024. + +**Response Parameter:** + +- `txIDs`: List of transaction IDs that affected the balance of this address. +- `cursor`: Page number or offset. Use this in request to get the next page. + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" : 1, + "method" :"avm.getAddressTxs", + "params" :{ + "address":"X-local1kpprmfpzzm5lxyene32f6lr7j0aj7gxsu6hp9y", + "assetID":"AVAX", + "pageSize":20 + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "txIDs": ["SsJF7KKwxiUJkczygwmgLqo3XVRotmpKP8rMp74cpLuNLfwf6"], + "cursor": "1" + }, + "id": 1 +} +``` + +### `avm.getAllBalances` + +:::caution + +Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12). + +::: + +Get the balances of all assets controlled by a given address. + +**Signature:** + +```sh +avm.getAllBalances({address:string}) -> { + balances: []{ + asset: string, + balance: int + } +} +``` + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" : 1, + "method" :"avm.getAllBalances", + "params" :{ + "address":"X-avax1c79e0dd0susp7dc8udq34jgk2yvve7hapvdyht" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "balances": [ + { + "asset": "AVAX", + "balance": "102" + }, + { + "asset": "2sdnziCz37Jov3QSNMXcFRGFJ1tgauaj6L7qfk7yUcRPfQMC79", + "balance": "10000" + } + ] + }, + "id": 1 +} +``` + +### `avm.getAssetDescription` + +Get information about an asset. + +**Signature:** + +```sh +avm.getAssetDescription({assetID: string}) -> { + assetId: string, + name: string, + symbol: string, + denomination: int +} +``` + +- `assetID` is the id of the asset for which the information is requested. +- `name` is the asset’s human-readable, not necessarily unique name. +- `symbol` is the asset’s symbol. +- `denomination` determines how balances of this asset are displayed by user interfaces. If + denomination is 0, 100 units of this asset are displayed as 100. If denomination is 1, 100 units + of this asset are displayed as 10.0. If denomination is 2, 100 units of this asset are displays as + .100, etc. + +:::note + +The AssetID for AVAX differs depending on the network you are on. + +Mainnet: FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z + +Testnet: U8iRqJoiJm8xZHAacmvYyZVwqQx6uDNtQeP3CQ6fcgQk3JqnK + +For finding the `assetID` of other assets, this [info] might be useful. +Also, `avm.getUTXOs` returns the `assetID` in its output. + +::: + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"avm.getAssetDescription", + "params" :{ + "assetID" :"FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z", + "name": "Avalanche", + "symbol": "AVAX", + "denomination": "9" + }, + "id": 1 +}` +``` + +### `avm.getBalance` + +:::caution + +Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12). + +::: + +Get the balance of an asset controlled by a given address. + +**Signature:** + +```sh +avm.getBalance({ + address: string, + assetID: string +}) -> {balance: int} +``` + +- `address` owner of the asset +- `assetID` id of the asset for which the balance is requested + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" : 1, + "method" :"avm.getBalance", + "params" :{ + "address":"X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", + "assetID": "2pYGetDWyKdHxpFxh2LHeoLNCH6H5vxxCxHQtFnnFaYxLsqtHC" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "balance": "299999999999900", + "utxoIDs": [ + { + "txID": "WPQdyLNqHfiEKp4zcCpayRHYDVYuh1hqs9c1RqgZXS4VPgdvo", + "outputIndex": 1 + } + ] + } +} +``` + +### `avm.getBlock` + +Returns the block with the given id. + +**Signature:** + +```sh +avm.getBlock({ + blockID: string + encoding: string // optional +}) -> { + block: string, + encoding: string +} +``` + +**Request:** + +- `blockID` is the block ID. It should be in cb58 format. +- `encoding` is the encoding format to use. Can be either `hex` or `json`. Defaults to `hex`. + +**Response:** + +- `block` is the transaction encoded to `encoding`. +- `encoding` is the `encoding`. + +#### Hex Example + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc": "2.0", + "method": "avm.getBlock", + "params": { + "blockID": "tXJ4xwmR8soHE6DzRNMQPtiwQvuYsHn6eLLBzo2moDqBquqy6", + "encoding": "hex" + }, + "id": 1 +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "block": "0x00000000002000000000641ad33ede17f652512193721df87994f783ec806bb5640c39ee73676caffcc3215e0651000000000049a80a000000010000000e0000000100000000000000000000000000000000000000000000000000000000000000000000000121e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000070000002e1a2a3910000000000000000000000001000000015cf998275803a7277926912defdf177b2e97b0b400000001e0d825c5069a7336671dd27eaa5c7851d2cf449e7e1cdc469c5c9e5a953955950000000021e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000050000008908223b680000000100000000000000005e45d02fcc9e585544008f1df7ae5c94bf7f0f2600000000641ad3b600000000642d48b60000005aedf802580000000121e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000070000005aedf80258000000000000000000000001000000015cf998275803a7277926912defdf177b2e97b0b40000000b000000000000000000000001000000012892441ba9a160bcdc596dcd2cc3ad83c3493589000000010000000900000001adf2237a5fe2dfd906265e8e14274aa7a7b2ee60c66213110598ba34fb4824d74f7760321c0c8fb1e8d3c5e86909248e48a7ae02e641da5559351693a8a1939800286d4fa2", + "encoding": "hex" + }, + "id": 1 +} +``` + +### `avm.getBlockByHeight` + +Returns block at the given height. + +**Signature:** + +```sh +avm.getBlockByHeight({ + height: string + encoding: string // optional +}) -> { + block: string, + encoding: string +} +``` + +**Request:** + +- `blockHeight` is the block height. It should be in `string` format. +- `encoding` is the encoding format to use. Can be either `hex` or `json`. Defaults to `hex`. + +**Response:** + +- `block` is the transaction encoded to `encoding`. +- `encoding` is the `encoding`. + +#### Hex Example + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc": "2.0", + "method": "avm.getBlockByHeight”, + "params": { + “height”: “275686313486”, + "encoding": “hex” + }, + "id": 1 +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "block": "0x00000000002000000000642f6739d4efcdd07e4d4919a7fc2020b8a0f081dd64c262aaace5a6dad22be0b55fec0700000000004db9e100000001000000110000000100000000000000000000000000000000000000000000000000000000000000000000000121e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000070000005c6ece390000000000000000000000000100000001930ab7bf5018bfc6f9435c8b15ba2fe1e619c0230000000000000000ed5f38341e436e5d46e2bb00b45d62ae97d1b050c64bc634ae10626739e35c4b00000001c6dda861341665c3b555b46227fb5e56dc0a870c5482809349f04b00348af2a80000000021e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000050000005c6edd7b40000000010000000000000001000000090000000178688f4d5055bd8733801f9b52793da885bef424c90526c18e4dd97f7514bf6f0c3d2a0e9a5ea8b761bc41902eb4902c34ef034c4d18c3db7c83c64ffeadd93600731676de", + "encoding": "hex" + }, + "id": 1 +} +``` + +### `avm.getHeight` + +Returns the height of the last accepted block. + +**Signature:** + +```sh +avm.getHeight() -> +{ + height: uint64, +} +``` + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc": "2.0", + "method": "avm.getHeight", + "params": {}, + "id": 1 +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "height": "5094088" + }, + "id": 1 +} +``` + +### `avm.getTx` + +Returns the specified transaction. The `encoding` parameter sets the format of the returned +transaction. Can be either `"hex"` or `"json"`. Defaults to `"hex"`. + +**Signature:** + +```sh +avm.getTx({ + txID: string, + encoding: string, //optional +}) -> { + tx: string, + encoding: string, +} +``` + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"avm.getTx", + "params" :{ + "txID":"2oJCbb8pfdxEHAf9A8CdN4Afj9VSR3xzyzNkf8tDv7aM1sfNFL", + "encoding": "json" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "tx": { + "unsignedTx": { + "networkID": 1, + "blockchainID": "2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM", + "outputs": [], + "inputs": [ + { + "txID": "2jbZUvi6nHy3Pgmk8xcMpSg5cW6epkPqdKkHSCweb4eRXtq4k9", + "outputIndex": 1, + "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z", + "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ", + "input": { + "amount": 2570382395, + "signatureIndices": [0] + } + } + ], + "memo": "0x", + "destinationChain": "11111111111111111111111111111111LpoYY", + "exportedOutputs": [ + { + "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z", + "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ", + "output": { + "addresses": ["X-avax1tnuesf6cqwnjw7fxjyk7lhch0vhf0v95wj5jvy"], + "amount": 2569382395, + "locktime": 0, + "threshold": 1 + } + } + ] + }, + "credentials": [ + { + "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ", + "credential": { + "signatures": [ + "0x46ebcbcfbee3ece1fd15015204045cf3cb77f42c48d0201fc150341f91f086f177cfca8894ca9b4a0c55d6950218e4ea8c01d5c4aefb85cd7264b47bd57d224400" + ] + } + } + ], + "id": "2oJCbb8pfdxEHAf9A8CdN4Afj9VSR3xzyzNkf8tDv7aM1sfNFL" + }, + "encoding": "json" + }, + "id": 1 +} +``` + +Where: + +- `credentials` is a list of this transaction's credentials. Each credential proves that this + transaction's creator is allowed to consume one of this transaction's inputs. Each credential is a + list of signatures. +- `unsignedTx` is the non-signature portion of the transaction. +- `networkID` is the ID of the network this transaction happened on. (Avalanche Mainnet is `1`.) +- `blockchainID` is the ID of the blockchain this transaction happened on. (Avalanche Mainnet + X-Chain is `2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM`.) +- Each element of `outputs` is an output (UTXO) of this transaction that is not being exported to + another chain. +- Each element of `inputs` is an input of this transaction which has not been imported from another + chain. +- Import Transactions have additional fields `sourceChain` and `importedInputs`, which specify the + blockchain ID that assets are being imported from, and the inputs that are being imported. +- Export Transactions have additional fields `destinationChain` and `exportedOutputs`, which specify + the blockchain ID that assets are being exported to, and the UTXOs that are being exported. + +An output contains: + +- `assetID`: The ID of the asset being transferred. (The Mainnet Avax ID is + `FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z`.) +- `fxID`: The ID of the FX this output uses. +- `output`: The FX-specific contents of this output. + +Most outputs use the secp256k1 FX, look like this: + +```json +{ + "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z", + "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ", + "output": { + "addresses": ["X-avax126rd3w35xwkmj8670zvf7y5r8k36qa9z9803wm"], + "amount": 1530084210, + "locktime": 0, + "threshold": 1 + } +} +``` + +The above output can be consumed after Unix time `locktime` by a transaction that has signatures +from `threshold` of the addresses in `addresses`. + +### `avm.getTxStatus` + +:::caution +Deprecated as of **v1.10.0**. +::: + +Get the status of a transaction sent to the network. + +**Signature:** + +```sh +avm.getTxStatus({txID: string}) -> {status: string} +``` + +`status` is one of: + +- `Accepted`: The transaction is (or will be) accepted by every node +- `Processing`: The transaction is being voted on by this node +- `Rejected`: The transaction will never be accepted by any node in the network +- `Unknown`: The transaction hasn’t been seen by this node + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"avm.getTxStatus", + "params" :{ + "txID":"2QouvFWUbjuySRxeX5xMbNCuAaKWfbk5FeEa2JmoF85RKLk2dD" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "status": "Accepted" + } +} +``` + +### `avm.getUTXOs` + +Gets the UTXOs that reference a given address. If `sourceChain` is specified, then it will retrieve +the atomic UTXOs exported from that chain to the X Chain. + +**Signature:** + +```sh +avm.getUTXOs({ + addresses: []string, + limit: int, //optional + startIndex: { //optional + address: string, + utxo: string + }, + sourceChain: string, //optional + encoding: string //optional +}) -> { + numFetched: int, + utxos: []string, + endIndex: { + address: string, + utxo: string + }, + sourceChain: string, //optional + encoding: string +} +``` + +- `utxos` is a list of UTXOs such that each UTXO references at least one address in `addresses`. +- At most `limit` UTXOs are returned. If `limit` is omitted or greater than 1024, it is set to 1024. +- This method supports pagination. `endIndex` denotes the last UTXO returned. To get the next set of + UTXOs, use the value of `endIndex` as `startIndex` in the next call. +- If `startIndex` is omitted, will fetch all UTXOs up to `limit`. +- When using pagination (when `startIndex` is provided), UTXOs are not guaranteed to be unique + across multiple calls. That is, a UTXO may appear in the result of the first call, and then again + in the second call. +- When using pagination, consistency is not guaranteed across multiple calls. That is, the UTXO set + of the addresses may have changed between calls. +- `encoding` sets the format for the returned UTXOs. Can only be `hex` when a value is provided. + +#### **Example** + +Suppose we want all UTXOs that reference at least one of +`X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5` and `X-avax1d09qn852zcy03sfc9hay2llmn9hsgnw4tp3dv6`. + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"avm.getUTXOs", + "params" :{ + "addresses":["X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", "X-avax1d09qn852zcy03sfc9hay2llmn9hsgnw4tp3dv6"], + "limit":5, + "encoding": "hex" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X +``` + +This gives response: + +```json +{ + "jsonrpc": "2.0", + "result": { + "numFetched": "5", + "utxos": [ + "0x0000a195046108a85e60f7a864bb567745a37f50c6af282103e47cc62f036cee404700000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216c1f01765", + "0x0000ae8b1b94444eed8de9a81b1222f00f1b4133330add23d8ac288bffa98b85271100000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216473d042a", + "0x0000731ce04b1feefa9f4291d869adc30a33463f315491e164d89be7d6d2d7890cfc00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f21600dd3047", + "0x0000b462030cc4734f24c0bc224cf0d16ee452ea6b67615517caffead123ab4fbf1500000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216c71b387e", + "0x000054f6826c39bc957c0c6d44b70f961a994898999179cc32d21eb09c1908d7167b00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f2166290e79d" + ], + "endIndex": { + "address": "X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", + "utxo": "kbUThAUfmBXUmRgTpgD6r3nLj7rJUGho6xyht5nouNNypH45j" + }, + "encoding": "hex" + }, + "id": 1 +} +``` + +Since `numFetched` is the same as `limit`, we can tell that there may be more UTXOs that were not +fetched. We call the method again, this time with `startIndex`: + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :2, + "method" :"avm.getUTXOs", + "params" :{ + "addresses":["X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"], + "limit":5, + "startIndex": { + "address": "X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", + "utxo": "kbUThAUfmBXUmRgTpgD6r3nLj7rJUGho6xyht5nouNNypH45j" + }, + "encoding": "hex" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X +``` + +This gives response: + +```json +{ + "jsonrpc": "2.0", + "result": { + "numFetched": "4", + "utxos": [ + "0x000020e182dd51ee4dcd31909fddd75bb3438d9431f8e4efce86a88a684f5c7fa09300000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f21662861d59", + "0x0000a71ba36c475c18eb65dc90f6e85c4fd4a462d51c5de3ac2cbddf47db4d99284e00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f21665f6f83f", + "0x0000925424f61cb13e0fbdecc66e1270de68de9667b85baa3fdc84741d048daa69fa00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216afecf76a", + "0x000082f30327514f819da6009fad92b5dba24d27db01e29ad7541aa8e6b6b554615c00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216779c2d59" + ], + "endIndex": { + "address": "X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", + "utxo": "21jG2RfqyHUUgkTLe2tUp6ETGLriSDTW3th8JXFbPRNiSZ11jK" + }, + "encoding": "hex" + }, + "id": 1 +} +``` + +Since `numFetched` is less than `limit`, we know that we are done fetching UTXOs and don’t need to +call this method again. + +Suppose we want to fetch the UTXOs exported from the P Chain to the X Chain in order to build an +ImportTx. Then we need to call GetUTXOs with the `sourceChain` argument in order to retrieve the +atomic UTXOs: + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"avm.getUTXOs", + "params" :{ + "addresses":["X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", "X-avax1d09qn852zcy03sfc9hay2llmn9hsgnw4tp3dv6"], + "limit":5, + "sourceChain": "P", + "encoding": "hex" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X +``` + +This gives response: + +```json +{ + "jsonrpc": "2.0", + "result": { + "numFetched": "1", + "utxos": [ + "0x00001f989ffaf18a18a59bdfbf209342aa61c6a62a67e8639d02bb3c8ddab315c6fa0000000039c33a499ce4c33a3b09cdd2cfa01ae70dbf2d18b2d7d168524440e55d550088000000070011c304cd7eb5c0000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c83497819" + ], + "endIndex": { + "address": "X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", + "utxo": "2Sz2XwRYqUHwPeiKoRnZ6ht88YqzAF1SQjMYZQQaB5wBFkAqST" + }, + "encoding": "hex" + }, + "id": 1 +} +``` + +### `avm.import` + +:::caution + +Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12). + +::: + +:::warning +Not recommended for use on Mainnet. See warning notice in [Keystore API](/reference/avalanchego/keystore-api.md). +::: + +Finalize a transfer of an asset from the P-Chain or C-Chain to the X-Chain. + +**Signature:** + +```sh +avm.import({ + to: string, + sourceChain: string, + username: string, + password: string, +}) -> {txID: string} +``` + +- `to` is the address the AVAX is sent to. This must be the same as the `to` argument in the + corresponding call to the P-Chain’s `exportAVAX` or C-Chain's `export`. +- `sourceChain` is the ID or alias of the chain the AVAX is being imported from. To import funds + from the C-Chain, use `"C"`. +- `username` is the user that controls `to`. +- `txID` is the ID of the newly created atomic transaction. + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"avm.import", + "params" :{ + "to":"X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", + "sourceChain":"C", + "username":"myUsername", + "password":"myPassword" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "txID": "2gXpf4jFoMAWQ3rxBfavgFfSdLkL2eFUYprKsUQuEdB5H6Jo1H" + }, + "id": 1 +} +``` + + + +### `avm.importKey` + +:::caution + +Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12). + +::: + +:::warning +Not recommended for use on Mainnet. See warning notice in [Keystore API](/reference/avalanchego/keystore-api.md). +::: + +Give a user control over an address by providing the private key that controls the address. + +**Signature:** + +```sh +avm.importKey({ + username: string, + password: string, + privateKey: string +}) -> {address: string} +``` + +- Add `privateKey` to `username`‘s set of private keys. `address` is the address `username` now + controls with the private key. + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"avm.importKey", + "params" :{ + "username":"myUsername", + "password":"myPassword", + "privateKey":"PrivateKey-2w4XiXxPfQK4TypYqnohRL8DRNTz9cGiGmwQ1zmgEqD9c9KWLq" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "address": "X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5" + } +} +``` + +### `avm.issueTx` + +Send a signed transaction to the network. `encoding` specifies the format of the signed transaction. +Can only be `hex` when a value is provided. + +**Signature:** + +```sh +avm.issueTx({ + tx: string, + encoding: string, //optional +}) -> { + txID: string +} +``` + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" : 1, + "method" :"avm.issueTx", + "params" :{ + "tx":"0x00000009de31b4d8b22991d51aa6aa1fc733f23a851a8c9400000000000186a0000000005f041280000000005f9ca900000030390000000000000001fceda8f90fcb5d30614b99d79fc4baa29307762668f16eb0259a57c2d3b78c875c86ec2045792d4df2d926c40f829196e0bb97ee697af71f5b0a966dabff749634c8b729855e937715b0e44303fd1014daedc752006011b730", + "encoding": "hex" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "txID": "NUPLwbt2hsYxpQg4H2o451hmTWQ4JZx2zMzM4SinwtHgAdX1JLPHXvWSXEnpecStLj" + } +} +``` + +### `avm.listAddresses` + +:::caution + +Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12). + +::: + +:::warning +Not recommended for use on Mainnet. See warning notice in [Keystore API](/reference/avalanchego/keystore-api.md). +::: + +List addresses controlled by the given user. + +**Signature:** + +```sh +avm.listAddresses({ + username: string, + password: string +}) -> {addresses: []string} +``` + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc": "2.0", + "method": "avm.listAddresses", + "params": { + "username":"myUsername", + "password":"myPassword" + }, + "id": 1 +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "addresses": ["X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"] + }, + "id": 1 +} +``` + +### `avm.mint` + +:::caution + +Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12). + +::: + +:::warning +Not recommended for use on Mainnet. See warning notice in [Keystore API](/reference/avalanchego/keystore-api.md). +::: + +Mint units of a variable-cap asset created with +[`avm.createVariableCapAsset`](/reference/avalanchego/x-chain/api.md#avmcreatevariablecapasset). + +**Signature:** + +```sh +avm.mint({ + amount: int, + assetID: string, + to: string, + from: []string, //optional + changeAddr: string, //optional + username: string, + password: string +}) -> +{ + txID: string, + changeAddr: string, +} +``` + +- `amount` units of `assetID` will be created and controlled by address `to`. +- `from` are the addresses that you want to use for this operation. If omitted, uses any of your + addresses as needed. +- `changeAddr` is the address any change will be sent to. If omitted, change is sent to one of the + addresses controlled by the user. +- `username` is the user that pays the transaction fee. `username` must hold keys giving it + permission to mint more of this asset. That is, it must control at least _threshold_ keys for one + of the minter sets. +- `txID` is this transaction’s ID. +- `changeAddr` in the result is the address where any change was sent. + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" : 1, + "method" :"avm.mint", + "params" :{ + "amount":10000000, + "assetID":"i1EqsthjiFTxunrj8WD2xFSrQ5p2siEKQacmCCB5qBFVqfSL2", + "to":"X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", + "from":["X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"], + "changeAddr":"X-avax1turszjwn05lflpewurw96rfrd3h6x8flgs5uf8", + "username":"myUsername", + "password":"myPassword" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "txID": "2oGdPdfw2qcNUHeqjw8sU2hPVrFyNUTgn6A8HenDra7oLCDtja", + "changeAddr": "X-avax1turszjwn05lflpewurw96rfrd3h6x8flgs5uf8" + } +} +``` + +### `avm.mintNFT` + +:::caution + +Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12). + +::: + +:::warning +Not recommended for use on Mainnet. See warning notice in [Keystore API](/reference/avalanchego/keystore-api.md). +::: + +Mint non-fungible tokens which were created with +[`avm.createNFTAsset`](/reference/avalanchego/x-chain/api.md#avmcreatenftasset). + +**Signature:** + +```sh +avm.mintNFT({ + assetID: string, + payload: string, + to: string, + encoding: string, //optional + from: []string, //optional + changeAddr: string, //optional + username: string, + password: string +}) -> +{ + txID: string, + changeAddr: string, +} +``` + +- `assetID` is the assetID of the newly created NFT asset. +- `payload` is an arbitrary payload of up to 1024 bytes. Its encoding format is specified by the + `encoding` argument. +- `from` are the addresses that you want to use for this operation. If omitted, uses any of your + addresses as needed. +- `changeAddr` is the address any change will be sent to. If omitted, change is sent to one of the + addresses controlled by the user. +- `username` is the user that pays the transaction fee. `username` must hold keys giving it + permission to mint more of this asset. That is, it must control at least _threshold_ keys for one + of the minter sets. +- `txID` is this transaction’s ID. +- `changeAddr` in the result is the address where any change was sent. +- `encoding` is the encoding format to use for the payload argument. Can only be `hex` when a value + is provided. + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" : 1, + "method" :"avm.mintNFT", + "params" :{ + "assetID":"2KGdt2HpFKpTH5CtGZjYt5XPWs6Pv9DLoRBhiFfntbezdRvZWP", + "payload":"0x415641204c61627338259aed", + "to":"X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", + "from":["X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"], + "changeAddr":"X-avax1turszjwn05lflpewurw96rfrd3h6x8flgs5uf8", + "username":"myUsername", + "password":"myPassword" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "txID": "2oGdPdfw2qcNUHeqjw8sU2hPVrFyNUTgn6A8HenDra7oLCDtja", + "changeAddr": "X-avax1turszjwn05lflpewurw96rfrd3h6x8flgs5uf8" + } +} +``` + +### `avm.send` + +:::caution + +Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12). + +::: + +:::warning +Not recommended for use on Mainnet. See warning notice in [Keystore API](/reference/avalanchego/keystore-api.md). +::: + +Send a quantity of an asset to an address. + +**Signature:** + +```sh +avm.send({ + amount: int, + assetID: string, + to: string, + memo: string, //optional + from: []string, //optional + changeAddr: string, //optional + username: string, + password: string +}) -> {txID: string, changeAddr: string} +``` + +- Sends `amount` units of asset with ID `assetID` to address `to`. `amount` is denominated in the + smallest increment of the asset. For AVAX this is 1 nAVAX (one billionth of 1 AVAX.) +- `to` is the X-Chain address the asset is sent to. +- `from` are the addresses that you want to use for this operation. If omitted, uses any of your + addresses as needed. +- `changeAddr` is the address any change will be sent to. If omitted, change is sent to one of the + addresses controlled by the user. +- You can attach a `memo`, whose length can be up to 256 bytes. +- The asset is sent from addresses controlled by user `username`. (Of course, that user will need to + hold at least the balance of the asset being sent.) + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"avm.send", + "params" :{ + "assetID" : "AVAX", + "amount" : 10000, + "to" : "X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", + "from" : ["X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"], + "changeAddr": "X-avax1turszjwn05lflpewurw96rfrd3h6x8flgs5uf8", + "memo" : "hi, mom!", + "username" : "userThatControlsAtLeast10000OfThisAsset", + "password" : "myPassword" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "txID": "2iXSVLPNVdnFqn65rRvLrsu8WneTFqBJRMqkBJx5vZTwAQb8c1", + "changeAddr": "X-avax1turszjwn05lflpewurw96rfrd3h6x8flgs5uf8" + } +} +``` + +### `avm.sendMultiple` + +:::caution + +Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12). + +::: + +:::warning +Not recommended for use on Mainnet. See warning notice in [Keystore API](/reference/avalanchego/keystore-api.md). +::: + +Sends multiple transfers of `amount` of `assetID`, to a specified address from a list of owned +addresses. + +**Signature:** + +```sh +avm.sendMultiple({ + outputs: []{ + assetID: string, + amount: int, + to: string + }, + from: []string, //optional + changeAddr: string, //optional + memo: string, //optional + username: string, + password: string +}) -> {txID: string, changeAddr: string} +``` + +- `outputs` is an array of object literals which each contain an `assetID`, `amount` and `to`. +- `memo` is an optional message, whose length can be up to 256 bytes. +- `from` are the addresses that you want to use for this operation. If omitted, uses any of your + addresses as needed. +- `changeAddr` is the address any change will be sent to. If omitted, change is sent to one of the + addresses controlled by the user. +- The asset is sent from addresses controlled by user `username`. (Of course, that user will need to + hold at least the balance of the asset being sent.) + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"avm.sendMultiple", + "params" :{ + "outputs": [ + { + "assetID" : "AVAX", + "to" : "X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", + "amount" : 1000000000 + }, + { + "assetID" : "26aqSTpZuWDAVtRmo44fjCx4zW6PDEx3zy9Qtp2ts1MuMFn9FB", + "to" : "X-avax18knvhxx8uhc0mwlgrfyzjcm2wrd6e60w37xrjq", + "amount" : 10 + } + ], + "memo" : "hi, mom!", + "from" : ["X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"], + "changeAddr": "X-avax1turszjwn05lflpewurw96rfrd3h6x8flgs5uf8", + "username" : "username", + "password" : "myPassword" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "txID": "2iXSVLPNVdnFqn65rRvLrsu8WneTFqBJRMqkBJx5vZTwAQb8c1", + "changeAddr": "X-avax1turszjwn05lflpewurw96rfrd3h6x8flgs5uf8" + } +} +``` + +### `avm.sendNFT` + +:::caution + +Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12). + +::: + +:::warning +Not recommended for use on Mainnet. See warning notice in [Keystore API](/reference/avalanchego/keystore-api.md). +::: + +Send a non-fungible token. + +**Signature:** + +```sh +avm.sendNFT({ + assetID: string, + groupID: number, + to: string, + from: []string, //optional + changeAddr: string, //optional + username: string, + password: string +}) -> {txID: string} +``` + +- `assetID` is the asset ID of the NFT being sent. +- `groupID` is the NFT group from which to send the NFT. NFT creation allows multiple groups under + each NFT ID. You can issue multiple NFTs to each group. +- `to` is the X-Chain address the NFT is sent to. +- `from` are the addresses that you want to use for this operation. If omitted, uses any of your + addresses as needed. `changeAddr` is the address any change will be sent to. If omitted, change is + sent to one of the addresses controlled by the user. +- The asset is sent from addresses controlled by user `username`. (Of course, that user will need to + hold at least the balance of the NFT being sent.) + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"avm.sendNFT", + "params" :{ + "assetID" : "2KGdt2HpFKpTH5CtGZjYt5XPWs6Pv9DLoRBhiFfntbezdRvZWP", + "groupID" : 0, + "to" : "X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", + "from" : ["X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"], + "changeAddr": "X-avax1turszjwn05lflpewurw96rfrd3h6x8flgs5uf8", + "username" : "myUsername", + "password" : "myPassword" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "txID": "DoR2UtG1Trd3Q8gWXVevNxD666Q3DPqSFmBSMPQ9dWTV8Qtuy", + "changeAddr": "X-avax1turszjwn05lflpewurw96rfrd3h6x8flgs5uf8" + }, + "id": 1 +} +``` + +### `wallet.issueTx` + +Send a signed transaction to the network and assume the TX will be accepted. `encoding` specifies +the format of the signed transaction. Can only be `hex` when a value is provided. + +This call is made to the wallet API endpoint: + +`/ext/bc/X/wallet` + +:::caution + +Endpoint deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12). + +::: + +**Signature:** + +```sh +wallet.issueTx({ + tx: string, + encoding: string, //optional +}) -> { + txID: string +} +``` + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" : 1, + "method" :"wallet.issueTx", + "params" :{ + "tx":"0x00000009de31b4d8b22991d51aa6aa1fc733f23a851a8c9400000000000186a0000000005f041280000000005f9ca900000030390000000000000001fceda8f90fcb5d30614b99d79fc4baa29307762668f16eb0259a57c2d3b78c875c86ec2045792d4df2d926c40f829196e0bb97ee697af71f5b0a966dabff749634c8b729855e937715b0e44303fd1014daedc752006011b730", + "encoding": "hex" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X/wallet +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "txID": "NUPLwbt2hsYxpQg4H2o451hmTWQ4JZx2zMzM4SinwtHgAdX1JLPHXvWSXEnpecStLj" + } +} +``` + +### `wallet.send` + +:::warning +Not recommended for use on Mainnet. See warning notice in [Keystore API](/reference/avalanchego/keystore-api.md). +::: + +Send a quantity of an asset to an address and assume the TX will be accepted so that future calls +can use the modified UTXO set. + +This call is made to the wallet API endpoint: + +`/ext/bc/X/wallet` + +:::caution + +Endpoint deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12). + +::: + +**Signature:** + +```sh +wallet.send({ + amount: int, + assetID: string, + to: string, + memo: string, //optional + from: []string, //optional + changeAddr: string, //optional + username: string, + password: string +}) -> {txID: string, changeAddr: string} +``` + +- Sends `amount` units of asset with ID `assetID` to address `to`. `amount` is denominated in the + smallest increment of the asset. For AVAX this is 1 nAVAX (one billionth of 1 AVAX.) +- `to` is the X-Chain address the asset is sent to. +- `from` are the addresses that you want to use for this operation. If omitted, uses any of your + addresses as needed. +- `changeAddr` is the address any change will be sent to. If omitted, change is sent to one of the + addresses controlled by the user. +- You can attach a `memo`, whose length can be up to 256 bytes. +- The asset is sent from addresses controlled by user `username`. (Of course, that user will need to + hold at least the balance of the asset being sent.) + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"wallet.send", + "params" :{ + "assetID" : "AVAX", + "amount" : 10000, + "to" : "X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", + "memo" : "hi, mom!", + "from" : ["X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"], + "changeAddr": "X-avax1turszjwn05lflpewurw96rfrd3h6x8flgs5uf8", + "username" : "userThatControlsAtLeast10000OfThisAsset", + "password" : "myPassword" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X/wallet +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "txID": "2iXSVLPNVdnFqn65rRvLrsu8WneTFqBJRMqkBJx5vZTwAQb8c1", + "changeAddr": "X-avax1turszjwn05lflpewurw96rfrd3h6x8flgs5uf8" + } +} +``` + +### `wallet.sendMultiple` + +:::warning +Not recommended for use on Mainnet. See warning notice in [Keystore API](/reference/avalanchego/keystore-api.md). +::: + +Send multiple transfers of `amount` of `assetID`, to a specified address from a list of owned of +addresses and assume the TX will be accepted so that future calls can use the modified UTXO set. + +This call is made to the wallet API endpoint: + +`/ext/bc/X/wallet` + +:::caution + +Endpoint deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12). + +::: + +**Signature:** + +```sh +wallet.sendMultiple({ + outputs: []{ + assetID: string, + amount: int, + to: string + }, + from: []string, //optional + changeAddr: string, //optional + memo: string, //optional + username: string, + password: string +}) -> {txID: string, changeAddr: string} +``` + +- `outputs` is an array of object literals which each contain an `assetID`, `amount` and `to`. +- `from` are the addresses that you want to use for this operation. If omitted, uses any of your + addresses as needed. +- `changeAddr` is the address any change will be sent to. If omitted, change is sent to one of the + addresses controlled by the user. +- You can attach a `memo`, whose length can be up to 256 bytes. +- The asset is sent from addresses controlled by user `username`. (Of course, that user will need to + hold at least the balance of the asset being sent.) + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"wallet.sendMultiple", + "params" :{ + "outputs": [ + { + "assetID" : "AVAX", + "to" : "X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", + "amount" : 1000000000 + }, + { + "assetID" : "26aqSTpZuWDAVtRmo44fjCx4zW6PDEx3zy9Qtp2ts1MuMFn9FB", + "to" : "X-avax18knvhxx8uhc0mwlgrfyzjcm2wrd6e60w37xrjq", + "amount" : 10 + } + ], + "memo" : "hi, mom!", + "from" : ["X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"], + "changeAddr": "X-avax1turszjwn05lflpewurw96rfrd3h6x8flgs5uf8", + "username" : "username", + "password" : "myPassword" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X/wallet +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "txID": "2iXSVLPNVdnFqn65rRvLrsu8WneTFqBJRMqkBJx5vZTwAQb8c1", + "changeAddr": "X-avax1turszjwn05lflpewurw96rfrd3h6x8flgs5uf8" + } +} +``` + +### Events + +Listen for transactions on a specified address. + +This call is made to the events API endpoint: + +`/ext/bc/X/events` + +:::caution + +Endpoint deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12). + +::: + +#### **Golang Example** + +```go +package main + +import ( + "encoding/json" + "log" + "net" + "net/http" + "sync" + + "github.com/ava-labs/avalanchego/api" + "github.com/ava-labs/avalanchego/pubsub" + "github.com/gorilla/websocket" +) + +func main() { + dialer := websocket.Dialer{ + NetDial: func(netw, addr string) (net.Conn, error) { + return net.Dial(netw, addr) + }, + } + + httpHeader := http.Header{} + conn, _, err := dialer.Dial("ws://localhost:9650/ext/bc/X/events", httpHeader) + if err != nil { + panic(err) + } + + waitGroup := &sync.WaitGroup{} + waitGroup.Add(1) + + readMsg := func() { + defer waitGroup.Done() + + for { + mt, msg, err := conn.ReadMessage() + if err != nil { + log.Println(err) + return + } + switch mt { + case websocket.TextMessage: + log.Println(string(msg)) + default: + log.Println(mt, string(msg)) + } + } + } + + go readMsg() + + cmd := &pubsub.Command{NewSet: &pubsub.NewSet{}} + cmdmsg, err := json.Marshal(cmd) + if err != nil { + panic(err) + } + err = conn.WriteMessage(websocket.TextMessage, cmdmsg) + if err != nil { + panic(err) + } + + var addresses []string + addresses = append(addresses, " X-fuji....") + cmd = &pubsub.Command{AddAddresses: &pubsub.AddAddresses{JSONAddresses: api.JSONAddresses{Addresses: addresses}}} + cmdmsg, err = json.Marshal(cmd) + if err != nil { + panic(err) + } + + err = conn.WriteMessage(websocket.TextMessage, cmdmsg) + if err != nil { + panic(err) + } + + waitGroup.Wait() +} +``` + +**Operations:** + +| Command | Description | Example | Arguments | +| :--------------- | :--------------------------- | :------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------- | +| **NewSet** | create a new address map set | `{"newSet":{}}` | | +| **NewBloom** | create a new bloom set. | `{"newBloom":{"maxElements":"1000","collisionProb":"0.0100"}}` | `maxElements` - number of elements in filter must be > 0 `collisionProb` - allowed collision probability must be > 0 and <= 1 | +| **AddAddresses** | add an address to the set | `{"addAddresses":{"addresses":\["X-fuji..."\]}}` | addresses - list of addresses to match | + +Calling **NewSet** or **NewBloom** resets the filter, and must be followed with **AddAddresses**. +**AddAddresses** can be called multiple times. + +**Set details:** + +- **NewSet** performs absolute address matches, if the address is in the set you will be sent the + transaction. +- **NewBloom** [Bloom filtering](https://en.wikipedia.org/wiki/Bloom_filter) can produce false + positives, but can allow a greater number of addresses to be filtered. If the addresses is in the + filter, you will be sent the transaction. + +**Example Response:** + +```json +2021/05/11 15:59:35 {"txID":"22HWKHrREyXyAiDnVmGp3TQQ79tHSSVxA9h26VfDEzoxvwveyk"} +``` diff --git a/vms/platformvm/config/config.md b/vms/platformvm/config/config.md new file mode 100644 index 000000000000..a9058c111ead --- /dev/null +++ b/vms/platformvm/config/config.md @@ -0,0 +1,226 @@ +--- +tags: [Configs] +description: Reference for all available configuration options and parameters for the PlatformVM. +pagination_label: P-Chain Configs +sidebar_position: 1 +--- + +# P-Chain + +This document provides details about the configuration options available for the PlatformVM. + +In order to specify a configuration for the PlatformVM, you need to define a `Config` struct and its parameters. The default values for these parameters are: + +```json +{ + "Chains": null, + "Validators": null, + "UptimeLockedCalculator": null, + "SybilProtectionEnabled": false, + "PartialSyncPrimaryNetwork": false, + "TrackedSubnets": [], + "TxFee": 0, + "CreateAssetTxFee": 0, + "CreateSubnetTxFee": 0, + "TransformSubnetTxFee": 0, + "CreateBlockchainTxFee": 0, + "AddPrimaryNetworkValidatorFee": 0, + "AddPrimaryNetworkDelegatorFee": 0, + "AddSubnetValidatorFee": 0, + "AddSubnetDelegatorFee": 0, + "MinValidatorStake": 0, + "MaxValidatorStake": 0, + "MinDelegatorStake": 0, + "MinDelegationFee": 0, + "UptimePercentage": 0, + "MinStakeDuration": "0s", + "MaxStakeDuration": "0s", + "RewardConfig": {}, + "ApricotPhase3Time": "0001-01-01T00:00:00Z", + "ApricotPhase5Time": "0001-01-01T00:00:00Z", + "BanffTime": "0001-01-01T00:00:00Z", + "CortinaTime": "0001-01-01T00:00:00Z", + "DurangoTime": "0001-01-01T00:00:00Z", + "EUpgradeTime": "0001-01-01T00:00:00Z", + "UseCurrentHeight": false +} +``` + +Default values are overridden only if explicitly specified in the config. + +## Parameters + +The parameters are as follows: + +### `Chains` + +The node's chain manager + +### `Validators` + +Node's validator set maps SubnetID to validators of the Subnet + +- The primary network's validator set should have been added to the manager before calling VM.Initialize. +- The primary network's validator set should be empty before calling VM.Initialize. + +### `UptimeLockedCalculator` + +Provides access to the uptime manager as a thread-safe data structure + +### `SybilProtectionEnabled` + +_Boolean_ + +True if the node is being run with staking enabled + +### `PartialSyncPrimaryNetwork` + +_Boolean_ + +If true, only the P-chain will be instantiated on the primary network. + +### `TrackedSubnets` + +Set of Subnets that this node is validating + +### `TxFee` + +_Uint64_ + +Fee that is burned by every non-state creating transaction + +### `CreateAssetTxFee` + +_Uint64_ + +Fee that must be burned by every state creating transaction before AP3 + +### `CreateSubnetTxFee` + +_Uint64_ + +Fee that must be burned by every Subnet creating transaction after AP3 + +### `TransformSubnetTxFee` + +_Uint64_ + +Fee that must be burned by every transform Subnet transaction + +### `CreateBlockchainTxFee` + +_Uint64_ + +Fee that must be burned by every blockchain creating transaction after AP3 + +### `AddPrimaryNetworkValidatorFee` + +_Uint64_ + +Transaction fee for adding a primary network validator + +### `AddPrimaryNetworkDelegatorFee` + +_Uint64_ + +Transaction fee for adding a primary network delegator + +### `AddSubnetValidatorFee` + +_Uint64_ + +Transaction fee for adding a Subnet validator + +### `AddSubnetDelegatorFee` + +_Uint64_ + +Transaction fee for adding a Subnet delegator + +### `MinValidatorStake` + +_Uint64_ + +The minimum amount of tokens one must bond to be a validator + +### `MaxValidatorStake` + +_Uint64_ + +The maximum amount of tokens that can be bonded on a validator + +### `MinDelegatorStake` + +_Uint64_ + +Minimum stake, in nAVAX, that can be delegated on the primary network + +### `MinDelegationFee` + +_Uint32_ + +Minimum fee that can be charged for delegation + +### `UptimePercentage` + +_Float64_ + +UptimePercentage is the minimum uptime required to be rewarded for staking + +### `MinStakeDuration` + +_Duration_ + +Minimum amount of time to allow a staker to stake + +### `MaxStakeDuration` + +_Duration_ + +Maximum amount of time to allow a staker to stake + +### `RewardConfig` + +Config for the minting function + +### `ApricotPhase3Time` + +_Time_ + +Time of the AP3 network upgrade + +### `ApricotPhase5Time` + +_Time_ + +Time of the AP5 network upgrade + +### `BanffTime` + +_Time_ + +Time of the Banff network upgrade + +### `CortinaTime` + +_Time_ + +Time of the Cortina network upgrade + +### `DurangoTime` + +_Time_ + +Time of the Durango network upgrade + +### `EUpgradeTime` + +_Time_ + +Time of the E network upgrade + +### `UseCurrentHeight` + +_Boolean_ + +UseCurrentHeight forces `GetMinimumHeight` to return the current height of the P-Chain instead of the oldest block in the `recentlyAccepted` window. This config is particularly useful for triggering proposervm activation on recently created Subnets (without this, users need to wait for `recentlyAcceptedWindowTTL` to pass for activation to occur). diff --git a/vms/platformvm/service.md b/vms/platformvm/service.md new file mode 100644 index 000000000000..b6005a8f1569 --- /dev/null +++ b/vms/platformvm/service.md @@ -0,0 +1,1983 @@ +--- +tags: [P-Chain, Platform Chain, AvalancheGo APIs] +description: This page is an overview of the P-Chain API associated with AvalancheGo. +sidebar_label: API +pagination_label: P-Chain Transaction Format +--- + +# Platform Chain API + +This API allows clients to interact with the +[P-Chain](/learn/avalanche/avalanche-platform.md#p-chain), which +maintains Avalanche’s [validator](/nodes/validate/how-to-stake#validators) set and handles +blockchain creation. + +## Endpoint + +```sh +/ext/bc/P +``` + +## Format + +This API uses the `json 2.0` RPC format. + +## Methods + +### `platform.exportKey` + +:::caution + +Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12). + +::: + +:::warning + +Not recommended for use on Mainnet. See warning notice in [Keystore API](/reference/avalanchego/keystore-api.md). + +::: + +Get the private key that controls a given address. + +**Signature:** + +```sh +platform.exportKey({ + username: string, + password: string, + address: string +}) -> {privateKey: string} +``` + +- `username` is the user that controls `address`. +- `password` is `username`‘s password. +- `privateKey` is the string representation of the private key that controls `address`. + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"platform.exportKey", + "params" :{ + "username" :"myUsername", + "password": "myPassword", + "address": "P-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "privateKey": "PrivateKey-Lf49kAJw3CbaL783vmbeAJvhscJqC7vi5yBYLxw2XfbzNS5RS" + } +} +``` + +### `platform.getBalance` + +:::caution + +Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12). + +::: + +Get the balance of AVAX controlled by a given address. + +**Signature:** + +```sh +platform.getBalance({ + addresses: []string +}) -> { + balances: string -> int, + unlockeds: string -> int, + lockedStakeables: string -> int, + lockedNotStakeables: string -> int, + utxoIDs: []{ + txID: string, + outputIndex: int + } +} +``` + +- `addresses` are the addresses to get the balance of. +- `balances` is a map from assetID to the total balance. +- `unlockeds` is a map from assetID to the unlocked balance. +- `lockedStakeables` is a map from assetID to the locked stakeable balance. +- `lockedNotStakeables` is a map from assetID to the locked and not stakeable balance. +- `utxoIDs` are the IDs of the UTXOs that reference `address`. + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" : 1, + "method" :"platform.getBalance", + "params" :{ + "addresses":["P-custom18jma8ppw3nhx5r4ap8clazz0dps7rv5u9xde7p"] + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "balance": "30000000000000000", + "unlocked": "20000000000000000", + "lockedStakeable": "10000000000000000", + "lockedNotStakeable": "0", + "balances": { + "BUuypiq2wyuLMvyhzFXcPyxPMCgSp7eeDohhQRqTChoBjKziC": "30000000000000000" + }, + "unlockeds": { + "BUuypiq2wyuLMvyhzFXcPyxPMCgSp7eeDohhQRqTChoBjKziC": "20000000000000000" + }, + "lockedStakeables": { + "BUuypiq2wyuLMvyhzFXcPyxPMCgSp7eeDohhQRqTChoBjKziC": "10000000000000000" + }, + "lockedNotStakeables": {}, + "utxoIDs": [ + { + "txID": "11111111111111111111111111111111LpoYY", + "outputIndex": 1 + }, + { + "txID": "11111111111111111111111111111111LpoYY", + "outputIndex": 0 + } + ] + }, + "id": 1 +} +``` + +### `platform.getBlock` + +Get a block by its ID. + +**Signature:** + +```sh +platform.getBlock({ + blockID: string + encoding: string // optional +}) -> { + block: string, + encoding: string +} +``` + +**Request:** + +- `blockID` is the block ID. It should be in cb58 format. +- `encoding` is the encoding format to use. Can be either `hex` or `json`. Defaults to `hex`. + +**Response:** + +- `block` is the block encoded to `encoding`. +- `encoding` is the `encoding`. + +#### Hex Example + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc": "2.0", + "method": "platform.getBlock", + "params": { + "blockID": "d7WYmb8VeZNHsny3EJCwMm6QA37s1EHwMxw1Y71V3FqPZ5EFG", + "encoding": "hex" + }, + "id": 1 +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "block": "0x00000000000309473dc99a0851a29174d84e522da8ccb1a56ac23f7b0ba79f80acce34cf576900000000000f4241000000010000001200000001000000000000000000000000000000000000000000000000000000000000000000000000000000011c4c57e1bcb3c567f9f03caa75563502d1a21393173c06d9d79ea247b20e24800000000021e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000050000000338e0465f0000000100000000000000000427d4b22a2a78bcddd456742caf91b56badbff985ee19aef14573e7343fd6520000000121e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000070000000338d1041f0000000000000000000000010000000195a4467dd8f939554ea4e6501c08294386938cbf000000010000000900000001c79711c4b48dcde205b63603efef7c61773a0eb47efb503fcebe40d21962b7c25ebd734057400a12cce9cf99aceec8462923d5d91fffe1cb908372281ed738580119286dde", + "encoding": "hex" + }, + "id": 1 +} +``` + +#### JSON Example + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc": "2.0", + "method": "platform.getBlock", + "params": { + "blockID": "d7WYmb8VeZNHsny3EJCwMm6QA37s1EHwMxw1Y71V3FqPZ5EFG", + "encoding": "json" + }, + "id": 1 +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "block": { + "parentID": "5615di9ytxujackzaXNrVuWQy5y8Yrt8chPCscMr5Ku9YxJ1S", + "height": 1000001, + "txs": [ + { + "unsignedTx": { + "inputs": { + "networkID": 1, + "blockchainID": "11111111111111111111111111111111LpoYY", + "outputs": [], + "inputs": [ + { + "txID": "DTqiagiMFdqbNQ62V2Gt1GddTVLkKUk2caGr4pyza9hTtsfta", + "outputIndex": 0, + "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z", + "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ", + "input": { + "amount": 13839124063, + "signatureIndices": [0] + } + } + ], + "memo": "0x" + }, + "destinationChain": "2q9e4r6Mu3U68nU1fYjgbR6JvwrRx36CohpAX5UQxse55x1Q5", + "exportedOutputs": [ + { + "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z", + "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ", + "output": { + "addresses": [ + "P-avax1jkjyvlwclyu42n4yuegpczpfgwrf8r9lyj0d3c" + ], + "amount": 13838124063, + "locktime": 0, + "threshold": 1 + } + } + ] + }, + "credentials": [ + { + "signatures": [ + "0xc79711c4b48dcde205b63603efef7c61773a0eb47efb503fcebe40d21962b7c25ebd734057400a12cce9cf99aceec8462923d5d91fffe1cb908372281ed7385801" + ] + } + ] + } + ] + }, + "encoding": "json" + }, + "id": 1 +} +``` + +### `platform.getBlockByHeight` + +Get a block by its height. + +**Signature:** + +```sh +platform.getBlockByHeight({ + height: int + encoding: string // optional +}) -> { + block: string, + encoding: string +} +``` + +**Request:** + +- `height` is the block height. +- `encoding` is the encoding format to use. Can be either `hex` or `json`. Defaults to `hex`. + +**Response:** + +- `block` is the block encoded to `encoding`. +- `encoding` is the `encoding`. + +#### Hex Example + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc": "2.0", + "method": "platform.getBlockByHeight", + "params": { + "height": 1000001, + "encoding": "hex" + }, + "id": 1 +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "block": "0x00000000000309473dc99a0851a29174d84e522da8ccb1a56ac23f7b0ba79f80acce34cf576900000000000f4241000000010000001200000001000000000000000000000000000000000000000000000000000000000000000000000000000000011c4c57e1bcb3c567f9f03caa75563502d1a21393173c06d9d79ea247b20e24800000000021e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000050000000338e0465f0000000100000000000000000427d4b22a2a78bcddd456742caf91b56badbff985ee19aef14573e7343fd6520000000121e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000070000000338d1041f0000000000000000000000010000000195a4467dd8f939554ea4e6501c08294386938cbf000000010000000900000001c79711c4b48dcde205b63603efef7c61773a0eb47efb503fcebe40d21962b7c25ebd734057400a12cce9cf99aceec8462923d5d91fffe1cb908372281ed738580119286dde", + "encoding": "hex" + }, + "id": 1 +} +``` + +#### JSON Example + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc": "2.0", + "method": "platform.getBlockByHeight", + "params": { + "height": 1000001, + "encoding": "json" + }, + "id": 1 +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "block": { + "parentID": "5615di9ytxujackzaXNrVuWQy5y8Yrt8chPCscMr5Ku9YxJ1S", + "height": 1000001, + "txs": [ + { + "unsignedTx": { + "inputs": { + "networkID": 1, + "blockchainID": "11111111111111111111111111111111LpoYY", + "outputs": [], + "inputs": [ + { + "txID": "DTqiagiMFdqbNQ62V2Gt1GddTVLkKUk2caGr4pyza9hTtsfta", + "outputIndex": 0, + "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z", + "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ", + "input": { + "amount": 13839124063, + "signatureIndices": [0] + } + } + ], + "memo": "0x" + }, + "destinationChain": "2q9e4r6Mu3U68nU1fYjgbR6JvwrRx36CohpAX5UQxse55x1Q5", + "exportedOutputs": [ + { + "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z", + "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ", + "output": { + "addresses": [ + "P-avax1jkjyvlwclyu42n4yuegpczpfgwrf8r9lyj0d3c" + ], + "amount": 13838124063, + "locktime": 0, + "threshold": 1 + } + } + ] + }, + "credentials": [ + { + "signatures": [ + "0xc79711c4b48dcde205b63603efef7c61773a0eb47efb503fcebe40d21962b7c25ebd734057400a12cce9cf99aceec8462923d5d91fffe1cb908372281ed7385801" + ] + } + ] + } + ] + }, + "encoding": "json" + }, + "id": 1 +} +``` + +### `platform.getBlockchains` + +:::caution + +Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12). + +::: + +Get all the blockchains that exist (excluding the P-Chain). + +**Signature:** + +```sh +platform.getBlockchains() -> +{ + blockchains: []{ + id: string, + name:string, + subnetID: string, + vmID: string + } +} +``` + +- `blockchains` is all of the blockchains that exists on the Avalanche network. +- `name` is the human-readable name of this blockchain. +- `id` is the blockchain’s ID. +- `subnetID` is the ID of the Subnet that validates this blockchain. +- `vmID` is the ID of the Virtual Machine the blockchain runs. + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc": "2.0", + "method": "platform.getBlockchains", + "params": {}, + "id": 1 +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "blockchains": [ + { + "id": "2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM", + "name": "X-Chain", + "subnetID": "11111111111111111111111111111111LpoYY", + "vmID": "jvYyfQTxGMJLuGWa55kdP2p2zSUYsQ5Raupu4TW34ZAUBAbtq" + }, + { + "id": "2q9e4r6Mu3U68nU1fYjgbR6JvwrRx36CohpAX5UQxse55x1Q5", + "name": "C-Chain", + "subnetID": "11111111111111111111111111111111LpoYY", + "vmID": "mgj786NP7uDwBCcq6YwThhaN8FLyybkCa4zBWTQbNgmK6k9A6" + }, + { + "id": "CqhF97NNugqYLiGaQJ2xckfmkEr8uNeGG5TQbyGcgnZ5ahQwa", + "name": "Simple DAG Payments", + "subnetID": "11111111111111111111111111111111LpoYY", + "vmID": "sqjdyTKUSrQs1YmKDTUbdUhdstSdtRTGRbUn8sqK8B6pkZkz1" + }, + { + "id": "VcqKNBJsYanhVFxGyQE5CyNVYxL3ZFD7cnKptKWeVikJKQkjv", + "name": "Simple Chain Payments", + "subnetID": "11111111111111111111111111111111LpoYY", + "vmID": "sqjchUjzDqDfBPGjfQq2tXW1UCwZTyvzAWHsNzF2cb1eVHt6w" + }, + { + "id": "2SMYrx4Dj6QqCEA3WjnUTYEFSnpqVTwyV3GPNgQqQZbBbFgoJX", + "name": "Simple Timestamp Server", + "subnetID": "11111111111111111111111111111111LpoYY", + "vmID": "tGas3T58KzdjLHhBDMnH2TvrddhqTji5iZAMZ3RXs2NLpSnhH" + }, + { + "id": "KDYHHKjM4yTJTT8H8qPs5KXzE6gQH5TZrmP1qVr1P6qECj3XN", + "name": "My new timestamp", + "subnetID": "2bRCr6B4MiEfSjidDwxDpdCyviwnfUVqB2HGwhm947w9YYqb7r", + "vmID": "tGas3T58KzdjLHhBDMnH2TvrddhqTji5iZAMZ3RXs2NLpSnhH" + }, + { + "id": "2TtHFqEAAJ6b33dromYMqfgavGPF3iCpdG3hwNMiart2aB5QHi", + "name": "My new AVM", + "subnetID": "2bRCr6B4MiEfSjidDwxDpdCyviwnfUVqB2HGwhm947w9YYqb7r", + "vmID": "jvYyfQTxGMJLuGWa55kdP2p2zSUYsQ5Raupu4TW34ZAUBAbtq" + } + ] + }, + "id": 1 +} +``` + +### `platform.getBlockchainStatus` + +Get the status of a blockchain. + +**Signature:** + +```sh +platform.getBlockchainStatus( + { + blockchainID: string + } +) -> {status: string} +``` + +`status` is one of: + +- `Validating`: The blockchain is being validated by this node. +- `Created`: The blockchain exists but isn’t being validated by this node. +- `Preferred`: The blockchain was proposed to be created and is likely to be created but the + transaction isn’t yet accepted. +- `Syncing`: This node is participating in this blockchain as a non-validating node. +- `Unknown`: The blockchain either wasn’t proposed or the proposal to create it isn’t preferred. The + proposal may be resubmitted. + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc": "2.0", + "method": "platform.getBlockchainStatus", + "params":{ + "blockchainID":"2NbS4dwGaf2p1MaXb65PrkZdXRwmSX4ZzGnUu7jm3aykgThuZE" + }, + "id": 1 +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "status": "Created" + }, + "id": 1 +} +``` + +### `platform.getCurrentSupply` + +Returns an upper bound on amount of tokens that exist that can stake the requested Subnet. This is +an upper bound because it does not account for burnt tokens, including transaction fees. + +**Signature:** + +```sh +platform.getCurrentSupply({ + subnetID: string // optional +}) -> {supply: int} +``` + +- `supply` is an upper bound on the number of tokens that exist. + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc": "2.0", + "method": "platform.getCurrentSupply", + "params": { + "subnetID": "11111111111111111111111111111111LpoYY" + }, + "id": 1 +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "supply": "365865167637779183" + }, + "id": 1 +} +``` + +The response in this example indicates that AVAX’s supply is at most 365.865 million. + +### `platform.getCurrentValidators` + +List the current validators of the given Subnet. + +**Signature:** + +```sh +platform.getCurrentValidators({ + subnetID: string, // optional + nodeIDs: string[], // optional +}) -> { + validators: []{ + txID: string, + startTime: string, + endTime: string, + stakeAmount: string, + nodeID: string, + weight: string, + validationRewardOwner: { + locktime: string, + threshold: string, + addresses: string[] + }, + delegationRewardOwner: { + locktime: string, + threshold: string, + addresses: string[] + }, + potentialReward: string, + delegationFee: string, + uptime: string, + connected: bool, + signer: { + publicKey: string, + proofOfPosession: string + }, + delegatorCount: string, + delegatorWeight: string, + delegators: []{ + txID: string, + startTime: string, + endTime: string, + stakeAmount: string, + nodeID: string, + rewardOwner: { + locktime: string, + threshold: string, + addresses: string[] + }, + potentialReward: string, + } + } +} +``` + +- `subnetID` is the Subnet whose current validators are returned. If omitted, returns the current + validators of the Primary Network. +- `nodeIDs` is a list of the NodeIDs of current validators to request. If omitted, all current + validators are returned. If a specified NodeID is not in the set of current validators, it will + not be included in the response. +- `validators`: + - `txID` is the validator transaction. + - `startTime` is the Unix time when the validator starts validating the Subnet. + - `endTime` is the Unix time when the validator stops validating the Subnet. + - `stakeAmount` is the amount of tokens this validator staked. Omitted if `subnetID` is not a PoS + Subnet. + - `nodeID` is the validator’s node ID. + - `weight` is the validator’s weight when sampling validators. Omitted if `subnetID` is a PoS + Subnet. + - `validationRewardOwner` is an `OutputOwners` output which includes `locktime`, `threshold` and + array of `addresses`. Specifies the owner of the potential reward earned from staking. Omitted + if `subnetID` is not a PoS Subnet. + - `delegationRewardOwner` is an `OutputOwners` output which includes `locktime`, `threshold` and + array of `addresses`. Specifies the owner of the potential reward earned from delegations. + Omitted if `subnetID` is not a PoS Subnet. + - `potentialReward` is the potential reward earned from staking. Omitted if `subnetID` is not a + PoS Subnet. + - `delegationFeeRate` is the percent fee this validator charges when others delegate stake to + them. Omitted if `subnetID` is not a PoS Subnet. + - `uptime` is the % of time the queried node has reported the peer as online and validating the + Subnet. Omitted if `subnetID` is not a PoS Subnet. + - `connected` is if the node is connected and tracks the Subnet. + - `signer` is the node's BLS public key and proof of possession. Omitted if the validator doesn't + have a BLS public key. + - `delegatorCount` is the number of delegators on this validator. + Omitted if `subnetID` is not a PoS Subnet. + - `delegatorWeight` is total weight of delegators on this validator. + Omitted if `subnetID` is not a PoS Subnet. + - `delegators` is the list of delegators to this validator. + Omitted if `subnetID` is not a PoS Subnet. + Omitted unless `nodeIDs` specifies a single NodeID. + - `txID` is the delegator transaction. + - `startTime` is the Unix time when the delegator started. + - `endTime` is the Unix time when the delegator stops. + - `stakeAmount` is the amount of nAVAX this delegator staked. + - `nodeID` is the validating node’s node ID. + - `rewardOwner` is an `OutputOwners` output which includes `locktime`, `threshold` and array of + `addresses`. + - `potentialReward` is the potential reward earned from staking + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc": "2.0", + "method": "platform.getCurrentValidators", + "params": { + "nodeIDs": ["NodeID-5mb46qkSBj81k9g9e4VFjGGSbaaSLFRzD"] + }, + "id": 1 +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "validators": [ + { + "txID": "2NNkpYTGfTFLSGXJcHtVv6drwVU2cczhmjK2uhvwDyxwsjzZMm", + "startTime": "1600368632", + "endTime": "1602960455", + "stakeAmount": "2000000000000", + "nodeID": "NodeID-5mb46qkSBj81k9g9e4VFjGGSbaaSLFRzD", + "validationRewardOwner": { + "locktime": "0", + "threshold": "1", + "addresses": ["P-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"] + }, + "delegationRewardOwner": { + "locktime": "0", + "threshold": "1", + "addresses": ["P-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"] + }, + "potentialReward": "117431493426", + "delegationFee": "10.0000", + "uptime": "0.0000", + "connected": false, + "delegatorCount": "1", + "delegatorWeight": "25000000000", + "delegators": [ + { + "txID": "Bbai8nzGVcyn2VmeYcbS74zfjJLjDacGNVuzuvAQkHn1uWfoV", + "startTime": "1600368523", + "endTime": "1602960342", + "stakeAmount": "25000000000", + "nodeID": "NodeID-5mb46qkSBj81k9g9e4VFjGGSbaaSLFRzD", + "rewardOwner": { + "locktime": "0", + "threshold": "1", + "addresses": ["P-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"] + }, + "potentialReward": "11743144774" + } + ] + } + ] + }, + "id": 1 +} +``` + +### `platform.getHeight` + +Returns the height of the last accepted block. + +**Signature:** + +```sh +platform.getHeight() -> +{ + height: int, +} +``` + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc": "2.0", + "method": "platform.getHeight", + "params": {}, + "id": 1 +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "height": "56" + }, + "id": 1 +} +``` + +### `platform.getMaxStakeAmount` + +:::caution + +Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12). + +::: + +Returns the maximum amount of nAVAX staking to the named node during a particular time period. + +**Signature:** + +```sh +platform.getMaxStakeAmount( + { + subnetID: string, + nodeID: string, + startTime: int, + endTime: int + } +) -> +{ + amount: uint64 +} +``` + +- `subnetID` is a Buffer or cb58 string representing Subnet +- `nodeID` is a string representing ID of the node whose stake amount is required during the given + duration +- `startTime` is a big number denoting start time of the duration during which stake amount of the + node is required. +- `endTime` is a big number denoting end time of the duration during which stake amount of the node + is required. + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc": "2.0", + "method": "platform.getMaxStakeAmount", + "params": { + "subnetID":"11111111111111111111111111111111LpoYY", + "nodeID":"NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg", + "startTime": 1644240334, + "endTime": 1644240634 + }, + "id": 1 +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "amount": "2000000000000000" + }, + "id": 1 +} +``` + +### `platform.getMinStake` + +Get the minimum amount of tokens required to validate the requested Subnet and the minimum amount of +tokens that can be delegated. + +**Signature:** + +```sh +platform.getMinStake({ + subnetID: string // optional +}) -> +{ + minValidatorStake : uint64, + minDelegatorStake : uint64 +} +``` + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"platform.getMinStake", + "params": { + "subnetID":"11111111111111111111111111111111LpoYY" + }, +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "minValidatorStake": "2000000000000", + "minDelegatorStake": "25000000000" + }, + "id": 1 +} +``` + +### `platform.getPendingValidators` + +List the validators in the pending validator set of the specified Subnet. Each validator is not +currently validating the Subnet but will in the future. + +**Signature:** + +```sh +platform.getPendingValidators({ + subnetID: string, // optional + nodeIDs: string[], // optional +}) -> { + validators: []{ + txID: string, + startTime: string, + endTime: string, + stakeAmount: string, + nodeID: string, + delegationFee: string, + connected: bool, + signer: { + publicKey: string, + proofOfPosession: string + }, + weight: string, + }, + delegators: []{ + txID: string, + startTime: string, + endTime: string, + stakeAmount: string, + nodeID: string + } +} +``` + +- `subnetID` is the Subnet whose current validators are returned. If omitted, returns the current + validators of the Primary Network. +- `nodeIDs` is a list of the NodeIDs of pending validators to request. If omitted, all pending + validators are returned. If a specified NodeID is not in the set of pending validators, it will + not be included in the response. +- `validators`: + - `txID` is the validator transaction. + - `startTime` is the Unix time when the validator starts validating the Subnet. + - `endTime` is the Unix time when the validator stops validating the Subnet. + - `stakeAmount` is the amount of tokens this validator staked. Omitted if `subnetID` is not a PoS + Subnet. + - `nodeID` is the validator’s node ID. + - `connected` if the node is connected and tracks the Subnet. + - `signer` is the node's BLS public key and proof of possession. Omitted if the validator doesn't + have a BLS public key. + - `weight` is the validator’s weight when sampling validators. Omitted if `subnetID` is a PoS + Subnet. +- `delegators`: + - `txID` is the delegator transaction. + - `startTime` is the Unix time when the delegator starts. + - `endTime` is the Unix time when the delegator stops. + - `stakeAmount` is the amount of tokens this delegator staked. + - `nodeID` is the validating node’s node ID. + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc": "2.0", + "method": "platform.getPendingValidators", + "params": {}, + "id": 1 +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "validators": [ + { + "txID": "2NNkpYTGfTFLSGXJcHtVv6drwVU2cczhmjK2uhvwDyxwsjzZMm", + "startTime": "1600368632", + "endTime": "1602960455", + "stakeAmount": "200000000000", + "nodeID": "NodeID-5mb46qkSBj81k9g9e4VFjGGSbaaSLFRzD", + "delegationFee": "10.0000", + "connected": false + } + ], + "delegators": [ + { + "txID": "Bbai8nzGVcyn2VmeYcbS74zfjJLjDacGNVuzuvAQkHn1uWfoV", + "startTime": "1600368523", + "endTime": "1602960342", + "stakeAmount": "20000000000", + "nodeID": "NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg" + } + ] + }, + "id": 1 +} +``` + +### `platform.getRewardUTXOs` + +:::caution + +Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12). + +::: + +Returns the UTXOs that were rewarded after the provided transaction's staking or delegation period +ended. + +**Signature:** + +```sh +platform.getRewardUTXOs({ + txID: string, + encoding: string // optional +}) -> { + numFetched: integer, + utxos: []string, + encoding: string +} +``` + +- `txID` is the ID of the staking or delegating transaction +- `numFetched` is the number of returned UTXOs +- `utxos` is an array of encoded reward UTXOs +- `encoding` specifies the format for the returned UTXOs. Can only be `hex` when a value is + provided. + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc": "2.0", + "method": "platform.getRewardUTXOs", + "params": { + "txID": "2nmH8LithVbdjaXsxVQCQfXtzN9hBbmebrsaEYnLM9T32Uy2Y5" + }, + "id": 1 +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "numFetched": "2", + "utxos": [ + "0x0000a195046108a85e60f7a864bb567745a37f50c6af282103e47cc62f036cee404700000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216c1f01765", + "0x0000ae8b1b94444eed8de9a81b1222f00f1b4133330add23d8ac288bffa98b85271100000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216473d042a" + ], + "encoding": "hex" + }, + "id": 1 +} +``` + +### `platform.getStake` + +:::caution + +Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12). + +::: + +Get the amount of nAVAX staked by a set of addresses. The amount returned does not include staking +rewards. + +**Signature:** + +```sh +platform.getStake({ + addresses: []string, + validatorsOnly: true or false +}) -> +{ + stakeds: string -> int, + stakedOutputs: []string, + encoding: string +} +``` + +- `addresses` are the addresses to get information about. +- `validatorsOnly` can be either `true` or `false`. If `true`, will skip checking delegators for stake. +- `stakeds` is a map from assetID to the amount staked by addresses provided. +- `stakedOutputs` are the string representation of staked outputs. +- `encoding` specifies the format for the returned outputs. + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc": "2.0", + "method": "platform.getStake", + "params": { + "addresses": [ + "P-avax1pmgmagjcljjzuz2ve339dx82khm7q8getlegte" + ], + "validatorsOnly": true + }, + "id": 1 +} +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "staked": "6500000000000", + "stakeds": { + "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z": "6500000000000" + }, + "stakedOutputs": [ + "0x000021e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff00000007000005e96630e800000000000000000000000001000000011f1c933f38da6ba0ba46f8c1b0a7040a9a991a80dd338ed1" + ], + "encoding": "hex" + }, + "id": 1 +} +``` + +### `platform.getStakingAssetID` + +Retrieve an assetID for a Subnet’s staking asset. + +**Signature:** + +```sh +platform.getStakingAssetID({ + subnetID: string // optional +}) -> { + assetID: string +} +``` + +- `subnetID` is the Subnet whose assetID is requested. +- `assetID` is the assetID for a Subnet’s staking asset. + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc": "2.0", + "method": "platform.getStakingAssetID", + "params": { + "subnetID": "11111111111111111111111111111111LpoYY" + }, + "id": 1 +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "assetID": "2fombhL7aGPwj3KH4bfrmJwW6PVnMobf9Y2fn9GwxiAAJyFDbe" + }, + "id": 1 +} +``` + +:::note + +The AssetID for AVAX differs depending on the network you are on. + +Mainnet: FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z + +Testnet: U8iRqJoiJm8xZHAacmvYyZVwqQx6uDNtQeP3CQ6fcgQk3JqnK + +::: + +### `platform.getSubnets` + +:::caution + +Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12). + +::: + +Get info about the Subnets. + +**Signature:** + +```sh +platform.getSubnets({ + ids: []string +}) -> +{ + subnets: []{ + id: string, + controlKeys: []string, + threshold: string + } +} +``` + +- `ids` are the IDs of the Subnets to get information about. If omitted, gets information about all + Subnets. +- `id` is the Subnet’s ID. +- `threshold` signatures from addresses in `controlKeys` are needed to add a validator to the + Subnet. If the Subnet is a PoS Subnet, then `threshold` will be `0` and `controlKeys` will be + empty. + +See [here](/nodes/validate/add-a-validator.md) for information on adding a validator to a +Subnet. + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc": "2.0", + "method": "platform.getSubnets", + "params": {"ids":["hW8Ma7dLMA7o4xmJf3AXBbo17bXzE7xnThUd3ypM4VAWo1sNJ"]}, + "id": 1 +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "subnets": [ + { + "id": "hW8Ma7dLMA7o4xmJf3AXBbo17bXzE7xnThUd3ypM4VAWo1sNJ", + "controlKeys": [ + "KNjXsaA1sZsaKCD1cd85YXauDuxshTes2", + "Aiz4eEt5xv9t4NCnAWaQJFNz5ABqLtJkR" + ], + "threshold": "2" + } + ] + }, + "id": 1 +} +``` + +### `platform.getTimestamp` + +Get the current P-Chain timestamp. + +**Signature:** + +```sh +platform.getTimestamp() -> {time: string} +``` + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc": "2.0", + "method": "platform.getTimestamp", + "params": {}, + "id": 1 +} +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "timestamp": "2021-09-07T00:00:00-04:00" + }, + "id": 1 +} +``` + +### `platform.getTotalStake` + +Get the total amount of tokens staked on the requested Subnet. + +**Signature:** + +```sh +platform.getTotalStake({ + subnetID: string +}) -> { + stake: int + weight: int +} +``` + +#### Primary Network Example + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc": "2.0", + "method": "platform.getTotalStake", + "params": { + "subnetID": "11111111111111111111111111111111LpoYY" + }, + "id": 1 +} +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "stake": "279825917679866811", + "weight": "279825917679866811" + }, + "id": 1 +} +``` + +#### Subnet Example + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc": "2.0", + "method": "platform.getTotalStake", + "params": { + "subnetID": "2bRCr6B4MiEfSjidDwxDpdCyviwnfUVqB2HGwhm947w9YYqb7r", + }, + "id": 1 +} +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/P +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "weight": "100000" + }, + "id": 1 +} +``` + +### `platform.getTx` + +Gets a transaction by its ID. + +Optional `encoding` parameter to specify the format for the returned transaction. Can be either +`hex` or `json`. Defaults to `hex`. + +**Signature:** + +```sh +platform.getTx({ + txID: string, + encoding: string // optional +}) -> { + tx: string, + encoding: string, +} +``` + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc": "2.0", + "method": "platform.getTx", + "params": { + "txID":"28KVjSw5h3XKGuNpJXWY74EdnGq4TUWvCgEtJPymgQTvudiugb", + "encoding": "json" + }, + "id": 1 +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "tx": { + "unsignedTx": { + "networkID": 1, + "blockchainID": "11111111111111111111111111111111LpoYY", + "outputs": [], + "inputs": [ + { + "txID": "NXNJHKeaJyjjWVSq341t6LGQP5UNz796o1crpHPByv1TKp9ZP", + "outputIndex": 0, + "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z", + "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ", + "input": { + "amount": 20824279595, + "signatureIndices": [0] + } + }, + { + "txID": "2ahK5SzD8iqi5KBqpKfxrnWtrEoVwQCqJsMoB9kvChCaHgAQC9", + "outputIndex": 1, + "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z", + "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ", + "input": { + "amount": 28119890783, + "signatureIndices": [0] + } + } + ], + "memo": "0x", + "validator": { + "nodeID": "NodeID-VT3YhgFaWEzy4Ap937qMeNEDscCammzG", + "start": 1682945406, + "end": 1684155006, + "weight": 48944170378 + }, + "stake": [ + { + "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z", + "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ", + "output": { + "addresses": ["P-avax1tnuesf6cqwnjw7fxjyk7lhch0vhf0v95wj5jvy"], + "amount": 48944170378, + "locktime": 0, + "threshold": 1 + } + } + ], + "rewardsOwner": { + "addresses": ["P-avax19zfygxaf59stehzedhxjesads0p5jdvfeedal0"], + "locktime": 0, + "threshold": 1 + } + }, + "credentials": [ + { + "signatures": [ + "0x6954e90b98437646fde0c1d54c12190fc23ae5e319c4d95dda56b53b4a23e43825251289cdc3728f1f1e0d48eac20e5c8f097baa9b49ea8a3cb6a41bb272d16601" + ] + }, + { + "signatures": [ + "0x6954e90b98437646fde0c1d54c12190fc23ae5e319c4d95dda56b53b4a23e43825251289cdc3728f1f1e0d48eac20e5c8f097baa9b49ea8a3cb6a41bb272d16601" + ] + } + ], + "id": "28KVjSw5h3XKGuNpJXWY74EdnGq4TUWvCgEtJPymgQTvudiugb" + }, + "encoding": "json" + }, + "id": 1 +} +``` + +### `platform.getTxStatus` + +Gets a transaction’s status by its ID. If the transaction was dropped, response will include a +`reason` field with more information why the transaction was dropped. + +**Signature:** + +```sh +platform.getTxStatus({ + txID: string +}) -> {status: string} +``` + +`status` is one of: + +- `Committed`: The transaction is (or will be) accepted by every node +- `Processing`: The transaction is being voted on by this node +- `Dropped`: The transaction will never be accepted by any node in the network, check `reason` field + for more information +- `Unknown`: The transaction hasn’t been seen by this node + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc": "2.0", + "method": "platform.getTxStatus", + "params": { + "txID":"TAG9Ns1sa723mZy1GSoGqWipK6Mvpaj7CAswVJGM6MkVJDF9Q" + }, + "id": 1 +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "status": "Committed" + }, + "id": 1 +} +``` + +### `platform.getUTXOs` + +Gets the UTXOs that reference a given set of addresses. + +**Signature:** + +```sh +platform.getUTXOs( + { + addresses: []string, + limit: int, // optional + startIndex: { // optional + address: string, + utxo: string + }, + sourceChain: string, // optional + encoding: string, // optional + }, +) -> +{ + numFetched: int, + utxos: []string, + endIndex: { + address: string, + utxo: string + }, + encoding: string, +} +``` + +- `utxos` is a list of UTXOs such that each UTXO references at least one address in `addresses`. +- At most `limit` UTXOs are returned. If `limit` is omitted or greater than 1024, it is set to 1024. +- This method supports pagination. `endIndex` denotes the last UTXO returned. To get the next set of + UTXOs, use the value of `endIndex` as `startIndex` in the next call. +- If `startIndex` is omitted, will fetch all UTXOs up to `limit`. +- When using pagination (that is when `startIndex` is provided), UTXOs are not guaranteed to be unique + across multiple calls. That is, a UTXO may appear in the result of the first call, and then again + in the second call. +- When using pagination, consistency is not guaranteed across multiple calls. That is, the UTXO set + of the addresses may have changed between calls. +- `encoding` specifies the format for the returned UTXOs. Can only be `hex` when a value is + provided. + +#### **Example** + +Suppose we want all UTXOs that reference at least one of +`P-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5` and `P-avax1d09qn852zcy03sfc9hay2llmn9hsgnw4tp3dv6`. + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"platform.getUTXOs", + "params" :{ + "addresses":["P-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", "P-avax1d09qn852zcy03sfc9hay2llmn9hsgnw4tp3dv6"], + "limit":5, + "encoding": "hex" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P +``` + +This gives response: + +```json +{ + "jsonrpc": "2.0", + "result": { + "numFetched": "5", + "utxos": [ + "0x0000a195046108a85e60f7a864bb567745a37f50c6af282103e47cc62f036cee404700000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216c1f01765", + "0x0000ae8b1b94444eed8de9a81b1222f00f1b4133330add23d8ac288bffa98b85271100000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216473d042a", + "0x0000731ce04b1feefa9f4291d869adc30a33463f315491e164d89be7d6d2d7890cfc00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f21600dd3047", + "0x0000b462030cc4734f24c0bc224cf0d16ee452ea6b67615517caffead123ab4fbf1500000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216c71b387e", + "0x000054f6826c39bc957c0c6d44b70f961a994898999179cc32d21eb09c1908d7167b00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f2166290e79d" + ], + "endIndex": { + "address": "P-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", + "utxo": "kbUThAUfmBXUmRgTpgD6r3nLj7rJUGho6xyht5nouNNypH45j" + }, + "encoding": "hex" + }, + "id": 1 +} +``` + +Since `numFetched` is the same as `limit`, we can tell that there may be more UTXOs that were not +fetched. We call the method again, this time with `startIndex`: + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"platform.getUTXOs", + "params" :{ + "addresses":["P-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"], + "limit":5, + "startIndex": { + "address": "P-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", + "utxo": "0x62fc816bb209857923770c286192ab1f9e3f11e4a7d4ba0943111c3bbfeb9e4a5ea72fae" + }, + "encoding": "hex" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P +``` + +This gives response: + +```json +{ + "jsonrpc": "2.0", + "result": { + "numFetched": "4", + "utxos": [ + "0x000020e182dd51ee4dcd31909fddd75bb3438d9431f8e4efce86a88a684f5c7fa09300000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f21662861d59", + "0x0000a71ba36c475c18eb65dc90f6e85c4fd4a462d51c5de3ac2cbddf47db4d99284e00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f21665f6f83f", + "0x0000925424f61cb13e0fbdecc66e1270de68de9667b85baa3fdc84741d048daa69fa00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216afecf76a", + "0x000082f30327514f819da6009fad92b5dba24d27db01e29ad7541aa8e6b6b554615c00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216779c2d59" + ], + "endIndex": { + "address": "P-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", + "utxo": "21jG2RfqyHUUgkTLe2tUp6ETGLriSDTW3th8JXFbPRNiSZ11jK" + }, + "encoding": "hex" + }, + "id": 1 +} +``` + +Since `numFetched` is less than `limit`, we know that we are done fetching UTXOs and don’t need to +call this method again. + +Suppose we want to fetch the UTXOs exported from the X Chain to the P Chain in order to build an +ImportTx. Then we need to call GetUTXOs with the `sourceChain` argument in order to retrieve the +atomic UTXOs: + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"platform.getUTXOs", + "params" :{ + "addresses":["P-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"], + "sourceChain": "X", + "encoding": "hex" + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P +``` + +This gives response: + +```json +{ + "jsonrpc": "2.0", + "result": { + "numFetched": "1", + "utxos": [ + "0x00001f989ffaf18a18a59bdfbf209342aa61c6a62a67e8639d02bb3c8ddab315c6fa0000000139c33a499ce4c33a3b09cdd2cfa01ae70dbf2d18b2d7d168524440e55d55008800000007000000746a528800000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29cd704fe76" + ], + "endIndex": { + "address": "P-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", + "utxo": "S5UKgWoVpoGFyxfisebmmRf8WqC7ZwcmYwS7XaDVZqoaFcCwK" + }, + "encoding": "hex" + }, + "id": 1 +} +``` + +### `platform.getValidatorsAt` + +Get the validators and their weights of a Subnet or the Primary Network at a given P-Chain height. + +**Signature:** + +```sh +platform.getValidatorsAt( + { + height: int, + subnetID: string, // optional + } +) +``` + +- `height` is the P-Chain height to get the validator set at. +- `subnetID` is the Subnet ID to get the validator set of. If not given, gets validator set of the + Primary Network. + +**Example Call:** + +```bash +curl -X POST --data '{ + "jsonrpc": "2.0", + "method": "platform.getValidatorsAt", + "params": { + "height":1 + }, + "id": 1 +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "validators": { + "NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg": 2000000000000000, + "NodeID-GWPcbFJZFfZreETSoWjPimr846mXEKCtu": 2000000000000000, + "NodeID-MFrZFVCXPv5iCn6M9K6XduxGTYp891xXZ": 2000000000000000, + "NodeID-NFBbbJ4qCmNaCzeW7sxErhvWqvEQMnYcN": 2000000000000000, + "NodeID-P7oB2McjBGgW2NXXWVYjV8JEDFoW9xDE5": 2000000000000000 + } + }, + "id": 1 +} +``` + +### `platform.issueTx` + +Issue a transaction to the Platform Chain. + +**Signature:** + +```sh +platform.issueTx({ + tx: string, + encoding: string, // optional +}) -> {txID: string} +``` + +- `tx` is the byte representation of a transaction. +- `encoding` specifies the encoding format for the transaction bytes. Can only be `hex` when a value + is provided. +- `txID` is the transaction’s ID. + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc": "2.0", + "method": "platform.issueTx", + "params": { + "tx":"0x00000009de31b4d8b22991d51aa6aa1fc733f23a851a8c9400000000000186a0000000005f041280000000005f9ca900000030390000000000000001fceda8f90fcb5d30614b99d79fc4baa29307762668f16eb0259a57c2d3b78c875c86ec2045792d4df2d926c40f829196e0bb97ee697af71f5b0a966dabff749634c8b729855e937715b0e44303fd1014daedc752006011b730", + "encoding": "hex" + }, + "id": 1 +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "txID": "G3BuH6ytQ2averrLxJJugjWZHTRubzCrUZEXoheG5JMqL5ccY" + }, + "id": 1 +} +``` + +### `platform.listAddresses` + +:::caution + +Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12). + +::: + +:::warning + +Not recommended for use on Mainnet. See warning notice in [Keystore API](/reference/avalanchego/keystore-api.md). + +::: + +List addresses controlled by the given user. + +**Signature:** + +```sh +platform.listAddresses({ + username: string, + password: string +}) -> {addresses: []string} +``` + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc": "2.0", + "method": "platform.listAddresses", + "params": { + "username":"myUsername", + "password":"myPassword" + }, + "id": 1 +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "addresses": ["P-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"] + }, + "id": 1 +} +``` + +### `platform.sampleValidators` + +Sample validators from the specified Subnet. + +**Signature:** + +```sh +platform.sampleValidators( + { + size: int, + subnetID: string, // optional + } +) -> +{ + validators: []string +} +``` + +- `size` is the number of validators to sample. +- `subnetID` is the Subnet to sampled from. If omitted, defaults to the Primary Network. +- Each element of `validators` is the ID of a validator. + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc":"2.0", + "id" :1, + "method" :"platform.sampleValidators", + "params" :{ + "size":2 + } +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "validators": [ + "NodeID-MFrZFVCXPv5iCn6M9K6XduxGTYp891xXZ", + "NodeID-NFBbbJ4qCmNaCzeW7sxErhvWqvEQMnYcN" + ] + } +} +``` + +### `platform.validatedBy` + +Get the Subnet that validates a given blockchain. + +**Signature:** + +```sh +platform.validatedBy( + { + blockchainID: string + } +) -> {subnetID: string} +``` + +- `blockchainID` is the blockchain’s ID. +- `subnetID` is the ID of the Subnet that validates the blockchain. + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc": "2.0", + "method": "platform.validatedBy", + "params": { + "blockchainID": "KDYHHKjM4yTJTT8H8qPs5KXzE6gQH5TZrmP1qVr1P6qECj3XN" + }, + "id": 1 +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "subnetID": "2bRCr6B4MiEfSjidDwxDpdCyviwnfUVqB2HGwhm947w9YYqb7r" + }, + "id": 1 +} +``` + +### `platform.validates` + +Get the IDs of the blockchains a Subnet validates. + +**Signature:** + +```sh +platform.validates( + { + subnetID: string + } +) -> {blockchainIDs: []string} +``` + +- `subnetID` is the Subnet’s ID. +- Each element of `blockchainIDs` is the ID of a blockchain the Subnet validates. + +**Example Call:** + +```sh +curl -X POST --data '{ + "jsonrpc": "2.0", + "method": "platform.validates", + "params": { + "subnetID":"2bRCr6B4MiEfSjidDwxDpdCyviwnfUVqB2HGwhm947w9YYqb7r" + }, + "id": 1 +}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P +``` + +**Example Response:** + +```json +{ + "jsonrpc": "2.0", + "result": { + "blockchainIDs": [ + "KDYHHKjM4yTJTT8H8qPs5KXzE6gQH5TZrmP1qVr1P6qECj3XN", + "2TtHFqEAAJ6b33dromYMqfgavGPF3iCpdG3hwNMiart2aB5QHi" + ] + }, + "id": 1 +} +```