Skip to content

API

Jump to bottom
Steven Masley edited this page Dec 19, 2019 · 19 revisions

pegnetd Daemon RPC Documentation

This document defines the Remote Procedure Call API for pegnetd. The RPC encompasses methods to read balances, transactions, and conversions on pegnet.

The API will follow JSON-RPC 2.0 Specification.

API Version

This standard covers RPC API version v1. The pegnetd is used for reading the pegnet chain. If you wish to write conversions/transactions, all factom entries follow this format: https://hackmd.io/EfSzduXqQ8yyD9vBYK3E-w?view.

All transaction format validation can be found in this directory: https://github.com/pegnet/pegnetd/tree/master/fat/fat2. If you wish to build transactions using the library, you can use the cli as a guide.

Methods

get-sync-status :

Return the current heights synced by pegnetd and the factomd it is communicating with.

Request:

curl -X POST --data-binary \
'{"jsonrpc": "2.0", "id": 0, "method":"get-sync-status"}' \
-H 'content-type:text/plain;' http://localhost:8070/v1

Response:

{  
   "jsonrpc":"2.0",
   "result":{  
      "syncheight":214301,
      "factomheight":214301
   },
   "id":0
}

get-transaction:

Returns the given pegnet transaction if it exists. All txids are in the format [TxIndex]-[TxHash]. If the hash exists, but not the index, the result is Transaction Not Found. The response is still an array, as the underlying functionality is provided by the get-transactions call. You can see the documentation for that call for additional parameters. The main difference is that this call only accepts a txid as the search parameter. All calls should return at most 1 transaction in the array.

Request:

curl -X POST --data-binary \
'{"jsonrpc": "2.0", "id": 0, "method":"get-transaction",
"params":{"txid":"00-c99dedea0e4e0c40118fe7e4d515b23cc0489269c8cef187b4f15a4ccbd880be"}}' \
-H 'content-type:text/plain;' http://localhost:8070/v1

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "actions": [
      {
        "hash": "c99dedea0e4e0c40118fe7e4d515b23cc0489269c8cef187b4f15a4ccbd880be",
        "txid": "0-c99dedea0e4e0c40118fe7e4d515b23cc0489269c8cef187b4f15a4ccbd880be",
        "height": 206590,
        "timestamp": "2019-08-20T16:11:00-05:00",
        "executed": 206590,
        "txindex": 0,
        "txaction": 3,
        "fromaddress": "FA2mPQpBhr7f9XtXMVhsYQjNzsMGv1sqk2dTZp1NyTBuCaR6BjLM",
        "fromasset": "",
        "fromamount": 0,
        "toasset": "PEG",
        "toamount": 80000000000
      }
    ],
    "count": 1,
    "nextoffset": 0
  },
  "id": 0
}

get-pegnet-issuance :

Get the total supply for each pegnet asset.

Request:

curl -X POST --data-binary \
'{"jsonrpc": "2.0", "id": 0, "method":"get-pegnet-issuance"}' \
-H 'content-type:text/plain;' http://localhost:8070/v1

Response:

{  
   "jsonrpc":"2.0",
   "result":{  
      "syncstatus":{  
         "syncheight":214299,
         "factomheight":214299
      },
      "issuance":{  
         "PEG":5064716249706472,
         "pADA":9174741510,
         "pBNB":23964155,
         "pBRL":1915004591,
         "pCAD":505757599,
         "pCHF":2031773352,
         "pCNY":2716169709,
         "pDASH":5317841,
         "pDCR":21694146,
         "pETH":1838430641,
         "pEUR":427187617,
         "pFCT":3846027468077,
         "pGBP":308496745,
         "pHKD":2980001159,
         "pINR":26981732013,
         "pJPY":40694137315,
         "pKRW":454720374337,
         "pLTC":6640888,
         "pMXN":7428080364,
         "pPHP":19717349003,
         "pRVN":14391145402388,
         "pSGD":524774284,
         "pUSD":368327645950,
         "pXAG":10029803207,
         "pXAU":144804349,
         "pXBC":1623103,
         "pXBT":42136027,
         "pXLM":6158039443,
         "pXMR":6690407,
         "pZEC":10101202
      }
   },
   "id":0
}

