Datacash is the simplest library for building and broadcasting Bitcoin Cash OP_RETURN transactions.
Post to the blockchain with just 4 lines of code.
Post to both Memo.cash and Blockpress with a single interface.
npm install datacash
and then require it
const datacash = require('datacash')
<script src='https://unpkg.com/datacash'></script>
Send "Hello from datacash"
to memo.cash in 5 lines of code.
const privateKey = [YOUR PRIVATE KEY HERE];
datacash.send({
data: ["0x6d02", "Hello from datacash"],
cash: { key: privateKey }
});
Above code builds an OP_RETURN
transaction with 0x6d02 hello
as push data, and broadcasts it to Bitcoin Cash network.
Datacash lets you build a transaction in a declarative manner. Here's an example:
var config = {
data: ["0x6d02", "hello from datacash"],
cash: {
key: "5JZ4RXH4MoXpaUQMcJHo8DxhZtkf5U5VnYd9zZH8BRKZuAbxZEw",
rpc: "https://cashexplorer.bitcoin.com",
fee: 250,
to: [{
address: "1A2JN4JAUoKCQ5kA4pHhu4qCqma8jZSU81",
value: 1000
}]
}
}
Above config describes a transaction that:
"hello from datacash"
to memo.cash network (See the protocol at https://memo.cash/protocol),250
satoshis,5JZ4RXH4MoXpaUQMcJHo8DxhZtkf5U5VnYd9zZH8BRKZuAbxZEw
,1A2JN4JAUoKCQ5kA4pHhu4qCqma8jZSU81
a value of 1000
satoshis.All you need to do to invoke it is call:
datacash.send(config)
Want to instead build a transaction but save it for later or export it? Just call:
datacash.build(config, function(error, tx) {
console.log("Here's the transaction! : ", tx)
})
And that's it! No complex APIs, but you can construct pretty much all kinds of OP_RETURN transactions.
datacash
is powered by bitcore-lib-cash, which in turn is a fork of bitcore-lib, which means all the low level transactions are completely robust and secure.
datacash
was created in order to make it dead simple to construct OP_RETURN
related transactions, but you can even use it to build regular transactions.
Also datacash
exposes datacash.bch
endpoint which you can use to access the underlying bitcore-lib-cash
library. If you need more sophisticated features (in most cases you won't), feel free to use this feature. Best of both worlds!
Datacash is designed with a different philosophy than conventional Bitcoin transaction libraries.
While traditional Bitcoin libraries focus on sending money, datacash is focused on sending data.
The API is optimized to make this as simple as possible. Datacash library has only two methods:
build
: For building a transaction (but not sending)send
: For sending a transaction"build" builds a transaction but doesn't broadcast it to the network.
The build()
method takes two arguments:
The first argument--a declarative JSON object--can contain the following attributes:
data
: For constructing OP_RETURN
datacash
: For describing everything related to actually sending moneytx
: For importing previously "built" transactionsThe data
attribute is used to construct human readable/processable data to post to the blockchain.
const tx = {
data: ["0x6d02", "hello world"]
}
datacash.build(tx, function(err, tx) {
/**
* res contains the generated transaction object, powered by bitcore-lib-cash
* You can check it out at https://github.com/bitpay/bitcore-lib-cash/blob/master/lib/transaction/transaction.js
* Some available methods you can call on the tx object are:
* 1. tx.toString() => Export as string
* 2. tx.toObject() => Inspect the transaction as JSON object
**/
});
NOTE: Each item in the data
array can either be:
To use hex string, simply prefix the string with "0x".
In above example, we can see that the first item is "0x6d02"
. Datacash will automatically recognize this as a hex string and interpret as a hex string (while discarding the 0x prefix before the interpretation)
This is useful if you want to export a transaction and later recover it.
const tx = {
data: "6a04366430320b68656c6c6f20776f726c64"
}
datacash.build(tx, function(err, tx) {
/**
* res contains the generated transaction object, powered by bitcore-lib-cash
* You can check it out at https://github.com/bitpay/bitcore-lib-cash/blob/master/lib/transaction/transaction.js
* Some available methods you can call on the tx object are:
* 1. tx.toString() => Export as string
* 2. tx.toObject() => Inspect the transaction as JSON object
**/
});
The cash
attribute deals with everything related to actually sending money.
key
: Signing with private keyrpc
: Specifying a JSON-RPC endpoint to broadcast throughfee
: Specifying transaction feeto
: Attaching tips on top of OP_RETURN messages (Normally OP_RETURN transactions don't have a receiver)When a cash
attribute is present, the build()
call generates a transaction
instead of a script
.
key
The key
attribute is mandatory. You must specify a private key in order to sign a transaction.
const tx = {
data: ["0x6d02", "hello world"],
cash: { key: "5JZ4RXH4MoXpaUQMcJHo8DxhZtkf5U5VnYd9zZH8BRKZuAbxZEw" }
}
datacash.build(tx, function(err, tx) {
/**
* res contains the generated transaction object
* (a signed transaction, since 'key' is included)
**/
})
rpc
The rpc
attribute is used to manually set the JSON-RPC endpoint you wish to broadcast through.
https://cashexplorer.bitcoin.com
const tx = {
data: ["0x6d02", "hello world"],
cash: {
key: "5JZ4RXH4MoXpaUQMcJHo8DxhZtkf5U5VnYd9zZH8BRKZuAbxZEw",
rpc: "https://cashexplorer.bitcoin.com"
}
};
datacash.build(tx, function(err, res) {
/**
* res contains the generated transaction object
* (a signed transaction, since 'key' is included)
**/
})
fee
The fee
attribute is used to specify the transaction fee in satoshis.
300
const tx = {
data: ["0x6d02", "hello world"],
cash: {
key: "5JZ4RXH4MoXpaUQMcJHo8DxhZtkf5U5VnYd9zZH8BRKZuAbxZEw",
rpc: "https://cashexplorer.bitcoin.com",
fee: 250
}
}
datacash.build(tx, function(err, res) {
/**
* res contains the generated transaction object
* (a signed transaction, since 'key' is included)
**/
})
to
The to
attribute is an array of receivers to send the OP_RETURN to. Normally this is left empty because most OP_RETURN
transactions are meant to have no receivers. But you can also send it to multiple users. For example you can use this feature to send tips to one or more people.
null
to
array can have 2 attributes:
const tx = {
data: ["0x6d02", "hello world"],
cash: {
key: "5JZ4RXH4MoXpaUQMcJHo8DxhZtkf5U5VnYd9zZH8BRKZuAbxZEw",
to: [{
address: "1A2JN4JAUoKCQ5kA4pHhu4qCqma8jZSU81",
value: 500
}, {
address: "1A2JN4JAUoKCQ5kA4pHhu4qCqma8jZSU81",
value: 500
}]
}
};
datacash.build(tx, function(err, res) {
/**
* res contains the generated transaction object
* (a signed transaction, since 'key' is included.
* Also, the transaction includes actual coin transfer outputs,
* since the "to" attribute is included)
**/
})
You may want to import a previously exported transaction. This is when you use the tx
attribute.
datacash.build({
tx: "01000000014182e9844c2979d973d3e82c55d57e1a971ed2e5473557ce0414864612911aa5010000006b48304502210098f8f32cd532bc73eef1e01c3d359caf0a7aa8f3dc1eebb8011d80810c9dbe66022054c6b23d5bd9573a1e6135c39dcc31a65cab91f3b3db781995e824614e24bad9412102d024c1861ccc655ce3395bc4d8a0bdcfb929ffcd9d1a8c81d8c6fa1dfb9bd70cffffffff020000000000000000106a026d020b68656c6c6f20776f726c64c2ff0000000000001976a9142a3a6886d98776d0197611e5328ba8806c3739db88ac00000000"
}, function(err, tx) {
// 'tx' is a transaction object
})
You can export an unsigned transaction, and later import and sign it to create a signed transaction, simply by supporting a cash.key
attribute.
// import an unsigned transaction and sign it
datacash.build({
tx: "01000000014182e9844c2979d973d3e82c55d57e1a971ed2e5473557ce0414864612911aa5010000006b48304502210098f8f32cd532bc73eef1e01c3d359caf0a7aa8f3dc1eebb8011d80810c9dbe66022054c6b23d5bd9573a1e6135c39dcc31a65cab91f3b3db781995e824614e24bad9412102d024c1861ccc655ce3395bc4d8a0bdcfb929ffcd9d1a8c81d8c6fa1dfb9bd70cffffffff020000000000000000106a026d020b68656c6c6f20776f726c64c2ff0000000000001976a9142a3a6886d98776d0197611e5328ba8806c3739db88ac00000000",
cash: {
key: "5JZ4RXH4MoXpaUQMcJHo8DxhZtkf5U5VnYd9zZH8BRKZuAbxZEw"
}
}, function(err, tx) {
// 'tx' is a signed transaction object
})
Notice how in addition to the tx
attribute we've added the cash.key
attribute. This will import the unsigned transaction and sign it.
If you already have a signed transaction object, you can simply send it away without any additional steps.
datacash.send({
tx: "01000000014182e9844c2979d973d3e82c55d57e1a971ed2e5473557ce0414864612911aa5010000006b48304502210098f8f32cd532bc73eef1e01c3d359caf0a7aa8f3dc1eebb8011d80810c9dbe66022054c6b23d5bd9573a1e6135c39dcc31a65cab91f3b3db781995e824614e24bad9412102d024c1861ccc655ce3395bc4d8a0bdcfb929ffcd9d1a8c81d8c6fa1dfb9bd70cffffffff020000000000000000106a026d020b68656c6c6f20776f726c64c2ff0000000000001976a9142a3a6886d98776d0197611e5328ba8806c3739db88ac00000000"
}, function(err, hash) {
// 'hash' is the transaction hash
})
Instead of just building, you can build AND send. Same syntax as build()
.
The only difference is the callback function.
const tx = {
data: ["0x6d02", "hello world"])
cash: { key: "5JZ4RXH4MoXpaUQMcJHo8DxhZtkf5U5VnYd9zZH8BRKZuAbxZEw" }
}
datacash.send(tx, function(err, res) {
console.log(res)
})
// Build and export an unsigned transaction for later usage
var exportedTxHex = "";
const tx = {
data: ["0x6d02", "hello world"]
}
datacash.build(tx, function(err, res) {
exportedTxHex = res;
})
// Later import exportedTxHex and sign it with privatkey, and broadcast, all in one method:
datacash.send({
tx: exportedTx,
cash: { key: "5JZ4RXH4MoXpaUQMcJHo8DxhZtkf5U5VnYd9zZH8BRKZuAbxZEw" }
}, function(err, hash) {
// hash contains the transaction hash after the broadcast
})
This time since the exported transaction is already signed, no need for additional cash.key
attriute when sending later
// Build and export an unsigned transaction for later usage
var exportedSignedTxHex = "";
const tx = {
data: ["0x6d02", "hello world"],
cash: { key: "5JZ4RXH4MoXpaUQMcJHo8DxhZtkf5U5VnYd9zZH8BRKZuAbxZEw" }
}
datacash.build(tx, function(err, res) {
exportedSignedTxHex = res;
})
// Later import exportedTxHex and broadcast, all in one method:
datacash.send({
tx: exportedSignedTx,
}, function(err, hash) {
// hash contains the transaction hash after the broadcast
})
Datacash depends on two powerful libraries for low level stuff.
While Datacash is designed to be the simplest possible way to write data to the blockchain, you may want to sometimes access the low level libraries that power datacash.
Datacash exposes additional endpoints so you can simply access these libraries without having to install or include any additional libraries.
This endpoint exposes the bitcore-lib-cash library object. Basically by referncing bch
you have access to the entire bitcore-lib-cash library.
const privateKey = new datacash.bch.PrivateKey();
const address = privateKey.toAddress();
console.log(address.toString()) // 15WZwpw3BofscM2u43ji85BXucai5YGToL
This endpoint is used to access the bitcore-explorers library.
Using this endpoint you can connect to a public JSON-RPC endpoint to let you make various direct JSON-RPC function calls such as getUnspentUtxos
, etc. (Basically it instantiates and returns the insight
object from https://github.com/bitpay/bitcore-explorers)
datacash.connect([RPC ENDPOINT]).[METHOD]
If you leave the RPC ENDPOINT
part out, it will automatically use the default https://cashexplorer.bitcoin.com node
getUnspentUtxos()
method:datacash.connect().getUnspentUtxos("14xMz8rKm4L83RuZdmsHXD2jvENZbv72vR", function(err, utxos) {
if (err) {
console.log("Error: ", err)
} else {
console.log(utxos)
}
})
datacash.connect('https://cashexplorer.bitcoin.com').getUnspentUtxos("14xMz8rKm4L83RuZdmsHXD2jvENZbv72vR", function(err, utxos) {
if (err) {
console.log("Error: ", err)
} else {
console.log(utxos)
}
});