Server Information Operations

Event Register

Create, modify or remove an event listener which can report server events via Event Wait. POST only.

Request:

• requestType is eventRegister

• event is one of multiple server events from the following list of event names: (optional, default is all possible events)

  • Block.BLOCK_GENERATED

  • Block.BLOCK_POPPED

  • Block.BLOCK_PUSHED

  • Peer.ADD_INBOUND

  • Peer.ADDED_ACTIVE_PEER

  • Peer.BLACKLIST

  • Peer.CHANGED_ACTIVE_PEER

  • Peer.DEACTIVATE

  • Peer.NEW_PEER

  • Peer.REMOVE

  • Peer.REMOVE_INBOUND

  • Peer.UNBLACKLIST

  • Transaction.ADDED_CONFIRMED_TRANSACTIONS

  • Transaction.ADDED_UNCONFIRMED_TRANSACTIONS

  • Transaction.REMOVE_UNCONFIRMED_TRANSACTIONS

• event is one of multiple server events (optional)

⋮

• add is true to add events to an existing listener (optional, omit if remove is true)

• remove is true to remove events from an existing listener (optional, omit if add is true)

• 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)

Note: To create a new event listener, omit both add and remove. To remove an existing event listener, set remove to true and omit event; all registered events will be removed, any outstanding Event Wait will be completed and the listener will be deactivated.

Note: An event listener is automatically deactivated whenever all registered events are removed or if Event Wait is not called frequently enough, according to the PRIZM.apiEventTimeout property. The timeout is not precise; the removal process runs every PRIZM.apiEventTimeout / 2 seconds, so that many extra seconds may elapse before removal; the first Event Wait call should be made immediately after registration to avoid deactivation.

Note: Each API user (with a unique address) can create only one event listener. When a new one is created, it will replace an existing one. The maximum number of unique users is controlled by the PRIZM.maxEventUsersproperty.

Response:

• registered is true if the operation completed successfully

• 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)

Example: Refer to Event Register example.

Event Wait

Wait for events registered with Event Register. POST only.

Request:

• requestType is eventWait

• timeout is the amount of time (in seconds) to wait for an event before the call returns (optional, default and maximum is the PRIZM.apiEventTimeout property)

• 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)

Notes: The call returns immediately if one or more events have occurred since the last call; multiple events are all returned together. If a new call is made before the last one returns, the timeout timer resets to the new value. Event registration expires if wait calls are not made frequently enough, according to the PRIZM.apiEventTimeout property.

Response:

• events (A) is an array of event objects each of which has the following fields:

  • name (S) is the name of the event (refer to Event Register for the list of event names)

  • ids (A) is an array of identifiers, depending on the type of event:

    • block string identifier (S) for a block event

    • peer network address (S) for a peer event

    • transaction string identifier (S) for a transaction event

• 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)

Example: Refer to Event Wait example.

Get Blockchain Status

Get the blockchain status.

Request:

• requestType is getBlockchainStatus

Response:

• currentMinRollbackHeight (N) is the current minimum rollback height

• numberOfBlocks (N) is the number of blocks in the blockchain (height + 1)

• isTestnet (B) is true if the node is connected to testnet, false otherwise

• includeExpiredPrunable (B) is the value of the PRIZM.includeExpiredPrunable property

• requestProcessingTime (N) is the API request processing time (in millisec)

• version (S) is the application version

• maxRollback (N) is the value of the PRIZM.maxRollback property

• lastBlock (S) is the last block ID on the blockchain

• application (S) is application name, typically NRS

• isScanning (B) is true if the blockchain is being scanned by the application, false otherwise

• isDownloading (B) is true if a download is in progress, false otherwise; true when a batch of more than 10 blocks at once has been downloaded from a peer, reset to false when an attempt to download more blocks from a peer does not result in any new blocks

• cumulativeDifficulty (S) is the cumulative difficulty

• lastBlockchainFeederHeight (N) is the height of the last blockchain of greatest cumulative difficulty obtained from a peer

• maxPrunableLifetime (N) is the maximum prunable lifetime (in seconds)

• time (N) is the current timestamp (in seconds since the genesis block)

• lastBlockchainFeeder (S) is the address or announced address of the peer providing the last blockchain of greatest cumulative difficulty

• blockchainState (S) Current state of this node's blockchain (UP_TO_DATE or DOWNLOADING)

Example: Refer to Get Blockchain Status example.

Get Constants

Get all defined constants.

Request:

• requestType is getConstants

Response:

• maxBlockPayloadLength (N) is the maximum block payload length (in bytes)

• maxArbitraryMessageLength (N) is the maximum length (in bytes) of an arbitrary message

• maxPrunableMessageLength (N) is the maximum length (in bytes) of a prunable message

• maxTaggedDataDataLength (N) is the maximum length (in bytes) of tagged data

