CoinFS (coinfs)

CoinFS is a NodeJS library for storing files in Bitcoin transactions. File sizes up to 40960 bytes are supported. Both Bitcoin and Testnet networks are supported.

How it works

During encoding, the file is broken down into 20-byte chunks, each encoded as a Bitcoin address, and added as an output on the CoinFS transaction, with a value of 2730 satoshis. This is the current minimum output, or the 'dust threshold'. This value can also be specified with the options.dust property, if needed. Two more outputs are required, one for the metadata, and one for the change address.

Usage

The cost of a CoinFS transaction is roughly the sum of its outputs (N+1 20-byte chunks of data x 2730 satoshis) plus the transaction fee (50000 satoshis per 1000 bytes of transaction). The number of inputs is also contributing to the cost. Each adds about 9000 satoshis to the transaction size.

var coinfs = require('coinfs')

var options = {
  network: 'bitcoin', // [bitcoin|testnet]
  inputs: 1
}

coinfs.estimateCost('./file.txt', options, function(err, cost) {
  console.log(cost)
})

Knowing the number of inputs for the transaction is often not possible, so then you'll have to take a guess. Over-estimating it should not be a problem, since the excess funds will be sendt back to the change address.

Encoding

The encode() function creates a raw transaction. This is a hexadecimal string that can be pushed directly onto the Bitcoin network using software like Bitcoin Core, or an online service like Blockcyper. The inputs property in the options object takes an array of objects pointing to unspent outputs of earlier transactions.

var coinfs = require('coinfs')

var options = {
  network: 'bitcoin',                   // [bitcoin|testnet]
  inputs: [{
    hash: 'a5b8da60259ad3a800....',     // TX hash,
    index: 1,                           // Index of TX output
    amount: 50000000,            		// Satoshis in TX output,
    WIF: '5J115WhqnVmZuD1xe4jc1g...'    // Private key of output address
  }],
  additionalFee: 50000,                 // Optional
  changeAddress: '1E8cEJRy38LC4sv8P...' // Bitcoin address to send the change to
}

coinfs.encode('./file.txt', options, function(err, transaction) {
  console.log(transaction.toHex())
})

Decoding

The decode() function takes a raw transaction as input, and extracts the data to a buffer. The transaction must be one generated using the encode() function.

var coinfs = require('coinfs')

var options = {
  network: 'bitcoin' // [bitcoin|testnet]
}

coinfs.decode(rawTransaction, options, function (err, data) {
  console.log(data.toString())
})

You could retrieve raw transactions from https://blockchain.info by querying its transaction hash, like this: https://blockchain.info/tx/9021b49d445c719106c95d561b9c3fac7bcb3650db67684a9226cd7fa1e1c1a0?format=hex

WARNING!!! - Use this library at your own risk! You should always verify the raw transactions before pushing them onto the network. Funds sent to Bitcoin addresses generated by this library are lost!