get-pegnet-balances :

Get the pegnet asset balances for a given address. All balances are in their fixed point values, meaning a balance of 1e8 == 1 pAsset. In this example response, the address has 9401 PEG.

Request:

curl -X POST --data-binary \
'{"jsonrpc": "2.0", "id": 0, "method":"get-pegnet-balances",
"params":{"address":"FA28MV2VvvsdjjgXoHwsadtMWqM5mt7bZU3hMjLuDLLN1DBhK48g"}}' \
-H 'content-type:text/plain;' http://localhost:8070/v1

Response:

{
   "jsonrpc":"2.0",
   "result":{
      "PEG":940100000000,
      "pADA":0,
      "pBNB":0,
      "pBRL":0,
      "pCAD":0,
      "pCHF":0,
      "pCNY":0,
      "pDASH":0,
      "pDCR":0,
      "pETH":0,
      "pEUR":0,
      "pFCT":0,
      "pGBP":0,
      "pHKD":0,
      "pINR":0,
      "pJPY":0,
      "pKRW":0,
      "pLTC":0,
      "pMXN":0,
      "pPHP":0,
      "pRVN":0,
      "pSGD":0,
      "pUSD":0,
      "pXAG":0,
      "pXAU":0,
      "pXBC":0,
      "pXBT":0,
      "pXLM":0,
      "pXMR":0,
      "pZEC":0
   },
   "id":0
}

get-pegnet-rates:

Returns the pegnet conversion rates for a given block height.

Request:

curl -X POST --data-binary \
'{"jsonrpc": "2.0", "id": 0, "method":"get-pegnet-rates",
"params":{"height":213000}}' \
-H 'content-type:text/plain;' http://localhost:8070/v1

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "PEG": 0,
    "pADA": 3974089,
    "pBNB": 1567649568,
    "pBRL": 24646300,
    "pCAD": 75119063,
    "pCHF": 100467172,
    "pCNY": 13989136,
    "pDASH": 6946832822,
    "pDCR": 1668878643,
    "pETH": 17633014348,
    "pEUR": 109799615,
    "pFCT": 362154294,
    "pGBP": 123334369,
    "pHKD": 12755583,
    "pINR": 1411920,
    "pJPY": 935059,
    "pKRW": 83871,
    "pLTC": 5736385888,
    "pMXN": 5124197,
    "pPHP": 1935040,
    "pRVN": 3086664,
    "pSGD": 72519997,
    "pUSD": 100000000,
    "pXAG": 1753985933,
    "pXAU": 150375939849,
    "pXBC": 22310754166,
    "pXBT": 812762606639,
    "pXLM": 5913512,
    "pXMR": 5669451886,
    "pZEC": 3700509005
  },
  "id": 0
}

get-transaction-status:

Returns the status of a transaction. The parameter entryhash can be either a winning OPR entry hash, a transaction chain entry hash, or an FCT Burn transaction id. An unknown hash will result in an -32803 error. A known hash response contains two fields:

  • height: this is the directory block height that the transaction was submitted
  • executed: this is the status indicator
    • -3 means the transaction was rejected due to being a pXXX -> pFCT transaction while one-way conversions are enabled for pFCT.
    • -2 means the transaction was rejected due to being invalid. This could be an expired timestamp, bad signature, or other validation rules.
    • -1 means the transaction was rejected due to insufficient balance
    • 0 means the transaction is currently pending and has not yet been processed
    • N (>= height) means the transaction was successfully applied at block height N.

Request:

