Forging

From ArdorDocs
Jump to: navigation, search

Start Bundler

Start a bundler with an account, or check to see if an account is bundling. POST only. Javadoc

Request:

  • requestType is startBundler
  • chain is the child chain related to the operation (eg: 2 for Ignis)
  • minRateNQTPerFXT is the minimum rate in chain NQT per ARDR NQT accepted by the bundler
  • totalFeesLimitFQT is the maximum amount of ARDR NQT to be paid in total by the bundler
  • overpayFQTPerFXT is an additional factor of the Ardor fee to pay in case of competing bundlers (optional)
  • feeCalculatorName is a bundling rule for filtering (optional)
  • filter is a filter to be applied (optional)
  • bundlingRulesJSON is a list of bundling rules as a Json format (optional)
  • secretPhrase is the secret passphrase of the account (optional for stopBundler and getBundlers if password protected like the Debug Operations)

Response:

  • totalFeesLimitFQT (N) is the maximum amount of ARDR NQT to be paid in total by the bundler
  • currentTotalFeesFQT (N) is the up to date fees paid by the bundler
  • minimumRateNQTPerFXT (N) is the minimum rate in chain NQT per ARDR NQT accepted by the bundler
  • overpayFQTPerFXT (N) is an additional factor of the Ardor fee to pay in case of competing bundlers
  • chain (N) is the child chain related to the operation (eg: 2 for Ignis)
  • announcedMinRateNQTPerFXT (N) is the announced minimum rate in chain NQT per ARDR NQT accepted by the bundler
  • bundler (N) is bundler id
  • bundlingRules (A) is an array containing all bundling rules (minimumRateNQTPerFXT, feeCalculatorName...)
  • bundlerRS (S) is the Reed-Solomon address of the bundler account
  • requestProcessingTime (N) is the API request processing time (in millisec)

Start Bundler Example

http://localhost:27876/nxt?
  requestType=startBundler&
  chain=2&
  minRateNQTPerFXT=1&
  totalFeesLimitFQT=1000000&
  secretPhrase=IWontTellYou
{
    "totalFeesLimitFQT": "10000000",
    "currentTotalFeesFQT": "0",
    "minRateNQTPerFXT": "1",
    "overpayFQTPerFXT": "0",
    "chain": 2,
    "announcedMinRateNQTPerFXT": "1",
    "bundler": "15382970207090678772",
    "bundlingRules": [
        {
            "minRateNQTPerFXT": "1",
            "feeCalculatorName": "MIN_FEE"
        }
    ],
    "requestProcessingTime": 2,
    "bundlerRS": "ARDOR-X8ZN-WUJ2-SXY3-FBUYC"
}


Stop Bundler

Stop a bundler with an account. POST only. Javadoc

Request:

  • requestType is stopBundler
  • chain is the child chain related to the operation (eg: 2 for Ignis)
  • account is the account to stop bundling (optional)
  • adminPassword is a string with the admin password (optional)
  • secretPhrase is the secret passphrase of the account (optional if password protected like the Debug Operations)

Response:

  • stoppedChildChainBundlers (B) is whether the bundler was stop or not
  • requestProcessingTime (N) is the API request processing time (in millisec)


Stop Bundler Example

http://localhost:27876/nxt?
  requestType=stopBundler&
  chain=2&
  secretPhrase=IWontTellYou
{
    "requestProcessingTime": 0,
    "stoppedChildChainBundlers": true
}


Get Bundlers

Get bundlers running. Javadoc

Request:

  • requestType is getBundlers
  • chain is the child chain related to the operation (eg: 2 for Ignis)
  • account is the account to stop bundling (optional)
  • adminPassword is a string with the admin password (optional)
  • secretPhrase is the secret passphrase of the account (optional if password protected like the Debug Operations)

Response:

  • bundlers (A) is an array containing all bundlers details
    • totalFeesLimitFQT (N) is the maximum amount of ARDR NQT to be paid in total by the bundler
    • currentTotalFeesFQT (N) is the up to date fees paid by the bundler
    • minimumRateNQTPerFXT (N) is the minimum rate in chain NQT per ARDR NQT accepted by the bundler
    • overpayFQTPerFXT (N) is an additional factor of the Ardor fee to pay in case of competing bundlers
    • chain (N) is the child chain related to the operation (eg: 2 for Ignis)
    • announcedMinRateNQTPerFXT (N) is the announced minimum rate in chain NQT per ARDR NQT accepted by the bundler
    • bundler (N) is bundler id
    • bundlingRules (A) is an array containing all bundling rules (minimumRateNQTPerFXT, feeCalculatorName...)
    • bundlerRS (S) is the Reed-Solomon address of the bundler account
  • requestProcessingTime (N) is the API request processing time (in millisec)

