Validators

Validators are special participants in the blockchain who have registered themselves as eligible to validate and produce blocks. They play a critical role in maintaining the integrity and operation of the blockchain network.

A validator has acquired a sufficient number of votes and has a Relay Node configured to forge new blocks through a forger module. At any time only 53 validators are active. They are cost-efficient miners running the Mainsail network.

Voters are wallets which have broadcast a vote transaction on a validator. A vote remains active until an un-vote transaction is sent (it does not have to be recast unless a wallet wishes to change the validator they are voting for). Voting for a validator does not give the validator access to the wallet nor does it lock the coins in it.

Properties

Name
address
Type
string
Description
The unique address of the validator.
Name
publicKey
Type
string
Description
The public key of the validator.
Name
balance
Type
string
Description
The total balance of the validator.
Name
nonce
Type
string
Description
The nonce value associated with the validator.
Name
attributes
Type
object
Description
Additional attributes related to the validator, such as vote, username, and forging information.
Name
updated_at
Type
string
Description
The last block height at which the validator's data was updated.

GET/validators

List All Validators

This endpoint retrieves a paginated list of all validators registered on the blockchain. The validators include both active validators and other participants.

Query Parameters

Name
page
Type
integer
Description
The page number to retrieve.
Name
limit
Type
integer
Description
The number of results per page.
Name
offset
Type
integer
Description
The number of records to skip.
Name
orderBy
Type
string
Description
The column by which to sort the results.
Name
username
Type
string
Description
The username of the validator to retrieve.
Name
address
Type
string
Description
The address of the validator to retrieve.
Name
publicKey
Type
string
Description
The public key of the validator to retrieve.
Name
votes
Type
integer
Description
The number of votes the validator has received.
Name
isResigned
Type
boolean
Description
Whether the validator has resigned.
Name
blocks.produced
Type
integer
Description
The number of blocks produced by the validator.
Name
forged.fees
Type
string
Description
The total fees forged by the validator.
Name
forged.rewards
Type
string
Description
The total rewards forged by the validator.
Name
forged.total
Type
string
Description
The total amount (fees + rewards) forged by the validator.

Request

GET

/validators?page=1&limit=5

curl -G https://testnet.mainsailhq.com/api/validators \
  -d page=1 \
  -d limit=5

Response

{
  "meta": {
    "totalCountIsEstimate": true,
    "count": 5,
    "first": "/validators?limit=5&page=1",
    "last": "/validators?limit=5&page=1",
    "next": null,
    "pageCount": 1,
    "previous": null,
    "self": "/validators?limit=5&page=1",
    "totalCount": 53
  },
  "data": [
    {
      "address": "0x69aD988298FB856adD785070781aaE6370cf0093",
      "publicKey": "02da652d03f195fd2adb9e6290b8916f78a16daee4bc3d0a2c03b7f6c6651d1a29",
      "balance": "2358828566037735859056603",
      "nonce": "3",
      "attributes": {
        "vote": "02da652d03f195fd2adb9e6290b8916f78a16daee4bc3d0a2c03b7f6c6651d1a29",
        "username": "genesis_44",
        "validatorRank": 1,
        "validatorApproval": 1.89,
        "validatorLastBlock": {
          "hash": "9b167abb04b9ccef1366b3576b6c0bc6a2ca59f02b8542715aa6f32a11afb86c",
          "number": 83961,
          "timestamp": 1725475351632
        },
        "validatorForgedFees": "10000000",
        "validatorForgedTotal": "338000000000010000000",
        "validatorForgedRewards": "338000000000000000000",
        "validatorProducedBlocks": 1630
      },
      "updated_at": "83961"
    }
  ]
}

GET/validators/:id

Retrieve a Validator

This endpoint retrieves a specific validator by their unique identifier, which can be an address, public key, or username. The response includes detailed information about the validator, including their balance, public key, and validator-related attributes.

Query Parameters

Name
transform
Type
boolean
Description
Whether to transform the response structure.

Request

GET

/validators/:id

curl https://testnet.mainsailhq.com/api/validators/0x69aD988298FB856adD785070781aaE6370cf0093

Response

{
  "data": {
    "address": "0x69aD988298FB856adD785070781aaE6370cf0093",
    "publicKey": "02da652d03f195fd2adb9e6290b8916f78a16daee4bc3d0a2c03b7f6c6651d1a29",
    "balance": "2358828566037735859056603",
    "nonce": "3",
    "attributes": {
      "vote": "02da652d03f195fd2adb9e6290b8916f78a16daee4bc3d0a2c03b7f6c6651d1a29",
      "nonce": "3",
      "balance": "2358828566037735859056603",
      "username": "genesis_44",
      "publicKey": "02da652d03f195fd2adb9e6290b8916f78a16daee4bc3d0a2c03b7f6c6651d1a29",
      "validatorRank": 1,
      "validatorApproval": 1.89,
      "validatorLastBlock": {
        "hash": "9b167abb04b9ccef1366b3576b6c0bc6a2ca59f02b8542715aa6f32a11afb86c",
        "number": 83961,
        "timestamp": 1725475351632
      },
      "validatorPublicKey": "95e766b01acc717706d9cde51e2501c960fe8f39d342517f02b48fd75515cb10bb28a00510f06a26f434a29cd2ba37e1",
      "validatorForgedFees": "10000000",
      "validatorForgedTotal": "338000000000010000000",
      "validatorVoteBalance": "2358828566037735859056603",
      "validatorForgedRewards": "338000000000000000000",
      "validatorProducedBlocks": 1630
    },
    "updated_at": "84005"
  }
}

