Skip to content

floBlockchainAPI

Jump to bottom
Sai Raj edited this page May 26, 2023 · 1 revision

FLO Blockchain API Operations

floBlockchainAPI object method can be used to send/recieve data to/from blockchain. These functions are asynchronous and return a promise.

NOTE: Most of FLO Blockchain API operations have been promisified. i.e, output needs to be handled using .then and .catch

Example:

floBlockchainAPI.someFunction(parameters)
.then(result => process_resolve(result))
.catch(error => process_reject(error))

Note: for nodejs use require and assign floBlockchainAPI to global

global.floBlockchainAPI = require('/path/to/floBlockchainAPI');

Default values

This module uses some default values. They can be overwritten by assigning values floGlobals.

DEFAULT = {
    blockchain: 'FLO',
    apiURL: {
        FLO: ['https://flosight.ranchimall.net/'],
        FLO_TEST: ['https://flosight-testnet.ranchimall.net/']
    },
    sendAmt: 0.0003,
    fee: 0.0002,
    minChangeAmt: 0.0002,
    receiverID: floGlobals.adminID
}

blockchain

Blockchain to use (FLO or FLO_TEST)

Configured using floGlobals.blockchain

Default value: 'FLO'

apiURL

Default (flosight) API URLs.

Can be overwritten using floGlobals.apiURL

sendAmt

Default send amount (FLO) when amount not specified.

Default value: 0.0003

Can be overwitten using floGlobals.sendAmt

floBlockchainAPI.sendAmt setter and getter can be used to update or get the default sendAmt value. Example:

floBlockchainAPI.sendAmt = 10;
var amount = floBlockchainAPI.sendAmt;

fee

Default fee amount (FLO).

Default value: 0.0002

Can be overwitten using floGlobals.fee

floBlockchainAPI.fee setter and getter can be used to update or get the default sendAmt value. Example:

floBlockchainAPI.fee = 0.1;
var fee = floBlockchainAPI.fee;

minChangeAmt

Minimum change amount required so that change is returned in a transaction.

This is to prevent dust transaction error when broadcasting transactions

Default value: 0.0002

receiverID

Default receiverID for the transactions

Configured using floGlobals.adminID

Base API fetch function

Base fetch function that other functions use to request data from floSight API.

floBlockchainAPI.promisedAPI(apicall, query_params)
floBlockchainAPI.fetch(apicall, query_params)
  1. apicall - API uri
  2. query_params (optional) - search/query params (GET params)
  • Resolves: responseData from the API

Address queries

Balance check

floBlockchainAPI.getBalance(addr)

Requests balance for specified FLO address.

  1. addr - FLO address for which balance has to be retrieved
  • Resolves: balance (Number)

Transaction operations with single sender and single receiver

Create unsigned transaction

floBlockchainAPI.createTx(senderAddr, receiverAddr, sendAmt, floData, strict_utxo)
  1. senderAddr - FLO address from which the data and amount has to be sent.
  2. receiverAddr - Receiver FLO address.
  3. sendAmt - Amount of FLO coins to be sent to receiver.
  4. floData (optional) - FLO data (string, max 1040 characters) (DEFAULT: '')
  5. strict_utxo (optional) - ignore or use unconfirmed UTXOs
    • true: (DEFAULT) ignore unconfirmed UTXOs
    • false: allow unconfirmed UTXOs to be used in tx inputs
  • Resolves: Transaction Hex (String)

Create and broadcast a transaction

floBlockchainAPI.sendTx(senderAddr, receiverAddr, sendAmt, privKey, floData = '')

