General Notes
Genesis Block
Many API requests make reference to the genesis block. FYI, the genesis block's ID is 7024118705028086222.
Flexible Account IDs
All API requests that require an account ID accept either an account number or the corresponding Reed-Solomon address.
Quantity Units PRIZM and NQT
The PRIZM system has a currency PRIZM used to quantify value in the system. Like all currencies, PRIZM circulates in the system, moving from one user to another by payments and purchases. Also, a small fee is required for every transaction, including those in which no PRIZM is transfered, such as simple messages. This fee goes to the owner of the node that forges (generates) the new block containing the transaction that is accepted onto the blockchain.
Internally, the currency is still stored in integer form in units of NQT, where 1 PRIZM = 100 NQT. All parameters and fields in the API involving a quantity of PRIZM are denominated in units of NQT, for example feeNQT. The only exception is the field effectiveBalancePrizm, used in forging calculations.
The PRIZM system can be thought of as an asset owned by all who posses PRIZM. In this sense, PRIZM quantifies ownership of or stake in the system. Stakeholders are entitled to forge blocks and collect transaction fees in proportion to the amount of PRIZM they possess.
Creating Unsigned Transactions
All API requests that create a new transaction will accept either a secretPhrase or a publicKey parameter:
If secretPhrase is supplied, a transaction is created, signed at the server, and broadcast by the server as usual.
If only a publicKey parameter is supplied as a 64-digit (32-byte) hex string, the transaction will be prepared by the server and returned in the JSON response as transactionJSON without a signature. This JSON object along with secretPhrase can then be supplied to Sign Transaction as unsignedTransactionJSON and the resulting signed transactionJSON can then be supplied to Broadcast Transaction. This sequence allows for offline signing of transactions so that secretPhrase never needs to be exposed.
unsignedTransactionBytes may be used instead of unsigned transactionJSON when there is no encrypted message. Messages to be encrypted require the secretPhrase for encryption and so cannot be included in unsignedTransactionBytes.
Escrow Operations
(disabled)
Prunable Data
Prunable data can be removed from the blockchain without affecting the integrity of the blockchain. When a transaction containing prunable data is created, only the 32-byte sha256 hash of the prunable data is included in the transactionBytes, not the prunable data itself. The non-prunable signed transactionBytes are used to verify the signature and to generate the transaction's fullHash and ID; when the prunable part of the transaction is removed at a later time, none of these operations are affected.
Prunable data has a predetermined minimum lifetime of two weeks (24 hours on the Testnet) from the timestamp of the transaction. Transactions and blocks received from peer nodes are not accepted if prunable data is missing before this time has elapsed. After this time has elapsed, prunable data is no longer included with transactions and blocks transmitted to peer nodes, and is no longer included in the transaction JSON returned by general-purpose API calls such as Get Transaction; the only way to retrieve it, if still available, is through special-purpose API calls such as Get Prunable Message.
Expired prunable data remains stored in the blockchain until removed at the same time derived tables are trimmed, which occurs automatically every 1000 blocks by default. Use Trim Derived Tables to remove expired prunable data immediately.
Prunable data can be preserved on a node beyond the predetermined minimum lifetime by setting the PRIZM.maxPrunableLifetime property to a larger value than two weeks or to -1 to preserve it indefinitely. To force the node to include such preserved prunable data when transactions and blocks are transmitted to peer nodes, set the PRIZM.includeExpiredPrunables property to true, thus making it an archival node.
Currently, there is one variety of prunable data in the PRIZM system: prunable Arbitrary Messages. It has a maximum prunable data length of 42 kilobytes.
Properties Files
The behavior of some API calls is affected by property settings loaded from files in the prizm-dist/conf directory during PRIZM server intialization. This directory contains the prizm.default.properties and logging-default.propertiesfiles, both of which contain default property settings along with documentation. A few of the property settings can be obtained while the server is running through the Get Blockchain Status and Get State calls.
It is recommended not to modify default properties files because they can be overwritten during software updates. Instead, properties in the default files can be overridden by including them in optional prizm.properties and logging.properties files in the same directory. For example, a prizm.properties file can be created with the contents:
prizm.savePeers=true
Admin Password
Some API functions take an adminPassword parameter, which must match the PRIZM.adminPassword property unless the PRIZM.disableAdminPassword property is set to true or the API server only listens on the localhost interface (when the PRIZM.apiServerHost property is set to 127.0.0.1).
All Debug Operations require adminPassword since they require some kind of privilege. On some functions adminPassword is used so you can override maximum allowed value for lastIndex parameter, which is set to 100 by default by the PRIZM.maxAPIRecords property. Giving you the option to retrieve more than objects per request.
Roaming and Light Client Modes
The remote node to use when in roaming and light client modes is selected randomly, but can be changed manually in the UI, or using the new set API Proxy Peer API, or forced to a specific peer using the PRIZM.forceAPIProxyServerURL property.
Remote nodes can be blacklisted from the UI, or using the Blacklist API Proxy Peer API. This blacklisting is independent from peer blacklisting. The API proxy blacklisting period can be set using the PRIZM.apiProxyBlacklistingPeriod property (default 1800000 milliseconds).
API requests that require sending the secret phrase, shared key, or admin password to the server, for features like forging, shuffling, or running a funding monitor, are disabled when in roaming or light client mode.
Last updated