Stop Bundler Example

http://localhost:27876/nxt?
  requestType=getBundlers&
  chain=2
{
    "bundlers": [
        {
            "totalFeesLimitFQT": "10000000",
            "currentTotalFeesFQT": "0",
            "minRateNQTPerFXT": "1",
            "overpayFQTPerFXT": "0",
            "chain": 2,
            "announcedMinRateNQTPerFXT": "1",
            "bundler": "15382970207090678772",
            "bundlingRules": [
                {
                    "minRateNQTPerFXT": "1",
                    "feeCalculatorName": "MIN_FEE"
                }
            ],
            "bundlerRS": "ARDOR-X8ZN-WUJ2-SXY3-FBUYC"
        }
    ],
    "requestProcessingTime": 1
}


Get All Bundler Rates

Check all bundler rates ordered by chain. Javadoc

Request:

  • requestType is getAllBundlersRates
  • minBundlerBalanceFXT is for filtering based on the minimum bundler balance FXT
  • account is the account to stop bundling (optional)

Response:

  • rates (A) is an array containing the data
    • chain (N) is the chain related to the rates detail
    • rate (A) is an array containing the rate details
      • minRateNQTPerFXT (N) is the minimum rate accepted by the bundler
      • currentFeeLimitFQT (N) is the fee limit of the bundler
      • accountRS (S) is the Reed-Solomon address of the bundler account
      • account (N) is the bundler account in numeric format
  • requestProcessingTime (N) is the API request processing time (in millisec)

Get All Bundler Rates Example

http://localhost:27876/nxt?
  requestType=getAllBundlersRates
{
    "rates": [
        {
            "chain": 4,
            "rates": []
        },
        {
            "chain": 2,
            "rates": [
                {
                    "minRateNQTPerFXT": "10000000",
                    "currentFeeLimitFQT": "4917547630000",
                    "accountRS": "ARDOR-VS8T-QYQS-SK9H-5BYBB",
                    "account": "3794223001810886873"
                },
                {
                    "minRateNQTPerFXT": "30000000",
                    "currentFeeLimitFQT": "999717000000",
                    "accountRS": "ARDOR-J24K-QWD8-XHEX-36P7X",
                    "account": "2204130173906321489"
                },
                {
                    "minRateNQTPerFXT": "10000000",
                    "currentFeeLimitFQT": "5000000000000",
                    "accountRS": "ARDOR-N7KP-3X6S-A3HH-DRC4M",
                    "account": "13369312691995940405"
                },
                {
                    "minRateNQTPerFXT": "100000000",
                    "currentFeeLimitFQT": "989392000000",
                    "accountRS": "ARDOR-V4D7-D3XW-JX9Z-EAC8K",
                    "account": "14454664023893707109"
                },
                {
                    "minRateNQTPerFXT": "50000000",
                    "currentFeeLimitFQT": "938001000000",
                    "accountRS": "ARDOR-QGHN-HSGE-L2FR-AGS42",
                    "account": "9226484196410341876"
                }
            ]
        },
        {
            "chain": 3,
            "rates": [
                {
                    "minRateNQTPerFXT": "1000",
                    "currentFeeLimitFQT": "99999000000",
                    "accountRS": "ARDOR-QGHN-HSGE-L2FR-AGS42",
                    "account": "9226484196410341876"
                }
            ]
        }
    ],
    "requestProcessingTime": 0
}


Get Bundler Rates

Get the most competitive rates per chain. Javadoc

Request:

  • requestType is getBundlersRates
  • minBundlerBalanceFXT is for filtering based on the minimum bundler balance FXT
  • account is the account to stop bundling (optional)

Response:

  • rates (A) is an array containing the data
    • chain (N) is the chain related to the rates detail
    • minRateNQTPerFXT (N) is the minimum rate accepted by the bundler
    • currentFeeLimitFQT (N) is the fee limit of the bundler
    • accountRS (S) is the Reed-Solomon address of the bundler account
    • account (N) is the bundler account in numeric format
  • requestProcessingTime (N) is the API request processing time (in millisec)

Get Bundler Rates Example

http://localhost:27876/nxt?
  requestType=getBundlersRates
{
    "rates": [
        {
            "minRateNQTPerFXT": "10000000",
            "currentFeeLimitFQT": "4917547630000",
            "chain": 2,
            "accountRS": "ARDOR-VS8T-QYQS-SK9H-5BYBB",
            "account": "3794223001810886873"
        },
        {
            "minRateNQTPerFXT": "1000",
            "currentFeeLimitFQT": "99999000000",
            "chain": 3,
            "accountRS": "ARDOR-QGHN-HSGE-L2FR-AGS42",
            "account": "9226484196410341876"
        }
    ],
    "requestProcessingTime": 0
}