• maxPhasingDuration (N) is the maximum allowed phasing duration in block height

• epochBeginning (N) is the time in milliseconds when genesis block was created

• genesisAccountId (S) is the genesis account number

• genesisBlockId (S) is the genesis block ID

• transactionTypes (A) is an array of defined transaction types and subtypes (refer to the example below)

• transactionSubTypes (A) is an array of defined transaction subtypes and subtypes (refer to the example below)

• peerStates (A) is an array of defined peer states (refer to the example below)

• currencyTypes (A) is an array of defined currency types (refer to the example below)

• disabledAPIs (A) is an array of configured disabled apis (refer to the example below)

• apiTags (A) is an array of defined api tags (refer to the example below)

• disabledAPITags (A) is an array of configured disabled api tags (refer to the example below)

• votingModels (A) is an array of defined voting models (refer to the example below)

• holdingTypes (A) is an array of defined holding types (refer to the example below)

• minBalanceModels (A) is an array of defined minimum balance models (refer to the example below)

• shufflingStages (A) is an array of defined shuffling stages (refer to the example below)

• shufflingParticipantStates (A) is an array of defined shuffling participant states (refer to the example below)

• hashAlgorithms (A) is an array of defined hash algorithms (refer to the example below)

• mintingHashAlgorithms (A) is an array of defined minting hash algorithms (refer to the example below)

• phasingHashAlgorithms (A) is an array of defined phasing hash algorithms (refer to the example below)

• requestTypes (A) is an array of decined request types (refer to the example below)

Example: Refer to Get Constants example.

Get Plugins

Get a list of all installed plugins on the server.

Request:

• requestType is getPlugins

Response:

• plugins (A) is an array of plugin names (S)

• requestProcessingTime (N) is the API request processing time (in millisec)

Example: Refer to Get Plugins example.

Get State

Get the state of the server node and network.

Request:

• requestType is getState

• includeCounts is true if the fields beginning with numberOf... are to be included (optional); password protected like the Debug Operations if true.

Response:

• numberOfPeers (N) is the number of known peers on the network

• numberOfGoods (N) is the number of DGS goods in the blockchain

• numberOfPolls (N) is the number of polls in the blockchain

• numberOfUnlockedAccounts (N) is the number of unlocked accounts on this node

• numberOfTransfers (N) is the number of AE transfers in the blockchain

• includeExpiredPrunable (B) is the value of the PRIZM.includeExpiredPrunable property

• numberOfOrders (N) is the number of AE orders in the blockchain

• numberOfTransactions (N) is the number of transactions in the blockchain

• maxMemory (N) is the maximum amount of memory the node may use (in Bytes)

• maxRollback (N) is the value of the PRIZM.maxRollback property

• numberOfOffers (N) is the number of buy currency offers in the blockchain

• isDownloading (B) is true if a download is in progress, false otherwise; true when a batch of more than 10 blocks at once has been downloaded from a peer, reset to false when an attempt to download more blocks from a peer does not result in any new blocks

• isScanning (B) is true if this node is scanning the blockchain, false otherwise

• cumulativeDifficulty (S) is the current cumulative forging difficulty

• numberOfPrunableMessages (N) is the number of prunable messages in the blockchain

• freeMemory (N) is the amount of free memory on this node (in Bytes)

• peerPort (N) is the port used for connecting to peers

• availableProcessors (N) is the number of processors on this node

• numberOfAccounts (N) is the number of accounts in the blockchain

• needsAdminPassword (B) is true if the PRIZM.disableAdminPassword property is false

• currentMinRollbackHeight (N) is the current minimum rollback height

• numberOfBlocks (N) is the number of blocks (height + 1) in the blockchain

• isTestnet (B) is true if the node is connected to testnet, false otherwise

• numberOfCurrencyTransfers (N) is the number of currency transfers in the blockchain

• requestProcessingTime (N) is the API request processing time (in millisec)

• version (S) is the software version on this node

• lastBlock (S) is the last block address

• totalMemory (N) is the amount of memory this node is using (in Bytes)

• application (S) is the name of the software running on this node (typically NRS)

• numberOfActivePeers (N) is the number of active peers on the network

• lastBlockchainFeederHeight (N) is the height of the last blockchain feeder

• maxPrunableLifetime (N) is the maximum prunable lifetime (in seconds)

• time (N) is the current node time (in seconds since the genesis block)

• numberOfAskOrders (N) is the number of AE ask orders in the blockchain

• lastBlockchainFeeder (S) is the announced name of the feeder of the last blockchain

• isOffline (B) is true if this node is connected to other peers, false otherwise

Example: Refer to Get State example.

Get Time

Get the current time.

Request:

• requestType is getTime

Response:

• time (N) is the current time (in seconds since the genesis block).

• requestProcessingTime (N) is the API request processing time (in millisec)

Example: Refer to Get Time example.