curl -X POST --data-binary \
'{"jsonrpc": "2.0", "id": 0, "method":"get-transaction-status",
"params":{"entryhash":"a33d4f334a2658c17d3f44158af75f1c32cc6b2f3de9ddc337064c93043d8db0"}}' \
-H 'content-type:text/plain;' http://localhost:8070/v1

Response:

{"jsonrpc":"2.0","result":{"height":213438,"executed":213438},"id":0}

get-transactions:

Returns a set of up to 50 transactions for the given parameters. The only requirement is setting either entryhash, address, or height. All other parameters are optional. The executed height MUST be > 0 for the transaction to be valid. If the executed height is 0, the tx is pending. If the executed field is < 0, the tx is rejected. Anyone viewing txs should check the executed height.

  • entryhash (hex-encoded string): can be either a winning OPR entry hash, a transaction chain entry hash, or an FCT Burn transaction id, e.g.: a33d4f334a2658c17d3f44158af75f1c32cc6b2f3de9ddc337064c93043d8db0. Mutually exclusive with address and height.
  • address (string): transactions involving the address (as sender or recipient), e.g.: FA3pPBWaVjZXhiFiUBdpvyjK84cvjWcZvZqoxeAEsH3rFCtEvEVt. Mutually exclusive with entryhash and height.
  • height (integer): transactions that were submitted at this height, e.g.: 213438
  • offset (integer): Results are paginated and the offset is used to specify the starting point. A paginated result will return the next value of offset as nextoffset. e.g.: 150
  • desc (bool): If set to true, the order of transactions is reversed, retrieving newest transactions first.
  • transfer (bool): If set to true, the list of transactions will include transfers
  • conversion (bool): If set to true, the list of transactions will include conversions
  • coinbase (bool): If set to true, the list of transactions will include miner payouts
  • burn (bool): If set to true, the list of transactions will include fct burns

By default, all four transaction types are included. If one type is set to true, then ONLY that type is returned. You can combine different types, for example set transfer and conversion to true in order retrieve both transfers and conversions.

The results come in the form of up to 50 Transactions with a specific type. Each transaction has a unique (hash, tx_index) tuple but the hash alone is not unique. The data returned is a multi-level json format, with the base being:

  • actions (list): This contains the list of Transactions. For more, see below
  • count (integer): The total number of records for this request, which may be more than 50
  • nextoffset (integer): If this number is greater than zero, it means that not all transactions fit into the next. You can repeat the API request with offset to the value of nextoffset in order to retrieve the next set of transactions.

The list of transactions is an object with the following potential keys:

  • hash (hex encoded bytes): For transfers, conversions, and coinbases, this is the relevant entry hash. For burns, this is the txid.
  • txid ([TxIndex]-[Hash]): All hashes potentially contain multiple transactions. Every transaction associated with hash also has a transaction index. By using the transaction index as a prefix to the hash, a specific transaction in the set can be identified.
  • height (integer): The height that the transaction was written to the chain.
  • timestamp (string): The timestamp of when the transaction was written to the chain.
  • executed (integer): Status indicator. <0 means rejected, 0 means pending, otherwise, it is the height the transaction was applied. All rejected codes can be found in the get-transaction-status: api description.
  • txindex (integer): A single entry can contain multiple transactions and this is the index of the transaction inside of an entry. For coinbases and burns, this is always 0.
  • txaction (integer): The type of Transaction:
    • 1: Transfer
    • 2: Conversion
    • 3: Coinbase
    • 4: Burn
  • fromaddress (string): The origin of the funds in the form of an FA... address. For Conversions, Coinbases, and Burns this is also the recipient.
  • fromasset (string): The pAsset that was sent. For Burns this is always "FCT", for Coinbases this is blank.
  • fromamount (integer): The amount was sent in Pegtoshis. For Coinbases, this is blank.
  • toasset (string): The destination pAsset. For Transfers, this is blank.
  • toamount (integer): The amount of pAsset the address was credited with. For pending Conversions, this is 0, otherwise it contains the actual amount. For Transfers, this is 0.
  • outputs (list): For transfers, this is a list that contains the set of outputs. There is at least one output in the list. For conversions into PEG (pXXX -> PEG), the outputs can also contain a refund amount in the original pXXX asset. Since PEG conversions have a limit, partial conversions exist. For all other types, this is blank.