Sends a transaction to blockchain, resolves transaction id if the broadcast was succsessful.

  1. senderAddr - FLO address from which the data and amount has to be sent.
  2. receiverAddr - Receiver FLO address.
  3. sendAmt - Amount of FLO coins to be sent to receiver.
  4. privKey - private-key of sender to verify sender.
  5. floData (optional) - FLO data (string, max 1040 characters) (DEFAULT: '')
  6. strict_utxo (optional) - ignore or use unconfirmed UTXOs
    • true: (DEFAULT) ignore unconfirmed UTXOs
    • false: allow unconfirmed UTXOs to be used in tx inputs
  • Resolves: TransactionID (String)

Write data in blockchain via transaction

floBlockchainAPI.writeData(senderAddr, data, privKey, receiverAddr)

Writes data into blockchain, resolves transaction id if the broadcast was successful.

  1. senderAddr - FLO address from which the data and amount has to be sent.
  2. data - FLO data (string, max 1040 characters)
  3. privKey - private-key of sender
  4. receiverAddr (optional) - Receiver FLO address. (uses DEFAULT.receiverID if not specified)
  5. options (optional) - Accepts an object with following options
    • strict_utxo: same as in floBlockchainAPI.sendTx
    • sendAmt: uses DEFAULT.sendAmt if not specified
  • Resolves: TransactionID (String)

Merge multiple UTXOs into single UTXO

floBlockchainAPI.mergeUTXOs(floID, privKey, floData = '')

Sends a transaction to blockchain that merges all UTXOs of the given floID.

  1. floID - FLO address of which the UTXOs should be merged.
  2. privKey - private-key of the floID.
  3. floData (optional) - FLO data (string, max 1040 characters) (DEFAULT: '')
  • Resolves: TransactionID (String)

Split UTXOs for parallel sending

floBlockchainAPI.splitUTXOs(floID, privKey, count, floData)

Sends a transaction to blockchain that splits UTXOs into required number of UTXOs. Useful for parallel sending txs without need to wait for previous tx to get confirmation.

  1. floID - FLO address for spliting UTXOs
  2. privKey - private-key of the floID.
  3. count - number of split UTXOs required
  4. floData (optional) - FLO data (string, max 1040 characters) (DEFAULT: '')
  • Resolves: TransactionID (String)

NOTE: Each UTXO split have DEFAULT.sendAmt + DEFAULT.fee FLO amount in them. example, if count = 3, then 3 utxos will be formed each with value 0.0005 (ie, 0.0003 + 0.0002).

Transaction Utility functions

NOTE: Some functions in this category are not promised and directly return values

Signing transactions

floBlockchainAPI.signTx(tx, privateKey, sighashtype)

Signs the transaction using given private-key

  1. tx - (unsigned) transaction hex
  2. privateKey - private-key for signing
  3. sighashtype (optional) - sign hash type for signing. (DEFAULT: 1)
  • Returns: signed_tx_hex (String)

Check Signatures

floBlockchainAPI.checkSigned(tx, bool)

Checks if the given transaction hex is signed or not

  1. tx - transaction hex to check for signatures
  2. bool (optional) - return signed detail
    • true: (DEFAULT) return boolean value for result. (true for signed, false for unsigned or partial signed)
    • false: give detailed sign info for each input
  • Returns: boolean or array

NOTE: for multisig, unsigned inputs have object {s, r, t} when bool parameter is false.

  • s: number of signatures present
  • r: minimum number of signatures required
  • t: total number of signatures possible

Check if transaction is same

floBlockchainAPI.checkIfSameTx(tx1, tx2)

Checks if the given 2 transactions are same (ie, input,output, flodata). Signatures are not considered.

  1. tx1 - transaction hex to compare
  2. tx2 - transaction hex to compare
  • Returns: boolean

Calculate transaction ID

floBlockchainAPI.transactionID(tx)

Calculates the transaction ID from transaction hex

  1. tx - transaction hex for which txid should be calculated
  • Returns: txid (String)

Parse transaction

floBlockchainAPI.parseTransaction(tx)

Parse the given transaction hex

  1. tx - transaction hex to be parsed
  • Resolves: (Object) transaction details

Broadcast transaction

