dojo.babbage.systems
Open in
urlscan Pro
2a00:1450:4001:82f::2013
Public Scan
Submitted URL: https://www.gateway.cash/
Effective URL: https://dojo.babbage.systems/
Submission: On June 16 via automatic, source certstream-suspicious — Scanned from DE
Effective URL: https://dojo.babbage.systems/
Submission: On June 16 via automatic, source certstream-suspicious — Scanned from DE
Form analysis
0 forms found in the DOMText Content
THE BITCOIN DOJO * Now offering full SPV support! * Benford’s Law and On-chain Privacy Out-of-the-box * Flexibility to create any Bitcoin transactions of your choice * Authrite identity certificates for KYC compliance * Ninja keeps keys client-side, while Dojo tracks UTXOs online Welcome to the UTXO Dojo! You can use this API to do just about anything you can imagine with Bitcoin, and there are also libraries available that make it easier to use (more on that momentarily). Register new MetaNet Identities and manage Bitcoins easily with nothing other than a private key. Plug it into your existing application, and never worry about change outputs or address re-use again. Read through these docs, and if you still have questions, we're happy to answer them on our website. Just ask for a call and we'll help you out. Happy hacking, and if you built something cool, we'd love to hear about it :) INITIAL SETUP You can use the UTXO Ninja to easily interact with the server, and if you're using JavaScript, this is probably your best bet. Just plug in the Dojo URL, generate a private key, and you're off to the races! CURRENT SERVER'S DOJO URL AND CONFIG Beep boop, my Dojo URL is: https://dojo.babbage.systems A quick note: I no longer think Paymail is cool, so I won't be working as a Paymail host anymore. It's still possible to do everything without Paymail though. My friend Roger wrote a great article about this, which you should read if you're interested. MUTUAL AUTHENTICATION So I know who you are, and so you know who I am, let's agree to use Authrite when we talk to each other. It's a secure communications channel, and it even supports identity certificates so everyone knows they're speaking with the right person. If you'd like to see an example of using Authrite with this API, you should check out the code for the UTXO Ninja client. MONEY BASKETS When you receive an incoming payment, the payment is routed to one of your Money Baskets. A Money Basket is a group of Bitcoin UTXOs (unspent transaction outputs) that share a common set of characteristics. You can think of a Money Basket like a bank account or a savings jar for a particular purpose. You can configure which senders, apps or token types get sent to whicch baskets. Money from one basket won't be mixed with money from any other basket. When you make your account, you'll get a single "default" basket, and it will be automatically hooked up for all your incoming payments. Baskets have a few settings that let you customize their behavior to your liking: BASKET SETTINGS * Minimum Desired Value: This lets you change the smallest UTXO amounts you'd like to see in your basket. * Number of Desired UTXOs: This lets you change how many UTXOs you'd like to try and keep on-hand in this basket at any one time. In the future, our API will let you create more baskets than just the default, and hook up different Money Baskets to different purposes. You should be aware that the policies surrounding the minimum desired value of UTXOs in a given Money Basket will take precedence over the policies surrounding the number of UTXOs to be kept on hand. If this bugs you, please yell at us, and maybe we'll change it. GETTING STARTED Generally, the first request you will want to make after you generate a key is to use "submitDirectTransaction" to fund your account with some incoming Bitcoin inputs from somewhere. Once you've got some coins under your new key, you can use "createTransaction" and "processTransaction" to build any transactions you'd like. Just generate a fresh private key, then sign and send your first request! Your account will be created automagically. THE DOJO API DOCS POST /CREATETRANSACTION This endpoint creates a new transaction, supplying you with additional inputs to fund it and/or providing change outputs as necessary. You can specify inputs and outputs, provide a fee model to use, and pick which types of Dojo-managed UTXOs you want to spend (if any). After you create and sign the transaction, you MUST immediately use "processTransaction" to activate any new outputs, or "updateTransactionStatus" to cancel it and free up any selected inputs. Note that any selected inputs will not be usable in any other transactions, unless you cancel this transaction without sending it. This is to prevent accidental double-spending of inputs where a second transaction would have selected overlapping inputs as the earlier one before the earlier one has a chance to be processed. PARAMETERS * auth: The authentication object (see the authentication section) * inputs: An optional object whose keys are TXIDs and whose values are payment envelopes for external inputs to use when funding this transaction. If more funding is needed beyond what is given here to pay for the specified outputs (plus the transaction fee), Dojo will select them from your baskets of unspent outputs (see the "inputSelection" parameter for more on this). * inputs[TXID]: Must be a payment envelope containing the transaction with output(s) that will be spent and used as input. * inputs[TXID].outputsToRedeem: In addition to the normal envelope fields, it must also include an additional field, "outputsToRedeem", which is an array of output numbers to be selected from that transaction and spent. The array is an array of objects where each object contains index, spendingDescription and unlockingScriptLength. * inputSelection: If Dojo needs to select more inputs beyond the ones specified in order to fund the transaction, this object describes which kinds of inputs can be selected, and from where. * inputSelection.baskets: TODO (coming soon). This is an array of UTXO basket names from which UTXOs can be selected for spending. To only select UTXOs of a certain type, configure the source basket only to accept those types of UTXOs. By default, UTXOs will only be selected if they are in the "default" basket. * inputSelection.maxUnconfirmedChainLength: 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. * inputSelection.disable: 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 the "inputs" array is empty, you will get an error. * outputs: An optional array of objects for 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). * outputs[element].script: The output script that will be included * outputs[element].satoshis: The amount of the output in satoshis * outputs[element].description: Human-readable output line-item description * outputs[element].basket: Destination output basket for the new UTXO * outputs[element].customInstructions: Custom spending instructions (metadata, string, optional) * outputGeneration: 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. * outputGeneration.basket: TODO (coming soon). Specify the basket where the generated outputs will be kept. Only output types compatible with the destination basket will be generated. * outputGeneration.method: The method used to generate outputs. "auto" (the default) 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. * fee: An object representing the fee the transaction will pay. * fee.model: The fee model to use, default "sat/kb" * fee.value: When "fee.model" is "sat/kb", this is an integer representing the number of satoshis per kb of block space the transaction will pay in fees. The default is 600. * labels: An array of transaction label strings, each at most 150 characters. Labels can be used to tag transactions into categories * note: A human-readable note detailing this transaction (Optional) * recipient: The Paymail handle of the recipient of this transaction (Optional) EXAMPLE RESPONSE { "referenceNumber": "xxx", "inputs": { "txid1...": { "providedBy": "you", "outputsToRedeem": [ 1 ], "rawTx": "01000000...", "...": "other envelope fields (proof or inputs/mapiResponses)" }, "txid2...": { "providedBy": "you", "outputsToRedeem": [ 2, 4 ], "rawTx": "01000000...", "...": "other envelope fields (proof or inputs/mapiResponses)" }, "txid3...": { "providedBy": "dojo", "outputsToRedeem": [ 3, 6 ], "instructions": { "3": { "type": "P2PKH", "paymailHandle": "you@yourdomain.com", "derivationPrefix": "asdfasdfj-asdfsf", "derivationSuffix": "asd-asdfsfdjdfoa" }, "6": { "type": "P2PKH", "paymailHandle": "you@yourdomain.com", "derivationPrefix": "asdfasdfj-asdfsf", "derivationSuffix": "asd-asdfsfdjdfoa" } }, "rawTx": "01000000...", "...": "other envelope fields (proof or inputs/mapiResponses)" }, "txid4...": { "providedBy": "you-and-dojo", "outputsToRedeem": [ 0, 1 ], "instructions": { "1": { "type": "P2RPH", "paymailHandle": "you@yourdomain.com", "derivationPrefix": "asdfasdfj-asdfsf", "derivationSuffix": "asd-asdfsfdjdfoa" } }, "rawTx": "01000000...", "...": "other envelope fields (proof or inputs/mapiResponses)" } }, "outputs": [ { "providedBy": "you", "script": "...442266889955", "satoshis": 1337 }, { "providedBy": "you", "script": "...888844446666", "satoshis": 1033 }, { "providedBy": "dojo", "purpose": "change", "destinationBasket": "loose-poket-change", "derivationSuffix": "asfsjosd-asffsjsa", "satoshis": 4488 }, { "providedBy": "dojo", "purpose": "service-charge", "script": "...a8cca8cc8caa", "satoshis": 10 } ] } POST /PROCESSTRANSACTION After creating a transaction with createTransaction and signing it, submit the reference number and the payment envelope containing the transaction to this endpoint, thereby marking the change outputs as spendable and confirming that the selected inputs have been spent. PARAMETERS * hex: The transaction serialized as a hex string * reference: The reference number that you received from createTransaction * outputMap: An object whose keys are change output derivation suffixes and whose values are the corresponding output (vout) numbers within the transaction. EXAMPLE RESPONSE { "note": "The transaction has been processed and broadcast.", "mapiResponses": [ { "payload": "{\"apiVersion\":\"1.3.0\",\"timestamp\":\"2021-07-22T06:10:16.8249798Z\",\"txid\":\"72fb10d4189f51d404e7098cfa63bda24ca403221f610b096bb15f5ed2f3f07a\",\"returnResult\":\"success\",\"resultDescription\":\"\",\"minerId\":\"030d1fe5c1b560efe196ba40540ce9017c20daa9504c4c4cec6184fc702d9f274e\",\"currentHighestBlockHash\":\"000000000000000009633c9e88483812c4a39a41e1eb95cdb18cce213196d202\",\"currentHighestBlockHeight\":696983,\"txSecondMempoolExpiry\":0}", "signature": "304402205bd36673a85c4843df0c3f34cc65a8de446bed884a98a91df8a6d1b7f828b8d7022076c954e93b21b30945d7382c54f26a238db216e5ad438601fabe69e2bc5bf701", "publicKey": "030d1fe5c1b560efe196ba40540ce9017c20daa9504c4c4cec6184fc702d9f274e", "encoding": "UTF-8", "mimetype": "application/json" } ] } POST /GETTRANSACTIONS Use this endpoint to obtain a list of transactions associated with your xpub key. PARAMETERS * limit: The maximum number of transactions to return at one time. (Optional). * offset: The offset into the list of transactions from which results will be returned. (Optional). * involving: If provided, only transactions involving the specified Paymail handle will be returned. (Optional). * orderBy: If provided, specifies the sort order of the list. Valid options are "newest-first" and "oldest-first". By default, the order is "oldest-first". (Optional). * label: If provided, must be a label string. Only transactions that have the specified label string will be returned. * status: If provided, only transactions that have the specified status will be returned. * referenceNumber: If provided, only the transaction with a matching reference number will be returned. EXAMPLE RESPONSE { "totalTransactions": 2, "transactions": [ { "txid": "txid1", "status": "completed", "amount": 314159, "senderPaymail": "foo@bar.com", "recipientPaymail": "me@example.com", "note": "Here is money.", "isOutgoing": true, "created_at": "2020-11-28T18:25:26.104Z", "referenceNumber": "ref_no", "labels": [ "Label #1", "Label #2" ] }, { "txid": "txid2", "status": "completed", "amount": 123456, "senderPaymail": "foo@bar.com", "recipientPaymail": "ben@dover.com", "note": "Here is more money.", "isOutgoing": true, "created_at": "2020-12-28T14:15:16.458Z", "referenceNumber": "ref_no", "labels": [ "Label #1", "Label #3", "Label #4" ] } ] } POST /GETPENDINGTRANSACTIONS Use this endpoint to get a list of the transactions that need to be either signed and submitted, or canceled. PARAMETERS * referenceNumber: xyz EXAMPLE RESPONSE [ { "amount": 314159, "senderPaymail": "foo@bar.com", "created_at": "2020-11-28T18:25:26.104Z", "referenceNumber": "ref_no" }, { "amount": 123456, "senderPaymail": "foo@bar.com", "created_at": "2020-12-28T14:15:16.458Z", "referenceNumber": "ref_no" } ] POST /GETTOTALOFUNSPENTOUTPUTS Use this endpoint to obtain the total value of the unspent transaction outputs. Currently, the total value is always returned, but in the future, if we decide to implement output baskets, transaction labels and other sorting schemes, it will be possible to provide more specificity. PARAMETERS * basket: Specify a basket. If not provided, the default basket is assumed. EXAMPLE RESPONSE { "total": 45568 } POST /SETNAMEANDPHOTOURL Use this endpoint to set a name and profile photo URL that will be resolved when people request an avatar for the Paymail handle. PARAMETERS * auth: The authentication object (see the authentication section) * name: The name that you would like to use * photoURL: The UHRP or HTTPS URL to a photo that you would like to use as your avatar * paymail: The Paymail handle you want to associate with the name and photo URL EXAMPLE RESPONSE { "status": "success" } POST /GETTRANSACTIONOUTPUTS Use this endpoint to obtain a list of transaction outputs managed by this server. PARAMETERS * basket: If provided, indicates which basket the outputs should be selected from. * tracked: If provided, only outputs with the corresponding tracked value will be returned (true/false). * includeEnvelope: If provided, returns a structure with the SPV envelopes for the UTXOS that have not been spent. * spendable: 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. (Optional). * type: If provided, only outputs of the specified type will be returned. If not provided, outputs of all types will be returned. (Optional). * limit: Provide a limit on the number of outputs that will be returned. (Optional). * offset: Provide an offset into the output list from which to begin returning outputs. (Optional). EXAMPLE RESPONSE [ { "txid": "123...", "vout": 5, "amount": 314159, "outputScript": "76...", "type": "P2PKH", "spendable": true } ] POST /GETTOTALOFAMOUNTS Use this endpoint to find the aggregate total of the amounts of all transactions of a given direction, in a given date range, or with a specific label. PARAMETERS * auth: The authentication object (see the authentication section) * direction: Specify the direction of transactions to total ("incoming" or "outgoing"). Required. * startDate: An epoch timestamp in seconds indicating that only the amounts of transactions created after this date should be totaled. Optional. * endDate: An epoch timestamp in seconds indicating that only the amounts of transactions created before this date should be totaled. Optional. * involving: If provided, only the amounts of transactions involving the specified Paymail handle will be totaled. Note that this still only returns amounts in a single direction. Optional. * label: If provided, must be a label string. Only the amounts of transactions that have the specified label string will be totaled. Optional. EXAMPLE RESPONSE { "total": 198254 } POST /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 "waitingForSenderToSend" or "completed" will make any selected UTXOs non-spendable elsewhere, while any other status value will free up the UTXOs for use in other transactions. PARAMETERS * auth: The authentication object (see the authentication section) * reference: The reference number associated with the transaction * status: The new desired status for the transaction EXAMPLE RESPONSE { "status": "success" } POST /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 * txid: The txid of the transaction that created (not spent!) the output which you would like to update * vout: The index of the output in the transaction * spendable: A boolean indicating the corrected outpoint spendability status. If true, this output can once again be selected spent in subsequent transactions. If false, the output will be treated as if it has already been spent and will not be used or selected again. EXAMPLE RESPONSE { "status": "success" } POST /LABELTRANSACTION Use this endpoint to add a label to an existing transaction. PARAMETERS * auth: The authentication object (see the authentication section) * txid: The txid of the transaction you want to label * label: The label to add to the transaction EXAMPLE RESPONSE { "status": "success" } POST /UNLABELTRANSACTION Use this endpoint to remove a label to a transaction. PARAMETERS * auth: The authentication object (see the authentication section) * txid: The txid of the transaction you want to unlabel * label: The label to remove from the transaction EXAMPLE RESPONSE { "status": "success" } POST /SUBMITDIRECTTRANSACTION 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. PARAMETERS * protocol: Specify the transaction submission payment protocol to use. Currently, the only supported protocol is that with BRFC ID "3241645161d8" * transaction: The transaction envelope to submit, including key derivation information * senderIdentityKey: Provide the identity key for the person who sent the transaction * note: Human-readable description for the transaction * labels: An array of transaction label strings, each at most 150 characters. Labels can be used to tag transactions into categories EXAMPLE RESPONSE { "reference": "asdf-asdffss0...", "status": "success", "note": "The transaction has been received." } POST /SAVECERTIFICATE Use this endpoint to receive an incoming certificate. PARAMETERS * certificate: The certificate object to save EXAMPLE RESPONSE { "status": "success" } POST /FINDCERTIFICATES find certificates PARAMETERS * certifiers: The certifiers to filter certificates by * types: The certificate types to filter certificates by EXAMPLE RESPONSE { "status": "success", "certificates": [ { "Authrite": "certificate" } ] } POST /VERIFYENVELOPE Use this endpoint to verify an SPV envelope against the chain of headers tracked by the Dojo. Only use this endpoint if you trust the server operator. PARAMETERS * rawTx: The field from the Envelope specification * inputs: The field from the Envelope specification * mapiResponses: The field from the Envelope specification * proof: The field from the Envelope specification EXAMPLE RESPONSE { "valid": true } GET /STATS Returns some statistics for the current Dojo instance. PARAMETERS EXAMPLE RESPONSE { "users": 22, "transactions": 552, "transactionLabels": 72, "network": "mainnet" } API ERRORS Errors are sent back with appropriate HTTP status codes. The status field of the response object will be "error" in these cases. The object will also contain a machine-readable code field and a human-readable description field. See the Table of Errors for a complete list of error codes. TABLE OF ERRORS * ERR_PAYMAIL_NOT_FOUND * ERR_PAYMAIL_NOT_FORMATTED_CORRECTLY * ERR_INTERNAL * ERR_UNAUTHORIZED * ERR_INVALID_REFERENCE * ERR_INVALID_TRANSACTION_STATUS * ERR_REQUEST_EXPIRED * ERR_PAYMAIL_MISMATCH * ERR_TRANSACTION_REJECTED * ERR_SENDER_SIGNATURE_CHECK * ERR_PAYMAIL_UNAVAILABLE * ERR_INVALID_PAYMAIL_DOMAIN * ERR_NOT_SUFFICIENT_FUNDS * ERR_BAD_REQUEST * ERR_INVALID_OUTPOINT * ERR_MISSING_PARAMETER * ERR_TRANSACTION_NOT_FOUND * ERR_LABEL_NOT_FOUND * ERR_CHAIN_INVALID NOTES ON ERR_NOT_SUFFICIENT_FUNDS When you use the createTransaction endpoint to attempt to request inputs and change outputs to a transaction that would require more funds than are available in the current context (you are trying to spend more Bitcoins than you have on hand), the server will generate ERR_NOT_SUFFICIENT_FUNDS. In addition to the error code and a human-readable description field, the error object will also contain totalSatoshisNeeded and moreSatoshisNeeded fields. These values are calculated based on the cost of only the required outputs and whatever inputs were available to be selected. They do not necessarily reflect the actual amount of satoshis you need to have on hand, because we do not account for the cost of miner fees associated with redeeming and spending the new output(s) in the transaction. Depending on the application, it can be better to over-shoot these estimates by a little and have change outputs. Factor in your current receive policy, fee rates, the types of outputs used and others if you need to be precise. TIPS AND TRICKS As you build, you may find the tips and tricks from this section useful when architecting the best applications and services. DEALING WITH "PHANTOM UTXOS" Sometimes, Dojo-managed UTXOs get inadvertently spent without properly going through the transaction creation or processing steps. There are two ways to deal with this type of situation, depending on the circumstances. 1. JUST USE PROCESSTRANSACTION: WORKS WHEN CREATETRANSACTION WAS USED If, for example, you created a transaction with createTransaction, sent it to a merchant who broadcasted it and accepted it as payment, but before you could use processTransaction to mark your UTXOs as spent and activate your change outputs, your internet connection dropped, then the Dojo does not know that the transaction was ever broadcast. It may try to spend the same UTXOs again (though this is unlikely in recent versions), causing for future transactions to be rejected with missing inputs. To resolve this, when you come back online (or when you otherwise learn of the error), you could find the reference number for the missing transaction with getTransactions, then use a service provider to obtain the payment envelope and subsequently process it as normal. The next section describes a more universal (though somewhat less convenient) method, useful in more extreme cases. 2. MANUALLY MARK UTXOS AS SPENT: WORKS NO MATTER WHAT If, for example, you loaded your Dojo XPRIV key into other software and sent transactions using the traditional non-P2P way (do not do this!), the transactions were not created in accordance with Dojo's instructions, and createTransaction was never even used. Dojo does not know about them, because Dojo never scans the blockchain for transactions. You don't have a reference number, so you can't just process them with processTransaction. You can recover from this by using the updateOutpointStatus endpoint, manually flagging the afflicted UTXOs as spent. That way, Dojo won't try to spend them again. If you are in a situation where you now have rogue change outputs created by other software, if you want to bring them back under Dojo management here is how: Just use createTransaction while specifying all of the rogue change UTXOs as inputs. Specify no outputs, thereby sending all of the inputs back under Dojo management. Sign the transaction and process it as normal with processTransaction and your reference number to get your UTXOs back into the system. WARNINGS & CAUTIONS Dojo never holds your private keys, but there are still risks if you use it carelessly. Always be mindful of what you are signing! BE CAREFUL WITH P2RPH! Be extremely careful with P2RPH transactions. Only use the K-chain value once for the signature. Never sign different messages with the same K-chain value and private key, otherwise the K-value and private key could be calculated. P2RPH is disabled by default, you enable and use it at your own risk. HOW I MAKE MONEY Every once in a while, a "service charge" output will be added when you use "createTransaction". These will be really small, and this is disabled for now. For now, everything's free so as many people as possible can get started.