Signum Exchange Integration
Signum Exchange Integration Guide
Relevant Details
- Network Name ( Signum )
- Currency Name ( Signa )
- Ticker: ( Signa )
- Decimals: ( 8 )
- Maximum supply: ( 2,158,812,800 )
- Algorithm: ( Proof-of-Capacity-Plus )
- Developers: ( Signum Network )
- Release: ( no ICO, airdrop, or premine )
Prerequisites
- A Signum node running continuously with a fully synchronized blockchain.
- The Signum Reference Software installed, which can be found here.
- A testnet node for QA and testing. Instructions can be found here: How to set up a testnet node.
- Access for the software to communicate on local port 8123 for mainnet communications and local port 6876 for the testnet.
Confirmations – Determining When to Credit a Customer’s Account
Deposits can be credited to a customer’s account after any number of confirmations, but crediting transactions immediately is not recommended. It is recommended that the number of confirmations is set to a minimum of 10. Each transaction contains a deadline after which the transaction will be canceled if it is not included in a block. This deadline will always be either a default of 24 hours or a custom deadline set by the transaction’s initiator. To avoid complication from a transaction being canceled if its block is orphaned and its custom deadline is too short to assure that it is reincluded, further conditions based on the transaction’s timestamp and deadline parameters are recommended ( either for all transactions or conditioned upon the amount of the transaction according to risk management strategy).
- When ( genesis time + timestamp + deadline * 60 ) is greater than ( transaction.blockTime + 23 hours ), recommendation is 10 confirmations
- When ( genesis time + transaction.timestamp + transaction.deadline * 60) is less than (transaction.blockTimestamp + 23 hours), recommendation is 720 confirmations.
Genesis time for the Signum blockchain is GMT: Monday, 11 August 2014 02:00:00 Unix epoch 1407722400
The shorter recommendation of 10 confirmations is appropriate for transactions that have the default deadline of 24 hours. These transactions are automatically reincluded in the event of a blockchain reorganization. The longer recommendation of 1,440 blocks, the maximum depth of a blockchain reorganization, is appropriate for transactions with a custom deadline that is less than 24 hours. After 1,440 confirmations, no combination of deadline and blockchain reorganization can cause a transaction to be canceled.
Monitoring An Exchange Account for Incoming Deposits Using Signum’s REST API
Note: Except for references to messages, the following information applies to message-based and account-based methods for accepting deposits. A subsequent section contains additional information that is specifically applicable to account-based methods.
To monitor an exchange account for incoming deposits, use the getAccountTransactions API call with the following request parameters:
- account – numeric deposit account id or deposit account id in Reed-Solomon format ( always has «S-» as a prefix ).
- timestamp – if specified, returned transactions will be newer than this block timestamp
- type – the type of transaction, for payments this will be 0.
- subtype – the transaction subtype, for payments this will be 0.
- firstIndex – for pagination purposes
- lastIndex – for pagination purposes
- numberOfConfirmations – to exclude transactions with fewer than the required number of confirmations. Set to zero, this will include all transactions, including pending transactions.
Example JSON response: Note: Response includes both incoming and outgoing transactions. Irrelevant items have been excluded.
{ “transactions”: [ { “type”: 2, “subtype”: 1, “timestamp”: 132622393, “deadline”: 1440, “senderPublicKey”: “64ecf79e02001408d86a3148192f10abb94a15f1add7fb7e0d581d0efe406306”, “recipient”: “10446462338210047360”, “recipientRS”: “BURST-5BE2-6SGA-K455-BCCY3”, “amountNQT”: “0”, “feeNQT”: “100000000”, “signature”: “1685ba8dc12b71726406693045b4421e42b1fe57cd42428c6b97701271f1980624f8be54d6ca210fd29bb63abe652ae6beff98095e7931a1df2d82dc6c67e7ef”, “signatureHash”: “155df32a81847c00df529c9d09bc5e1f26618036f68554240b94ab99a50932cb”, “fullHash”: “20aa5e79d5a49b5c07d877fcb4bf85cdc2bb058650f9228f66521799be0bc037”, “transaction”: “6673108509650758176”, “attachment”: { “version.AssetTransfer”: 1, “asset”: “3509939581101213262”, “version.Message”: 1, “message”: “...message text...”, “messageIsText”: true, “quantityQNT”: “10” }, “sender”: “13476626730621357107”, “senderRS”: “BURST-JM3M-MHWM-UVQ6-DSN3Q”, “height”: 548306, “version”: 1, “ecBlockId”: “17903993250352434776”, “ecBlockHeight”: 548297, “block”: “13565806093770253653”, “confirmations”: 115271, “blockTimestamp”: 132622449 }, … more transactions … ]
Select Transactions for Ccrediting to Customer Accounts or for Display as Pending by Looping Through This Array
Relevant items include:
- sender – the sender’s numeric account id
- senderRS – the sender’s account id in Reed-Solomon format
- confirmations – the number of confirmations received
- amountNQT – the amount sent in NQT form ( planck, which is analogous to satoshi )
- attachment.message – only present if a plain text message is attached. attachment.messageIsText will also be set to «true» (string)
- attachment.encryptedMessage – only present if an encrypted message is attached.
- timestamp – the time the transaction was made, in seconds, since the genesis block
- blockTimestamp – the time the block was created, in seconds, since the genesis block
Encrypted Message Decryption
When an encrypted message is present, there is an object which contains two keys ( data and nonce ). To decrypt the message, use the decryptFrom API call with the following parameters:
- account – account id that sent the encrypted message
- data – the encrypted message data extracted from transaction.attachment.encryptedMessage.data
- nonce – the encrypted message nonce extracted from transaction.attachment.encryptedMessage.nonce
- decryptedMessageIsText – set to “true” if the message to be decrypted is text
- secretPhrase – passphrase for the account receiving the encrypted message
Example JSON response:
{ “decryptedMessage”: “test message”, “requestProcessingTime”: 2 }
Showing Pending Deposits
Generally, pending deposits are those deposits contained within the getAccountTransactions API response that do not meet the requirements to be credited to customer accounts. These amounts can be displayed as pending until the transactions appear with the required number of confirmations in a subsequent API call response.
Note: Pending transactions can be retrieved separately by setting the confirmations in the previous getAccountTransactions API call to the number of confirmations required to credit a deposit to a customer account. The timestamp ( +1 ) from the last block processed can then be passed to the ?????????? API call, which will return the pending deposits only ( deposits without the required number of confirmations ).
To get the last block timestamp, look at the last processed transaction’s blockTimestamp or use the getBlockchainStatus API ( no request parameters needed ).
URL: http://localhost:6876/burst?requestType=getBlockchainStatus
{"application":"BRS","version":"v2.5.3","time":205127894,"lastBlock":"5090549854675467835","cumulativeDifficulty":"137040818013442624252","numberOfBlocks":848755,"lastBlockchainFeeder":"173.249.1.215","lastBlockchainFeederHeight":848754,"isScanning":false,"requestProcessingTime":0}
Account-Based Method: Creating Customer Accounts
To get the account id and public key for a new account, a new random passphrase must be generated. The passphrase should be very strong and contain at least 35 random characters.
Use the getAccountId API call using only one of the following parameters:
- secretPhrase – account passphrase
- publicKey – account’s public key
URL: http://localhost:6876/burst?requestType=getAccountId&secretPhrase=1234
Example JSON response: ( using the secretPhrase parameter ):
{ “accountRS”: “BURST-5WUN-YL5V-K29F-F43EJ”, “publicKey”: “fddcda69eeca58e5d783ad1032d080d2758a4e427881b6a4a6fe43d9e7f4ac34”, “requestProcessingTime”: 2, “account”: “15577989544718496596” }
The new account number can be extracted from the accountRS field ( Example: S-5WUN-YL5V-K29F-F43EJ ).
The new account will only be protected by the 64-bit account address. For the account to be protected at the 256-bit level, the account must be activated. Activation occurs when the account’s public key is published to the blockchain.
If the account has never had an incoming transaction, you will also need to display the publicKey. The public key no longer needs to be displayed after an account has its first incoming transaction.
Tracking New Account-Based Deposits
The procedures for tracking account based-deposits can be accomplished using the same procedure outlined for message-based deposits. The procedure would need to be run for each individual account in a loop.
The alternative procedure is to inspect each block and filter the transactions that match customer accounts.
To check for new blocks, use the getBlockchainStatus API call.
URL: http://localhost:6876/burst?requestType=getBlockchainStatus
Example JSON response:
{"application":"BRS","version":"v2.5.3","time":205127894,"lastBlock":"5090549854675467835","cumulativeDifficulty":"137040818013442624252","numberOfBlocks":848755,"lastBlockchainFeeder":"173.249.1.215","lastBlockchainFeederHeight":848754,"isScanning":false,"requestProcessingTime":0}
Relevant items include:
- lastBlock (block id)
- numberOfBlocks (height)
If numberOfBlocks is different from the previous execution of this API request, new blocks have been generated. New transactions from these blocks can be evaluated for crediting to customer accounts. You should save the last Block id in your database for making this comparison.
Use the getBlock API to get the block at a particular height. Example (10 confirmations).
URL: http://localhost:6876/burst?requestType=getBlock
Example JSON response:
{"block":"10582701432261822139","height":850187,"generator":"7475138834544103529","generatorRS":"BURST-P65B-7AZV-N3YX-89AHH","generatorPublicKey":"f6c171764c4413a42d2233d5ec3c615c3a2d4717d753aa7f405e0db36d3d5925","nonce":"5377084250857597027","scoopNum":1708,"timestamp":205468176,"numberOfTransactions":3,"totalAmountNQT":"99094245","totalFeeNQT":"4410000","blockReward":"182","payloadLength":1717,"version":3,"baseTarget":"76231","previousBlock":"16870620497447807269","payloadHash":"b31205318ef64800d04f5ede85a8309778e952983ee53d6e578e66fabca64b35","generationSignature":"3a89e11cde93de1cd52340ebf59292e5461cc261cac9bfbd96941f5c438dc2eb","previousBlockHash":"25e9cc42f57b20ea048ac84186345feff7c69d8628f12f1964798f92938bbdae","blockSignature":"e8731f87d67183baff43cc69ad720ce84596c99b1e318bfb75c39b6c69f0b00b63db0f3c5bc56db9f1985d67ef870d2f917fba769aa39920f5dcd3c3a2605e7c","transactions":["12770120572199710655","707023503805754980","5165099444787440228"],"requestProcessingTime":1}
Pass the numberOfBlocks parameter from the getBlockchainStatus API response after subtracting 11 from this value.
- height – the height of the block, zero-based
- includeTransactions – set to true to return the array of transactions included in the block
For each transaction, if the recipientRS field matches one of the deposit accounts generated for your customers, this is an incoming deposit. Apply the same procedures outlined in the above sections concerning qualifying transactions according to the number of confirmations and deadline.
Credit the user’s internal balance and transfer the funds to your hot wallet.
After all transactions of this block have been checked, see if you’ve processed the previous block before or not. If not, traverse through the previous blocks until you reach the last processed block.
Processing Withdrawal Requests
For a customer to make a withdrawal, a specific account must be specified. When this account id is received, verify that the account has a public key.
To verify that an account has a public key, use the getAccountPublicKey API call. This API requires the following parameter:
- account – the account for which the public key is requested
URL: http://localhost:6876/burst?requestType=getAccountPublicKey&account=BURST-C6L6-UQ5W-RBJK-AWDSJ
Example JSON response if the account has a public key:
{«publicKey»:»9fbd126b68603e721f71ed154b85c2da7c0137f9f156d05a98361da2f109d40b»,»requestProcessingTime»:0}
Example JSON response if the account does not have a public key:
{ «errorCode»: 5, «errorDescription»: «Unknown account» }
If the account does not have a public key, it is a new account that has not yet been activated. If possible, display a message to the customer as follows: «The account provided has not yet been activated. To activate your account, use your wallet’s account activation service, make an outgoing transaction from the account to activate it, or refer to your documentation for alternative methods».
When a customer provides the public key, you can verify that it is correct using the getAccountID API call using the following parameters:
- secretPhrase – account passphrase
- publicKey – account public key
Example JSON Response:
{«accountRS»:»BURST-C6L6-UQ5W-RBJK-AWDSJ», «publicKey»: «28f56a81e0f8555b07eacffd0e697b21cbbbdf3cf620db14522732b763564f13», «requestProcessingTime»:0,»account»:»9827273118446850628″}
If the response accountRS matches the account id, the funding request is in good order.
Funding Withdrawal Requests
To fund a withdrawal request, use the sendMoney API call. This request must be sent using HTTP POST. The required parameters are as follows:
- recipient – recipient’s account address
- amountNQT – the amount of BURST (in NQT)
- feeNQT – transaction fee for the transaction in NQT.
- secretPhrase – sender’s account passphrase
- deadline – deadline for the transaction in minutes. This should be set to the maximum value of 1440.
- recipientPublicKey – recipient account’s public key as provided by the customer. This is only needed if the customer’s account does not have a public key. (on the first transaction)
At the moment (v1.9.2), the recipientPublicKey is optional; however, not specifying it puts the user’s funds at risk. The recipientPublicKey is mandatory if you will be attaching an encrypted message to a withdrawal transaction from a new account.
Example JSON response: (A correctly executed response will always contain the “transaction” field. This represents the newly created transaction id. If there is an error, you will receive an applicable response.)
{ "fullHash": “10788f7ad3f145b5209da6145327d7fed869…”, .......... }
Example JSON response indicating an error:
{ "errorCode": 5, "errorDescription": "Unknown account" }
Adding A Message to A Transaction
Allowing the customer to add a message on your withdrawal page is recommended for coordinating with other services that use a message-based deposit system.
Plain text and encrypted messages are not mutually exclusive. Both can be sent in the same transaction.
To create the message, use the encryptTo API call. Note:
Required parameters for a plain text message are as follows:
- message – a plain text message.
- messageIsText – should be set to the string “true” if text.
Required parameters for an encrypted message are as follows:
- messageToEncrypt – a plain text message that should be encrypted.
- messageToEncryptIsText – should be set to the “true” (string) if text.
Hot and Cold Wallets
It is not recommended that all customer’s deposits be kept in a single wallet hot wallet for which the passphrase is stored on a main server. A cold wallet is recommended for holding the majority of the deposits and a manual transaction from the cold wallet to the hot wallet be made when a portion of the deposits needs to be available for day-to-day operations.
Signum Account Format
The account ID is stored internally as a 64 bit signed long variable. When used in APIs, it is usually returned as both an unsigned number represented as a string and as an alphanumeric Reed-Solomon representation starting with a “S-” prefix.
Example: S-ER8M-SYV3-R7EK-EUF3L
In API request parameters and response JSON, you will find both representations. The numeric representation is typically displayed as account, sender, and recipient.
The alphanumeric representation is typically displayed as accountRS, senderRS, recipientRS (added “RS”). RS stands for Reed-Solomon.
This form of address improves reliability by introducing redundancy that can detect and correct errors when entering and using account ID’s.
Signum and NQT Amounts
To be used in API calls, all amounts must be converted to NQT format.
NQT is the name given to 0.00000001 Signa ( 10^(-8) in mathematical shorthand ).
The NQT to Signa ratio is equal to the Satoshi to Bitcoin ratio.
1 Signa = 100,000,000 NQT. To convert Signum to NQT, multiply the amount of Signa by 100,000,000.
Token(Asset) and currency QNT amounts
Each Token and Currency (generally referred to as “Holding”) has a specific number of decimal positions to which this holding is divisible.
API requests require the holding quantity to be specified as a whole number without decimal positions. Responses are in the same format.
We refer to this value as QNT. For example, when transferring 12.34 units of holding XYZ (which has 4 decimal positions), specify the QNT value as 123400.
Minimum Fee
Currently, all outgoing transactions require a minimum transaction fee of 735000 NQT.
Use the suggestFee API call to receive the cheap, standard, and priority suggestions.
Account Security
Deposit accounts need to be protected with a strong passphrase and protected with a public key before deposits are accepted.
*Each address and public key combination (account) is retained permanently in the blockchain, even if it has a zero balance. For this reason, provided internal systems permit using one of the preferred methods, the use of throwaway addresses is discouraged.