floBlockchainAPI.broadcastTx(signedTxHash)

Broadcasts the signed tx hex and resolves txid if successful

  1. signedTxHash - fully signed transaction hex to be broadcasted
  • Resolves: (String) transaction ID

Wait for transaction confirmation

floBlockchainAPI.waitForConfirmation = function (txid, max_retry = -1, retry_timeout = 20)

Wait until the transaction gets confirmation

  1. txid - transaction ID
  2. max_retry (optional) - maximum retries until exit wait. negative values = Infinite retries (DEFAULT: -1, ie, Infinite retries).
  3. retry_timeout (optional) - interval between wait retries (in seconds) (DEFAULT: 20 seconds)

Sending Transaction with mutiple sender and receivers

Send transaction from/to multiple floIDs

floBlockchainAPI.sendTxMultiple(senderPrivKeys, receivers, floData = '')

Sends a transaction to blockchain from multiple floIDs to multiple floIDs, resolves transaction id if the broadcast was successful.

  1. senderPrivKeys - Array of Private keys of the senders (or) Object of private keys with sendAmount for each floID (eg: { privateKey1: sendAmt1, privateKey2: sendAmt2...}) . Note: If passed as Array, then ratio of the balance of the senders are preserved. If passed as Object uses the amount given.
  2. receivers - Object of receiver floIDs with receive amount (eg: {receiverID1: receiveAmt1, receiver2: receiveAmt2...})
  3. floData (optional) - FLO data (string, max 1040 characters) (DEFAULT: '')
  • Resolves: TransactionID (String)

Write Data from/to multiple floIDs

floBlockchainAPI.writeDataMultiple(senderPrivKeys, data, receivers, options)

Writes data into blockchain from multiple floIDs to multiple floIDs, resolves transaction id if the broadcast was successful.

  1. senderPrivKeys - Array of Private keys of the senders.
  2. Data - FLO data (string, max 1040 characters)
  3. receivers (optional) - Array of receiver FLO Addresses. (uses DEFAULT.receiverID if not specified)
  4. options (optional) - Accepts an object with following options
    • sendAmt: uses DEFAULT.sendAmt if not specified
    • preserveRatio: boolean
      • true: (DEFAULT) preserves the ratio of the balance of senders
      • false: all senders contribute equal amount to the transaction (optional, default is true)
  • Resolves: TransactionID (String)

Multisig transactions

Create unsigned multisig transaction

floBlockchainAPI.createMultisigTx(redeemScript, receivers, amounts, floData, strict_utxo)

Creates a unsigned multisig transaction.

  1. redeemScript - redeem-script of the multisig address
  2. receivers - array of receiver address
  3. amounts - array of receiver amounts
  4. floData (optional) - FLO data (string, max 1040 characters) (DEFAULT: '')
  5. strict_utxo (optional) - ignore or use unconfirmed UTXOs
    • true: (DEFAULT) ignore unconfirmed UTXOs
    • false: allow unconfirmed UTXOs to be used in tx inputs
  • Resolves: Transaction Hex (String)

NOTE: use floBlockchainAPI.signTx to sign later for broadcasting

Send multisig transaction

floBlockchainAPI.sendMultisigTx(redeemScript, privateKeys, receivers, amounts, floData, strict_utxo)

Creates a signed multisig transaction and broadcast it.

  1. redeemScript - redeem-script of the multisig address
  2. privateKeys - array of private keys for the multisig
  3. receivers - array of receiver address
  4. amounts - array of receiver amounts
  5. floData (optional) - FLO data (string, max 1040 characters) (DEFAULT: '')
  6. strict_utxo (optional) - ignore or use unconfirmed UTXOs
    • true: (DEFAULT) ignore unconfirmed UTXOs
    • false: allow unconfirmed UTXOs to be used in tx inputs
  • Resolves: Transaction ID (String)

NOTE: receivers and amounts arrays must be of equal length