The list of outputs contains objects with an address and an amount field. The amount units are always in fromasset units.

Request:

curl -X POST --data-binary \
'{"jsonrpc": "2.0", "id": 0, "method":"get-transactions",
"params":{"address":"FA3pPBWaVjZXhiFiUBdpvyjK84cvjWcZvZqoxeAEsH3rFCtEvEVt"}}' \
-H 'content-type:text/plain;' http://localhost:8070/v1

Response:

{
   "jsonrpc":"2.0",
   "result":{
      "actions":[
         {
            "hash":"2f07b6254559407b866356f878760d97c2e70721024f910bcf1c9daff256f7af",
            "height":213739,
            "timestamp":"2019-10-10T21:40:00+02:00",
            "executed":213740,
            "txindex":0,
            "txaction":2,
            "fromaddress":"FA3pPBWaVjZXhiFiUBdpvyjK84cvjWcZvZqoxeAEsH3rFCtEvEVt",
            "fromasset":"pFCT",
            "fromamount":50000000000,
            "toasset":"pRVN",
            "toamount":4747852584121
         },
         {
            "hash":"9d5cf82eb16310016962c9abc08a619b02258024b00ce7407eb2761b68e97150",
            "height":213470,
            "timestamp":"2019-10-09T00:46:00+02:00",
            "executed":213470,
            "txindex":0,
            "txaction":1,
            "fromaddress":"FA3pPBWaVjZXhiFiUBdpvyjK84cvjWcZvZqoxeAEsH3rFCtEvEVt",
            "fromasset":"pXAU",
            "fromamount":100000,
            "outputs":[
               {
                  "address":"FA2QdSsWp4MoZVm8RpcnsJXJVAVDvbno5fAD1Qn67knFRJdxsxJU",
                  "amount":100000
               }
            ]
         },
         {
            "hash":"024648e9e2b696d90f86ee8e474f2eb685194b0c9375dceb7b0170f94e342034",
            "height":213450,
            "timestamp":"2019-10-08T21:30:00+02:00",
            "executed":213450,
            "txindex":0,
            "txaction":1,
            "fromaddress":"FA3pPBWaVjZXhiFiUBdpvyjK84cvjWcZvZqoxeAEsH3rFCtEvEVt",
            "fromasset":"pXAU",
            "fromamount":100000,
            "outputs":[
               {
                  "address":"FA2LUHeytM4R2ZPrJjUFLr5e3S44Bs8ze7fYv3Wp5bztuFa8vgoy",
                  "amount":100000
               }
            ]
         }
      ],
      "count":34,
      "nextoffset":0
   },
   "id":0
}

get-rich-list:

Returns the rich list of addresses for all assets or a specific asset. Exclude the asset field to get the global rich list including all assets.

Request:

curl -X POST --data-binary \
'{"jsonrpc": "2.0", "id": 0, "method":"get-rich-list",
"params":{"asset":"PEG", "count":10}}' \
-H 'content-type:text/plain;' http://localhost:8070/v1

Response:

{  
   "jsonrpc":"2.0",
   "result":[  
      {  
         "address":"FA28wF5WSfXVJB5kzLTwsLiGRS4qgAo5iVg4k3fqVPQmNK7PoLhY",
         "amount":99800000000000,
         "pusd":388174096000
      },
      {  
         "address":"FA2jK2HcLnRdS94dEcU27rF3meoJfpUcZPSinpb7AwQvPRY6RL1Q",
         "amount":700000000000,
         "pusd":2722664000
      }
   ],
   "id":0
}
Clone this wiki locally