Add Bundling Rule

Add a bundling rule to an account bundler. POST only. Javadoc

Request:

  • requestType is addBundlingRule
  • chain is the child chain related to the operation (eg: 2 for Ignis)
  • minRateNQTPerFXT is the minimum rate in chain NQT per ARDR NQT accepted by the bundler
  • totalFeesLimitFQT is the maximum amount of ARDR NQT to be paid in total by the bundler
  • overpayFQTPerFXT is an additional factor of the Ardor fee to pay in case of competing bundlers (optional)
  • feeCalculatorName is a bundling rule for filtering (optional)
  • filter is a repeated element that represents the filter or filters to be applied (PersonalBundler, PropertyBundler, AssetBundler, CurrencyBundler, PurchaseBundler or QuotaBundler)

Response: Refer to Start Bundler Response

Add Bundling Rule Example

http://localhost:27876/nxt?
  requestType=blacklistBundler&
  chain=2&
  secretPhrase=IWontTellYou&
  minRateNQTPerFXT=1&
  totalFeesLimitFQT=100&
  filter=PersonalBundler
{
    "totalFeesLimitFQT": "10000000000",
    "currentTotalFeesFQT": "0",
    "chain": 2,
    "announcedMinRateNQTPerFXT": "1200000000",
    "bundler": "15382970207090678772",
    "bundlingRules": [
        {
            "minRateNQTPerFXT": "1200000000",
            "feeCalculatorName": "MIN_FEE"
        },
        {
            "minRateNQTPerFXT": "1600000000",
            "feeCalculatorName": "MIN_FEE",
            "filters": [
                {
                    "name": "PersonalBundler"
                }
            ]
        },
        {
            "minRateNQTPerFXT": "1",
            "feeCalculatorName": "MIN_FEE",
            "filters": [
                {
                    "name": "PersonalBundler"
                }
            ]
        }
    ],
    "requestProcessingTime": 1,
    "bundlerRS": "ARDOR-X8ZN-WUJ2-SXY3-FBUYC"
}


Blacklist Bundler

Blacklist a specific bundler. Javadoc

Request:

  • requestType is blacklistBundler
  • account is the account to blacklist bundling
  • adminPassword is a string with the admin password (optional)

Response:

  • done (B) is whether the operation was succesful or not
  • requestProcessingTime (N) is the API request processing time (in millisec)

Blacklist Bundler Example

http://localhost:27876/nxt?
  requestType=blacklistBundler&
  account=ARDOR-X8ZN-WUJ2-SXY3-FBUYC
{
    "requestProcessingTime": 0,
    "done": true
}


Bundle Transactions

Bundle unconfirmed transactions. POST only. Javadoc

Request: Refer to Create Transaction Request for common parameters.

  • requestType is bundleTransactions
  • chain is the chain related to the operation. For bundling transactions it is a must to select chain 1 = ARDOR
  • transactionFullHash is the transaction full hash of the transaction to be bundled
  • transactionFullHash is the transaction full hash of the transaction to be bundled (last transaction to be bundled)
  • feeNQT is the fee in chain NQT
  • feeRateNQTPerFXT is the fee to be paid to bundle the child chain block
  • minBundlerBalanceFXT is the minimum bundler ARDR balance.

Response:

  • Bundled (B) is whether the operation was succesful or not
  • requestProcessingTime (N) is the API request processing time (in millisec)

Bundle Transactions Example