Write data in blockchain using multisig address

floBlockchainAPI.writeMultisigData = function (redeemScript, data, privatekeys, receiverAddr = DEFAULT.receiverID, options = {})

Writes data using multisig address and resolves transaction id if the broadcast was successful.

  1. redeemScript - redeem-script of the multisig address
  2. data - FLO data (string, max 1040 characters)
  3. privatekeys - array of private keys for the multisig
  4. receiverID (optional) - Receiver FLO address. (uses DEFAULT.receiverID if not specified)
  5. options (optional) - Accepts an object with following options
    • strict_utxo: same as in floBlockchainAPI.sendTx
    • sendAmt: uses DEFAULT.sendAmt if not specified

Read transaction details from blockchain

Get details of a transaction

floBlockchainAPI.getTx(txid)

Requests the details of a given txid

  1. txid - transaction ID
  • Resolves: transaction_details (Object)

Read transactions in range

floBlockchainAPI.readTxs(addr, options)

readTxs reads transactions of specified address between from and to.

  1. addr - FLO address for which the transactions has to be read.
  2. options - Accepts object with following options
    • after txid: fetch after given txid
    • before txid: fetch before given txid
    • latest: if true, fetch latest first
    • mempool: query mempool or not. allowed values are
      • 'true',true: query tx from mempool
      • 'false',false: ignore tx from mempool
      • 'only': query tx only from mempool
  • Resolves: TransactionList

NOTE: resolves atmost 1000 transactions at a time

Read all transactions

floBlockchainAPI.readTxs(addr, options)

Reads all transactions of specified address(newest first).

  1. addr - FLO address for which the transactions has to be read.
  2. options - Accepts object with following options
    • after txid: fetch after given txid
    • before txid: fetch before given txid
    • latest: if true, fetch latest first
    • mempool: query mempool or not. allowed values are
      • 'true',true: query tx from mempool
      • 'false',false: ignore tx from mempool
      • 'only': query tx only from mempool
  • Resolves: TransactionData (Object)

Read flo data from blockchain

floBlockchainAPI.readData(addr, options = {})

readData reads FLO data from transactions of specified address

  1. addr - FLO address for which the transactions data has to be read.
  2. options - Contains options for filter data from transactions.
    • after : query after the given txid
    • before : query before the given txid
    • mempool : query mempool tx or not (options same as readAllTx) (DEFAULT=false: ignore unconfirmed tx)
    • sentOnly : filters only sent data
    • receivedOnly: filters only received data
    • pattern : filters data that contains pattern as an object key in the JSON string
    • filter : custom filter funtion for floData (eg . filter: d => {return d[0] == '$'})
    • sender : filter flo-id(s) of sender
    • receiver : filter flo-id(s) of receiver
    • tx : (boolean) resolve tx data or not
      • true: resolves an Array of Object with tx details (in .items)
      • false: (DEFAULT) resolves only flo-data (in .data)
  • Resolves: Object {lastItem, items or data (Array)}

Get latest data

floBlockchainAPI.getLatestData = function (addr, caseFn, options = {})

Get the latest flo-data from the given address satisfying the filter conditions

  1. addr - FLO address for which the transactions data has to be read.
  2. caseFn - satisfy case function
  3. options - Contains options for filter data from transactions.
    • after : query after the given txid
    • before : query before the given txid
    • mempool : query mempool tx or not (options same as readAllTx) (DEFAULT=false: ignore unconfirmed tx)
    • sentOnly : filters only sent data
    • receivedOnly: filters only received data
    • sender : filter flo-id(s) of sender
    • receiver : filter flo-id(s) of receiver
    • tx : (boolean) resolve tx data or not
      • true: resolves an Array of Object with tx details (in .items)
      • false: (DEFAULT) resolves only flo-data (in .data)
  • Resolves: Object {lastItem, items or data (Array)}
Clone this wiki locally