README
utxoninja
Bitcoin and Paymail Management Done Right
The code is on GitHub and the package is available through NPM.
There is a web interface that wraps this library available at ninja.babbage.systems.
Refer to the Dojo API docs for additional, useful information.
With the exception of getTransactionWithOutputs
(which just automates the creation and signing of the simpler transactions), most of the functions here are just one-to-one mappings of the Dojo API endpoints themselves. HTTP, API request authentication and the parsing of responses are handled for you by this library.
getTransactionWithOutputs after funding your account
To get started making transactions, you should check outIf you need help, don't hesitate to send a message to Ty Everett on the Atlantis Slack.
API
Table of Contents
- getPaymail
- setPaymail
- getSettings
- setSettings
- Avatar
- getAvatar
- setAvatar
- GetTransactionsTx
- GetTransactionsResult
- getTransactions
- GetPendingTransactionsTx
- getPendingTransactions
- getTotalOfAmounts
- getTotalValue
- GetTxWithOutputsOutput
- GetTxWithOutputsResult
- getTransactionWithOutputs
- TxRedeemableOutput
- TxOutput
- InputTemplate
- OutputTemplate
- TransactionTemplate
- TxInputEnvelope
- createTransaction
- processTransaction
- processPendingTransactions
- markMissingTxInputsAsSpent
- TransactionOutputDescriptor
- getTransactionOutputs
- updateTransactionStatus
- updateOutpointStatus
getPaymail
Returns the current Paymail handle
Parameters
obj
Object All parameters are given in an object (optional, default{}
)
Returns Promise<String> The Paymail handle
setPaymail
Changes the Paymail handle of the user. NOTE that the old handle will be available for others to use. NOTE that to prevent span, you may only do this if there is at least one unspent output under Dojo management.
Parameters
obj
Object All parameters are given in an object (optional, default{}
)
Returns Promise<Object> A success object with status: "success"
getSettings
Returns the current receive policy
Parameters
obj
Object All parameters are given in an object (optional, default{}
)
Returns Promise<Object> The receive policy of the user, see the receive policy section of the Dojo docs
setSettings
Sets a new receive policy
Parameters
obj
Object All parameters are given in an object (optional, default{}
)obj.xprivKey
String The key of the userobj.config
Object? Config object, see config section (optional, defaultCONFIG
)obj.settings
Object A receive policy object. See the Dojo API docs for details on the fields in the receive policy (optional, default{}
)
Returns Promise<Object> A success object with status: "success"
Avatar
Type: Object
Properties
getAvatar
Returns the name and photo URL of the user
Parameters
obj
Object All parameters are given in an object (optional, default{}
)
Returns Promise<Avatar> The avatar of the user
setAvatar
Sets a new name and photo URL
Parameters
obj
Object All parameters are given in an object (optional, default{}
)
Returns Promise<Object> A success object with status: "success"
GetTransactionsTx
Type: Object
Properties
txid
String The transaction IDamount
Number The number of satoshis added or removed from Dojo by this transactionstatus
String The current state of the transaction. Common statuses arecompleted
andwaitingForSenderToSend
.senderPaymail
String The Paymail handle of the person who sent the transactionrecipientPaymail
String The Paymail handle of the person who received the transactionisOutgoing
Boolean Whether or not the transaction was created withcreateTransaction
note
String The human-readable tag for the transaction, provided by the person who initiated itcreated_at
String The time the transaction was registered with the DojoreferenceNumber
String The Dojo reference number for the transactionlabels
Array<String> A set of all the labels affixed to the transaction
GetTransactionsResult
Type: Object
Properties
totalTransactions
Number The number of transactions in the complete settransactions
Array<GetTransactionsTx> The specific transactions from the set that were requested, based onlimit
andoffset
getTransactions
Returns a set of transactions that match the criteria
Parameters
obj
Object All parameters are given in an object (optional, default{}
)obj.xprivKey
String The key of the userobj.config
Object? Config object, see config section (optional, defaultCONFIG
)obj.involving
String? Only include transactions sent to or reveiced from this Paymail handleobj.status
String? If provided, only transactions with the given status will be returnedobj.label
String? Only include transactions affixed with this labelobj.limit
Number Include only this maximum number of transactions in the set (optional, default25
)obj.offset
Number Include transactions offset by this number in the full set (optional, default0
)obj.orderBy
String Sort order, can benewest-first
oroldest-first
(optional, defaultnewest-first
)
Returns Promise<GetTransactionsResult> The transactions and the total size of the set
GetPendingTransactionsTx
Type: Object
Properties
amount
Number The number of satoshis added or removed from Dojo by this transactionsenderPaymail
String The Paymail handle of the person who sent the transactioncreated_at
String The time the transaction was registered with the DojoreferenceNumber
String The Dojo reference number for the transaction
getPendingTransactions
Returns a set of all transactions that need to be signed and submitted, or canceled
Parameters
obj
Object All parameters are given in an object (optional, default{}
)
Returns Promise<Array<GetPendingTransactionsTx>> The array of pending transactions
getTotalOfAmounts
Returns the total of the amounts of transactions that fall under certain criteria
Parameters
obj
Object All parameters are given in an object (optional, default{}
)obj.xprivKey
String The key of the userobj.config
Object? Config object, see config section (optional, defaultCONFIG
)obj.involving
String? The Paymail handle of a user who must be involved with the transactionsobj.label
String? The label that must be affixed to the transactionsobj.direction
String Must be either "incoming" or "outgoing", transactions in only one direction can be totaledobj.startTime
Number? The earlies time of the transactions to include, an epoch timestamp in secondsobj.endTime
Number? The latest time of the transactions to include, an epoch timestamp in seconds
Returns Promise<Object> An object containing total
, a number of satoshis
getTotalValue
Returns the total of unspent outputs
Parameters
obj
Object All parameters are given in an object (optional, default{}
)
Returns Promise<Object> An object containing total
, a non-negative number of satoshis
GetTxWithOutputsOutput
Type: Object
Properties
script
String The hex representing the locking script of the outputsatoshis
Number The number of satoshis to put in the output
GetTxWithOutputsResult
Type: Object
Properties
rawTx
String The serialized, signed transaction that is ready for broadcastreferenceNumber
String The reference number that should now be provided back toprocessTransaction (or
updateTransactionStatus`)inputs
Object This is the fully-formedinputs
field of this transaction, as per the SPV Envelope specification.amount
Number The amount of the transaction
getTransactionWithOutputs
Creates and signs a transaction with specified outputs, so that it can be processed with processTransaction
. This is a higher-level wrapper around createTransaction
so that you do not need to manually handle signing, when you are not providing any non-Dojo inputs.
Use this by default, and fall back to createTransaction
if you need more customization.
Parameters
obj
Object All parameters are given in an object (optional, default{}
)obj.xprivKey
String The key of the userobj.config
Object? Config object, see config section (optional, defaultCONFIG
)obj.outputs
Array<GetTxWithOutputsOutput> A set of outputs to include, each withscript
andsatoshis
.obj.rPuzzleInputSigningWIF
String? A WIF-formatted private key that, if provided, requires at least one input to be P2RPH, and uses the key to sign when redeeming it.obj.feePerKb
Number The number of satoshis to pay per KB of block space used by this transaction. (optional, default500
)obj.labels
Array<String>? A set of label strings to affix to the transactionobj.inputs
Object? Input scripts to spend as part of this transaction. This is an object whose keys are TXIDs and whose values are Everett-style transaction envelopes that contain an additional field calledoutputsToRedeen
. This is an array of objects, each containingindex
andunlockingScript
properties. Theindex
property is the output number in the transaction you are spending, andunlockingScript
is the hex scriptcode that unlocks the satoshis. Note that you should create any signatures withSIGHASH_NONE | ANYONECANPAY
or similar so that the additional Dojo outputs can be added afterward without invalidating your signature. (optional, default{}
)obj.autoProcess
Boolean Whether the transaction should be processed automatically with processTransaction. Note that this will returnmapiResponses
andnote
instead of referenceNumber (optional, defaultfalse
)
Returns Promise<GetTxWithOutputsResult> The serialized transaction, inputs, reference number and amount
TxRedeemableOutput
Type: Object
Properties
index
Number The index of the output to redeem in the transactionunlockingScriptLength
Number The byte length of the unlocking script you intend to use to unlock this output
TxOutput
Type: Object
Properties
satoshis
Number The amount of satoshis that will be in the outputscript
String The hex string representing the output locking script
InputTemplate
Type: Object
Properties
providedBy
String Identifies the provider(s) of the output(s) to redeem trom the associated transaction. Can be "dojo", "you" (for externally-provided inputs), or "you-and-dojo"outputsToRedeem
Array<Number> A set of numbers indicating the index of each output that should be redeemed from this transactionrawTx
String As specified in the SPV envelope specification, the serialized transaction is providedinstructions
Object? When "providedBy" is "dojo" or "you-and-dojo", this is an object whose keys are numbers (from "outputsToRedeem") that correspond to Dojo-provided inputs
OutputTemplate
Type: Object
Properties
satoshis
Number The number of satoshis that will be put into this outputscript
String The hex string representing the output scriptprovidedBy
String Who is responsible for this output - Either "you" or "dojo"purpose
String? When the output is provided by Dojo, its purpose can either be "change" or "service-charge"destinationBasket
String? When the output is provided by Dojo, this indicates which basket it is destined for
TransactionTemplate
Type: Object
Properties
referenceNumber
String The reference number you will use to either process the transaction (withprocessTransaction
) or cancel it (withupdateTransactionStatus
).inputs
Object<InputTemplate> The set of input templates for this transaction. This is an object whose keys are TXIDs and whose values are InputTemplate objects.outputs
Array<OutputTemplate> The set of output templates to include in this transaction
TxInputEnvelope
Type: Object
Properties
rawTx
String The serialized hex of the transactioninputs
Object? As specified by SPV EnvelopemapiResponses
Array<Object>? As specified by SPV Envelopeproof
Object? As specified by SPV EnvelopeoutputsToRedeem
Array<TxRedeemableOutput> In addition to the fields for a normal envelope, this is used to indicate the outputs in the transaction that you are redeeming here.
createTransaction
Creates a new transaction that must be processed with processTransaction
after you sign it
Parameters
obj
Object All parameters are given in an object (optional, default{}
)obj.xprivKey
String The key of the userobj.config
Object? Config object, see config section (optional, defaultCONFIG
)obj.inputs
Object<TxInputEnvelope>? Specify any additional inputs to the transaction (if any) that are not to be provided by the Dojo. If you do not provide inputs here, or if they are insufficient, Dojo will select additional inputs for you to sign. To control this input selection behavior, see theinputSelection
parameter. Thisinputs
parameter is an object whose keys are TXIDs of input transactions, and whose values are their associated SPV envelopes.obj.inputSelection
Object? If Dojo needs to select more inputs beyond what you provided in theinputs
parameter, this parameter describes which kinds of inputs can be selected, and from where.obj.inputSelection.disable
Boolean? This is a boolean that, when true, will forbid Dojo from adding any additional inputs to your transaction, beyond what you specified in theinputs
parameter. Thus, if you have not sufficiently funded the transaction yourself, or ifinputs
is empty, you will get an error.obj.inputSelection.maxUnconfirmedChainLength
Number? An integer representing the maximum length for any chain of unconfirmed parents that a selected input can have. When -1 (the default), no maximum is specified. Cannot be zero. When 1, indicates that the input must itself be confirmed. When 2, input parents must be confirmed. 3 denotes grandparents, 4 great-grandparents and so forth.
obj.outputs
Array<TxOutput>? External outputs that you will include when you create this transaction. These outputs can contain custom scripts as specified by recipients. If the inputs to the transaction go beyond what is needed to fund these outputs (plus the transaction fee), additional Dojo-managed UTXOs will be generated to collect the remainder (see theoutputGeneration
parameter for more on this).obj.outputGeneration
Object? If Dojo needs to generate additional outputs for the transaction beyond what was specified, this object describes what kind of outputs to generate, and where they should be kept.obj.outputGeneration.method
String The method used to generate outputs. "auto" selects the amount and types of generated outputs based on the selected basket's configuration for how many of each type to keep on hand, then uses Benford's law to distribute the satoshis across them. "single" just uses one output, randomly selected from the available types, that contains all the satoshis. (optional, defaultauto
)
obj.fee
Object? Represents the fee the transaction will payobj.labels
Array<String>? The labels to affix to this transaction
Returns Promise<TransactionTemplate> The template you need to sign and process
processTransaction
After a transaction is created (with createTransaction
or with getTransactionWithOutputs
) this is used to process the transaction, thereby activating any change outputs and flagging designated inputs as spent
Parameters
obj
Object All parameters are given in an object (optional, default{}
)obj.xprivKey
String The key of the userobj.config
Object? Config object, see config section (optional, defaultCONFIG
)obj.submittedTransaction
String The transaction that has been created and signedobj.note
String? A numan-readable note describing the transactionobj.recipient
String? The Paymail handle for the recipient of the transactionobj.reference
String The reference number provided bycreateTransaction
orgetTransactionWithOutputs
Returns Promise<Object> An object containing a note
field with a success message, and mapiResponses
, for use in creating an SPV Envelope
processPendingTransactions
Signs and processes all pending transactions, useful when recovering from an error or crash, or on startup. If a transaction fails to process, marks it as failed.
Parameters
obj
Object All parameters are given in an object (optional, default{}
)
Returns Promise Resolves once the operation is complete
markMissingTxInputsAsSpent
This function has been deprecated, because blockchain scanning services it relied upon have been shut down.
TransactionOutputDescriptor
Type: Object
Properties
txid
String Transaction ID of transaction that created the outputvout
Number Index in the transaction of the outputamount
Number Number of satoshis in the outputoutputScript
String Hex representation of output locking scripttype
String The type of output, for example "P2PKH" or "P2RPH"spendable
Boolean Whether this output is free to be spent
getTransactionOutputs
Returns a set of transaction outputs that Dojo has tracked
Parameters
obj
Object All parameters are given in an object (optional, default{}
)obj.xprivKey
String The key of the userobj.config
Object? Config object, see config section (optional, defaultCONFIG
)obj.spendable
Boolean? If given as true or false, only outputs that have or have not (respectively) been spent will be returned. If not given, both spent and unspent outputs will be returned.obj.type
String? If provided, only outputs of the specified type will be returned. If not provided, outputs of all types will be returned.obj.limit
Number? Provide a limit on the number of outputs that will be returned. (optional, default25
)obj.offset
Number? Provide an offset into the list of outputs. (optional, default0
)
Returns Promise<Array<TransactionOutputDescriptor>> A set of outputs that match the criteria
updateTransactionStatus
Use this endpoint to update the status of a transaction. This is useful for flagging incomplete transactions as aborted or reverting a completed transaction back into a pending status if it never got confirmed. Setting the status to "completed" or "waitingForSenderToSend" will make any selected UTXOs unavailable for spending, while any other status value will free up the UTXOs for use in other transactions.
Parameters
obj
Object All parameters are given in an object (optional, default{}
)
Returns Promise<Object> A success object with status: "success"
updateOutpointStatus
Use this endpoint to update the status of one of your outputs, given as the TXID of a transaction and the vout (output index) in that transaction. This is useful for flagging transaction outpoints as spent if they were inadvertantly broadcasted or used without properly submitting them to the Dojo, or to undo the spending of an output if it was never actually spent.
Parameters
obj
Object All parameters are given in an object (optional, default{}
)obj.xprivKey
String The key of the userobj.config
Object? Config object, see config section (optional, defaultCONFIG
)obj.txid
String The TXID of the transaction that created the outputobj.vout
Number The index of the output in the transactionobj.spendable
Boolean The true spendability status of this outpoint
Returns Promise<Object> A success object with status: "success"
Handling Errors
When errors are returned from the Dojo API, they take the form of an object with three fields:
- status: Will be
error
if there is an error. - code: The machine-readable error code. Example:
ERR_BAD_THING
- description: The human-readable error message. Example:
A bad thing has happened.
The UTXONinja wrapper will raise JavaScript errors in the following format:
ERR_BAD_THING: A bad thing has happened.
You can parse these error messages into a usable format as follows:
try {
await ninja.someFunction()
} catch (e) {
console.error(`Error code: ${e.message.split(':')[0]}`)
console.error(`Error message: ${e.message.split(':')[1].trim()}`)
}
If you want custom error messages, or if you are building an internationalized (non-English) application, you can utilize the machine-readable error codes. A list of current codes can be found in the Table of Errors in the Dojo API Documentation.
License
The license for this library, which is a wrapper for the proprietary Dojo API, is the Open BSV License. It can only be used on the BSV blockchain. The Dojo API itself, including the rights to create and host Dojo servers or any other related infrastructure, is not covered by the Open BSV License and remains proprietary and restricted. The Open BSV License only extends to the code in this repository, and you are not permitted to host Dojo servers or create copies or alternative implementations of the proprietary Dojo API without other permission.