bitfs

bitcoin file system

0. What is bitFS?

bitFS is an autonomous file system constructed from Bitcoin transactions.

1. What gets stored to bitFS?

bitFS crawls the bitcoin blockchain to find and store all the bitcoin script pushdata chunks larger than 512 bytes.

Let's imagine the following Bitcoin script:

OP_0 OP_RETURN <1MB Image Buffer> OP_0 "Hello World"

In this case, bitFS will only store the image buffer chunk as a file. The rest will be ignored because they are either opcodes or smaller than than 512 bytes

SUMMARY: If you want to store your data on bitFS, make it larger than 512 bytes!

2. How does bitFS URI scheme work?

bitfs uses an intuitive bitcoin-native URI scheme to reference files, all the way down to each script chunk level.

bitfs://<TRANSACTION_ID>.(in|out).<SCRIPT_INDEX>.<CHUNK_INDEX>

For example, here's a bitFS URI:

bitfs://037af9073c8151486f987aa0a4a884af990875a26b700a6042580402b68fa9be.out.0.6

The URI points to the data chunk at:

  1. Index 6 Pushdata
  2. of the Index 0 output script
  3. of The transaction 037af9073c8151486f987aa0a4a884af990875a26b700a6042580402b68fa9be

3. How to use bitFS?

Currently the URI is served over HTTP to ensure accessibility.

For example, the bitfs URI bitfs://037af9073c8151486f987aa0a4a884af990875a26b700a6042580402b68fa9be.out.0.6 is hosted at:

https://x.bitfs.network/037af9073c8151486f987aa0a4a884af990875a26b700a6042580402b68fa9be.out.0.6

With the URI, you can fetch and use the object directly:

For example, the bitfs URI bitfs://13513153d455cdb394ce01b5238f36e180ea33a9ccdf5a9ad83973f2d423684a.out.0.4 contains the following object:

{
  "t": -1.1,
  "h": 74,
  "p": 1028,
  "c": 90,
  "ws": 3.26,
  "wd": 192,
  "f": [
    {
      "dt": 1581440400,
      "tmax": 3.91,
      "tmin": -0.26,
      "h": 99,
      "p": 1008,
      "r": 13.07,
      "c": 100,
      "ws": 2.06,
      "wd": 15,
      "desc": "Rain"
    },
    {
      "dt": 1581526800,
      "tmax": 4.05,
      "tmin": -2.2,
      "h": 55,
      "p": 1020,
      "c": 84,
      "ws": 3.12,
      "wd": 245,
      "desc": "Snow"
    },
    {
      "dt": 1581613200,
      "tmax": 1.27,
      "tmin": -8.05,
      "h": 98,
      "p": 999,
      "r": 6.81,
      "c": 100,
      "ws": 2.46,
      "wd": 352,
      "desc": "Snow"
    },
    {
      "dt": 1581699600,
      "tmax": -11.18,
      "tmin": -15.89,
      "h": 59,
      "p": 1031,
      "c": 0,
      "ws": 5.17,
      "wd": 328,
      "desc": "Clear"
    },
    {
      "dt": 1581786000,
      "tmax": -4.86,
      "tmin": -16.85,
      "h": 53,
      "p": 1039,
      "c": 87,
      "ws": 3.23,
      "wd": 210,
      "desc": "Clouds"
    }
  ]
}

We can fetch this file and proces it:

const axios = require('axios')
const bitfs = "13513153d455cdb394ce01b5238f36e180ea33a9ccdf5a9ad83973f2d423684a.out.0.4"
const url = "https://x.bitfs.network/" + bitfs
axios.get(url).then((res) => {
  const result= res.data.f.map((d) => {
    return {
      time: new Date(d.dt),
      weather: d.desc
    }
  })
  console.log(result)
})

The code will print:

$ node index.js
[
  { time: 1970-01-19T07:17:20.400Z, weather: 'Rain' },
  { time: 1970-01-19T07:18:46.800Z, weather: 'Snow' },
  { time: 1970-01-19T07:20:13.200Z, weather: 'Snow' },
  { time: 1970-01-19T07:21:39.600Z, weather: 'Clear' },
  { time: 1970-01-19T07:23:06.000Z, weather: 'Clouds' }
]

4. How does bitFS store files?

a. Raw Format

everything is efficiently stored in raw binary format. No encoding conversion. bitFS directly streams raw buffer from Bitcoin into the file storage. Developers can decode or render the files as they wish.

b. Content Type

When storing, bitFS automatically extracts and uses the file header from each chunk when it's served over the Internet

c. Portable file system

bitFS is a virtual file system which creates a bitcoin abstraction on top of a cloud storage. The file system can be easily recreated by crawling through the blockchain with Planaria. Also, the canonical URI system which can describe every dimension of a Bitcoin transaction, makes the file system portable.

e. For Developers

With the intuitive URI scheme, you can easily fetch specific parts of Bitcoin transactions and use them for your apps, all the way down to the script chunk level.