http://localhost:27876/nxt?
  transactionFullHash=8f075e6d74fff62cf57f051fa3acd33422c0295d0463b286224709abb91038ee&
  secretPhrase=IWontTelleyou&
  chain=1&
  deadline=12&
  feeNQT=1000000
{  
   "minimumFeeFQT":"1000000",
   "signatureHash":"437683407247c3048cbc5657c6d84feb6397872fef7736a65bd4e4138f6e3726",
   "transactionJSON":{  
      "senderPublicKey":"39dc2e813bb45ff063a376e316b10cd0addd7306555ca0dd2890194d37960152",
      "chain":1,
      "signature":"f250be38e3d9c2f1699c9474890b738a0da1191aaa4555407420af6fafd0990a64ae8f52a00456ea5c088bd1f429eca903d4a93aedf9fe2688642455f6e296d3",
      "feeNQT":"1000000",
      "type":-1,
      "fullHash":"8f075e6d74fff62cf57f051fa3acd33422c0295d0463b286224709abb91038ee",
      "version":1,
      "phased":false,
      "ecBlockId":"4341673193822741892",
      "signatureHash":"437683407247c3048cbc5657c6d84feb6397872fef7736a65bd4e4138f6e3726",
      "attachment":{  
         "version.ChildChainBlock":1,
         "chain":2,
         "childTransactionFullHashes":[  
            "81ff6dd9d269143c6c986aea322cbfc3e2406d3e900f11420661f5f31296283c"
         ],
         "hash":"364355e53f68de3b621b960253e3716f9cbc5bea81f7feaeecf3cb463f229c69"
      },
      "senderRS":"ARDOR-X5JH-TJKJ-DVGC-5T2V8",
      "subtype":0,
      "amountNQT":"0",
      "sender":"3705364957971254799",
      "ecBlockHeight":17150,
      "deadline":14,
      "transaction":"1783413193026057863",
      "timestamp":10058722,
      "height":2147483647
   },
   "unsignedTransactionBytes":"01000000ff0001e27b99000e0039dc2e813bb45ff063a376e316b10cd0addd7306555ca0dd2890194d379601520000000000000000000000000000000040420f000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000fe42000084e5a340c4b8403c00000000010002000000364355e53f68de3b621b960253e3716f9cbc5bea81f7feaeecf3cb463f229c69",
   "broadcasted":true,
   "requestProcessingTime":21,
   "transactionBytes":"01000000ff0001e27b99000e0039dc2e813bb45ff063a376e316b10cd0addd7306555ca0dd2890194d379601520000000000000000000000000000000040420f0000000000f250be38e3d9c2f1699c9474890b738a0da1191aaa4555407420af6fafd0990a64ae8f52a00456ea5c088bd1f429eca903d4a93aedf9fe2688642455f6e296d3fe42000084e5a340c4b8403c00000000010002000000364355e53f68de3b621b960253e3716f9cbc5bea81f7feaeecf3cb463f229c69",
   "fullHash":"873610a2d9f4bf182af9c2b0b6009d02089149224bc3282555ece500038e4e70"
}


Start / Stop / Get Forging

Start or stop forging with an account, or check to see if an account is forging. POST only. Javadoc startForging, Javadoc stopForging and Javadoc getForging

Request:

  • requestType is either startForging, stopForging or getForging
  • secretPhrase is the secret passphrase of the account (optional for stopForging and getForging if password protected like the Debug Operations)

Response:

  • deadline (N) is the estimated time (in seconds since the last block) until the account will forge a block (startForging and getForging only)
  • hitTime (N) is the estimated time (in seconds since the genesis block) when the account will forge a block (startForging and getForging only)
  • remaining (N) is the deadline less the elapsed time since the last block (getForging only)
  • foundAndStopped (B) is true if forging was stopped, false if forging was already stopped (stopForging only)
  • account (S) is the account number (getForging only)
  • accountRS (S) is the Reed-Solomon address of the account (getForging only)
  • requestProcessingTime (N) is the API request processing time (in millisec)

Note: A getForging request returns errorCode 5 if the account is not forging. If the account has a zero ARDR effectiveBalance, forging can be started but deadline, remainingTime and hitTime will be set to zero.

Start / Stop / Get Forging Example

http://localhost:27876/nxt?
  requestType=startForging&
  secretPhrase=IWontTellYou
{
 "requestProcessingTime": 1,
 "deadline": 0,
 "hitTime": 0
}


Get Guaranteed Balance

Get the balance of an account in ARDR that is confirmed at least a specified number of times. Javadoc

Request:

  • requestType is getGuaranteedBalance
  • account is an account ID
  • numberOfConfirmations is the minimum number of confirmations for a transaction to be included in the guaranteed balance (optional, if omitted or zero then minimally confirmed transactions are included)
  • requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
  • requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

  • guaranteedBalanceNQT (S) is the balance (in NQT) of the account with at least numberOfConfirmations confirmations
  • lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
  • requestProcessingTime (N) is the API request processing time (in millisec)

Get Guaranteed Balance Example

http://localhost:27876/nxt?
  requestType=getGuaranteedBalance&
  account=7114946486381367146&
  numberOfConfirmations=1440
{
 "guaranteedBalanceNQT": "9242231058415",
 "requestProcessingTime": 0
}


Lease Balance

Lease the entire guaranteed balance of ARDR to another account, after 1440 confirmations. POST only. Javadoc

Request: Refer to Create Transaction Request for common parameters.

  • requestType is leaseBalance
  • period is the lease period (in number of blocks, 1440 minimum)
  • recipient is the lessee (recipient) account
  • recipientPublicKey is the public key of the lessee (recipient) account (optional, enhances security of a new account)