GET/validators/:id/blocks

List All Blocks of a Validator

This endpoint retrieves all blocks produced by a specific validator. It includes detailed information about each block, such as its height, the number of transactions, and the rewards forged by the validator.

Query Parameters

Name
page
Type
integer
Description
The page number to retrieve.
Name
limit
Type
integer
Description
The number of results per page.
Name
offset
Type
integer
Description
The number of records to skip.
Name
orderBy
Type
string
Description
The column by which to sort the results.
Name
transform
Type
boolean
Description
Whether to transform the response structure.

Request

GET

/validators/:id/blocks

curl -G https://testnet.mainsailhq.com/api/validators/0x69aD988298FB856adD785070781aaE6370cf0093/blocks \
  -d orderBy=number:desc \
  -d limit=100

Response

{
  "meta": {
    "totalCountIsEstimate": true,
    "count": 100,
    "first": "/validators/0x69aD988298FB856adD785070781aaE6370cf0093/blocks?orderBy=height%3Adesc&transform=true&limit=100&page=1",
    "last": "/validators/0x69aD988298FB856adD785070781aaE6370cf0093/blocks?orderBy=height%3Adesc&transform=true&limit=100&page=17",
    "next": "/validators/0x69aD988298FB856adD785070781aaE6370cf0093/blocks?orderBy=height%3Adesc&transform=true&limit=100&page=2",
    "pageCount": 17,
    "previous": null,
    "self": "/validators/0x69aD988298FB856adD785070781aaE6370cf0093/blocks?orderBy=height%3Adesc&transform=true&limit=100&page=1",
    "totalCount": 1692
  },
  "data": [
    {
      "confirmations": 3,
      "forged": {
        "amount": "0",
        "fee": "0",
        "reward": "2000000000000000000",
        "total": "2000000000000000000"
      },
      "generator": {
        "address": "0x69aD988298FB856adD785070781aaE6370cf0093",
        "publicKey": "02da652d03f195fd2adb9e6290b8916f78a16daee4bc3d0a2c03b7f6c6651d1a29",
        "username": "genesis_44"
      },
      "number": 84051,
      "hash": "da7c334fbe48d7b7b06455fc71da4165d866c48642f2568868072ebe0532ce33",
      "payload": {
        "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        "length": 0
      },
      "previous": "5d890b32bfb0c667ff7e2173e6b1985b7f750a53887f2dd0e8525468c24bc831",
      "signature": "a10dedb75d0f17e97632cfc4e511903ef4afb70623f8b28f25ac02c3258fd0993628e06c7068ec0cf84124c79ec06e87025afdf06af8086e63b137a3e17a6fdd8b336823201ec85254e36fb6d42563ea51632c078ef514f260e26cae34deac04",
      "timestamp": 1725476107025,
      "transactions": 0,
      "version": 1
    }
  ]
}

GET/validators/:id/voters

List All Voters of a Validator

This endpoint retrieves all voters who have voted for a specific validator. It includes detailed information about each voter's address, balance, and other relevant attributes.

Query Parameters

Name
page
Type
integer
Description
The page number to retrieve.
Name
limit
Type
integer
Description
The number of results per page.
Name
offset
Type
integer
Description
The number of records to skip.
Name
orderBy
Type
string
Description
The column by which to sort the results.
Name
transform
Type
boolean
Description
Whether to transform the response structure.

Request

GET

/validators/:id/voters

curl -G https://testnet.mainsailhq.com/api/validators/0x69aD988298FB856adD785070781aaE6370cf0093/voters \
  -d limit=100

Response

{
  "meta": {
    "totalCountIsEstimate": true,
    "count": 1,
    "first": "/validators/0x69aD988298FB856adD785070781aaE6370cf0093/voters?limit=100&page=1",
    "last": "/validators/0x69aD988298FB856adD785070781aaE6370cf0093/voters?limit=100&page=1",
    "next": null,
    "pageCount": 1,
    "previous": null,
    "self": "/validators/0x69aD988298FB856adD785070781aaE6370cf0093/voters?limit=100&page=1",
    "totalCount": 1
  },
  "data": [
    {
      "address": "0x69aD988298FB856adD785070781aaE6370cf0093",
      "publicKey": "02da652d03f195fd2adb9e6290b8916f78a16daee4bc3d0a2c03b7f6c6651d1a29",
      "balance": "238135756603773",
      "nonce": "3",
      "attributes": {
        "vote": "02da652d03f195fd2adb9e6290b8916f78a16daee4bc3d0a2c03b7f6c6651d1a29",
        "nonce": "3",
        "balance": "238135756603773",
        "username": "genesis_44",
        "publicKey": "02da652d03f195fd2adb9e6290b8916f78a16daee4bc3d0a2c03b7f6c6651d1a29",
        "validatorRank": 11,
        "validatorApproval": 1.91,
        "validatorLastBlock": {
          "hash": "4d7465399e6e033a3c69f86b9cbcd04bbb1a3ec74f00ebcef89ecc072ce9f558",
          "number": 671822,
          "timestamp": 1725476514802
        },
        "validatorPublicKey": "95e766b01acc717706d9cde51e2501c960fe8f39d342517f02b48fd75515cb10bb28a00510f06a26f434a29cd2ba37e1",
        "validatorForgedFees": "2500000000",
        "validatorForgedTotal": "2286700000000",
        "validatorVoteBalance": "238135756603773",
        "validatorForgedRewards": "2284200000000",
        "validatorProducedBlocks": 12845
      },
      "updated_at": "671822"
    }
  ]
}