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.
If you need help, don't hesitate to send a message to Ty Everett on the Atlantis Slack.
Get Object Type Definitions
$0 Object (optional, default {})
$0.privateKey$0.config (optional, default CONFIG)$0.taalApiKeys (optional, default {test:'testnet_ba132cc4d5b2ebde7ed0ee0f6ee3f678',main:'mainnet_6c8f8c37afd5c45e09f62d083288a181'})obj Object All parameters are given in an object
Wraps the Authrite.request method to provide additional functionality
feature String The request destination routefetchConfig Object Any configuration including the request bodyReturns Object JSON object containing the result of the request
Returns the current Paymail handle
Returns Promise<String> The Paymail handle
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.
Returns Promise<Object> A success object with status: "success"
Returns the name and photo URL of the user
Returns Promise<Avatar> The avatar of the user
Sets a new name and photo URL
obj Object All parameters are given in an object
Returns Promise<Object> A success object with status: "success"
Returns a set of transactions that match the criteria
obj Object All parameters are given in an object (optional, default {})
obj.limit Number Include only this maximum number of transactions in the set (optional, default 25)obj.offset Number Include transactions offset by this number in the full set (optional, default 0)obj.involving String? Only include transactions sent to or received from this Paymail handleobj.orderBy String Sort order, can be newest-first or oldest-first (optional, default newest-first)obj.label String? Only include transactions affixed with this labelobj.status String? If provided, only transactions with the given status will be returnedobj.referenceNumberReturns Promise<GetTransactionsResult> The transactions and the total size of the set
Returns a set of all transactions that need to be signed and submitted, or canceled
$0 Object (optional, default {})
$0.referenceNumberReturns Promise<Array<GetPendingTransactionsTx>> The array of pending transactions
Returns the total of the amounts of transactions that fall under certain criteria
obj Object All parameters are given in an object (optional, default {})
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 secondsReturns Promise<Object> An object containing total, a number of satoshis
Returns the total of unspent outputs
Returns Promise<Object> An object containing total, a non-negative number of satoshis
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.
obj Object All parameters are given in an object (optional, default {})
obj.outputs Array<GetTxWithOutputsOutput> A set of outputs to include, each with script and satoshis. (optional, default [])obj.feePerKb Number The number of satoshis to pay per KB of block space used by this transaction. (optional, default 110)obj.labels Array<String> A set of label strings to affix to the transaction (optional, default [])obj.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 called outputsToRedeem. This is an array of objects, each containing index and unlockingScript properties. The index property is the output number in the transaction you are spending, and unlockingScript is the hex scriptcode that unlocks the satoshis. Note that you should create any signatures with SIGHASH_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 return mapiResponses and note instead of referenceNumber (optional, default true)obj.note String? A note about the transactionobj.recipient String? Paymail recipient for transactionobj.authriteClient Authrite An API for invoking mutually authenticated requestsReturns Promise<GetTxWithOutputsResult> The serialized transaction, inputs, reference number and amount
Creates a new transaction that must be processed with processTransaction
after you sign it
obj Object All parameters are given in an object
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 the
inputSelection parameter. This inputs 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 the inputs 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 the inputs
parameter. Thus, if you have not sufficiently funded the
transaction yourself, or if inputs 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 the outputGeneration 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, default auto)obj.fee Object? Represents the fee the transaction will pay
obj.labels Array<String>? The labels to affix to this transaction
obj.note String? A numan-readable note describing the transaction
obj.recipient String? The Paymail handle for the recipient of the transaction
Returns Promise<TransactionTemplate> The template you need to sign and process
Returns which BSV network we are using (mainnet or testnet)
format String for the returned string. Either with or without a 'net' suffix. (optional, default 'default')Returns String The current BSV network formatted as requested.
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
obj Object All parameters are given in an object
obj.inputs String Inputs to spend as part of this transactionobj.submittedTransaction String The transaction that has been created and signedobj.reference String The reference number provided by createTransaction or getTransactionWithOutputsobj.outputMap Object An object whose keys are derivation prefixes and whose values are corresponding change output numbers from the transaction.Returns Promise<Object> An object containing a note field with a success message, and mapiResponses, for use in creating an SPV Envelope
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.
obj Object All parameters are given in an object (optional, default {})
Returns Promise Resolves once the operation is complete
Returns a set of transaction outputs that Dojo has tracked
obj Object All parameters are given in an object (optional, default {})
obj.basket String? If provided, indicates which basket the outputs should be selected from.obj.tracked Boolean? If provided, only outputs with the corresponding tracked value will be returned (true/false).obj.includeEnvelope Boolean? If provided, returns a structure with the SPV envelopes for the UTXOS that have not been spent. (optional, default false)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, default 25)obj.offset Number? Provide an offset into the list of outputs. (optional, default 0)Returns Promise<Array<TransactionOutputDescriptor>> A set of outputs that match the criteria
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.
obj Object All parameters are given in an object
Returns Promise<Object> A success object with status: "success"
This endpoint allows a recipient to submit a transactions that was directly given to them by a sender. Saves the inputs and key derivation information, allowing the UTXOs to be redeemed in the future. Sets the transaction to completed and marks the outputs as spendable.
obj Object All parameters are given in an object
obj.protocol string Specify the transaction submission payment protocol to use. Currently, the only supported protocol is that with BRFC ID "3241645161d8"
obj.transaction Object The transaction envelope to submit, including key derivation information
obj.transaction.outputs Array An array of outputs, each containing vout, satoshis, derivationSuffix, and (optionally), derivationPrefix. If a global derivationPrefix is used (recommended), output-specific derivation prefixes should be omitted.obj.senderIdentityKey string Provide the identity key for the person who sent the transaction
obj.note string Human-readable description for the transaction
obj.derivationPrefix string? A derivation prefix used for all outputs. If provided, derivation prefixes on all outputs are optional.
obj.amount
obj.labels
Returns Promise<Object> Object containing reference number, status=success, and human-readable note acknowledging the transaction
Verifies an incoming Paymail transaction (deprecated, use submitDirectTransaction)
obj Object
Returns Promise<Boolean> A success boolean status
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.
obj Object All parameters are given in an object
Returns Promise<Object> A success object with status: "success"
Use this endpoint to store an incoming certificate.
obj Object All parameters are given in an object
obj.certificate Object The certificate object to saveReturns Promise<Object> A success object with status: "success"
Use this endpoint to retrieve certificates.
obj Object All parameters are given in an object
Returns Promise<Object> A success object with status: "success" and any found certificates
Type: Object
script String The hex representing the locking script of the outputsatoshis Number The number of satoshis to put in the outputType: Object
rawTx String The serialized, signed transaction that is ready for broadcasttxid String The txid for the new transactionreferenceNumber String The reference number that should now be provided back to processTransaction (or updateTransactionStatus`)inputs Object This is the fully-formed inputs field of this transaction, as per the SPV Envelope specification.amount Number The amount of the transactionWhen errors are returned from the Dojo API, they take the form of an object with three fields:
error if there is an error.ERR_BAD_THINGA 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.
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.
FAQs
Bitcoin and Paymail Management Done Right
The npm package utxoninja receives a total of 13 weekly downloads. As such, utxoninja popularity was classified as not popular.
We found that utxoninja demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.