Response: Refer to Create Transaction Response.

Lease Balance Example

http://localhost:27876/nxt?
  requestType=leaseBalance&
  period=1440&
  recipient=ARDOR-4VNQ-RWZC-4WWQ-GVM8S&
  secretPhrase=IWontTellYou&
  feeNQT=100000000&
  deadline=60
{
 "signatureHash": "462590bb85b615ddd34d59a1ffdc452a9baee2088044c1b9eb44298e49158f35",
 "unsignedTransactionBytes": "04107977ce013c0057fb6f3a958e320bb49c4e81b4c2cf28b9f25d086c143b473b...",
 "transactionJSON": {
  "senderPublicKey": "57fb6f3a958e320bb49c4e81b4c2cf28b9f25d086c143b473beec228f79ff93c",
  "signature": "4a89702535246fd55bfc4b4691dc4266daa3100e00cdf0caaed57a5ad750da075a...",
  "feeNQT": "100000000",
  "type": 4,
  "fullHash": "251bcd86057c09bb2d055bbeeb9b67ccae861f75d4aada21b3b79a13db9712e1",
  "version": 1,
  "ecBlockId": "6565389899781382679",
  "signatureHash": "462590bb85b615ddd34d59a1ffdc452a9baee2088044c1b9eb44298e49158f35",
  "attachment": {
   "version.EffectiveBalanceLeasing": 1,
   "period": 1440
  },
  "senderRS": "ARDOR-L6FM-89WK-VK8P-FCRBB",
  "subtype": 0,
  "amountNQT": "0",
  "sender": "15323192282528158131",
  "recipientRS": "ARDOR-4VNQ-RWZC-4WWQ-GVM8S",
  "recipient": "17013046603665206934",
  "ecBlockHeight": 280672,
  "deadline": 60,
  "transaction": "13477439723061189413",
  "timestamp": 30308217,
  "height": 2147483647
 },
 "broadcasted": true,
 "requestProcessingTime": 7340,
 "transactionBytes": "04107977ce013c0057fb6f3a958e320bb49c4e81b4c2cf28b9f25d086c143b473b...",
 "fullHash": "251bcd86057c09bb2d055bbeeb9b67ccae861f75d4aada21b3b79a13db9712e1",
 "transaction": "13477439723061189413"
}


Get Next Block Generators

Returns the next block generators ordered by hit time. The list of currently active forgers is first initialized using the block generators with at least 2 blocks generated within the previous 10,000 blocks, excluding accounts without a public key. The list is updated as new blocks are processed. The results are not 100% correct since previously active generators may no longer be running and new generators won't be known until they generate a block. Javadoc

Request:

  • requestType is getNextBlockGenerators
  • limit (N) is the number of next block generators to display.

Response:

  • activeCount (N) is the number of active forging accounts
  • lastBlock (S) is the last block ID on the blockchain
  • generators (A) is an array containing the number of next block generators requested
    • effectiveBalanceFXT (N) is the balance of the account available for forging: the unleased guaranteedBalance of this account plus the leased guaranteedBalance of all lessors to this account
    • accountRS (S) is the Reed-Solomon address of the account
    • deadline (N) is the estimated time (in seconds since the last block) until the account will forge a block
    • account (S) is the account number
    • hitTime (N) is the estimated time (in seconds since the genesis block) when the account will forge a block
  • requestProcessingTime (N) is the API request processing time (in millisec)
  • timestamp (N) is the timestamp (in seconds since the genesis block) when the request was executed
  • height (N) is the height of the blockchain

Get Next Block Generators Example

http://localhost:27876/nxt?
  requestType=getNextBlockGenerators&
  limit=3
{
 "activeCount": 216,
 "lastBlock": "10153073870267066931",
 "generators": [
  {
   "effectiveBalanceFXT": 5400786,
   "accountRS": "ARDOR-8HNT-4ZTF-ZXH3-7RU38",
   "deadline": 4,
   "account": "5982846390354787993",
   "hitTime": 112224054
  },
  {
   "effectiveBalanceFXT": 4061204,
   "accountRS": "ARDOR-HLNR-4HDK-HQUJ-37545",
   "deadline": 35,
   "account": "1263370831364868759",
   "hitTime": 112224085
  },
  {
   "effectiveBalanceFXT": 8847921,
   "accountRS": "ARDOR-ZEKG-CHYB-N8AR-4TQ3U",
   "deadline": 52,
   "account": "3244519536310858286",
   "hitTime": 112224102
  }
  ],
 "requestProcessingTime": 1,
 "timestamp": 112224050,
 "height": 1351776
}