README.md

Getting started with Helia

Explore the docs · View Demo · Report Bug · Request Feature/Example

Table of Contents

• Table of Contents
• About The Project
• Getting Started
  • Prerequisites
  • Installation
  • Running Examples
• Usage
  • 101 - Basics
  • 201 - Storage
    • Blockstore
    • Datastore
  • 301 - Networking
    • libp2p
  • Putting it all together
• Documentation
• Contributing
• Want to hack on IPFS?

About The Project

• Read the docs
• Look into other examples to learn how to spawn a Helia node in Node.js and in the Browser
• Visit https://dweb-primer.ipfs.io to learn about IPFS and the concepts that underpin it
• Head over to https://proto.school to take interactive tutorials that cover core IPFS APIs
• Check out https://docs.ipfs.io for tips, how-tos and more
• See https://blog.ipfs.io for news and more
• Need help? Please ask 'How do I?' questions on https://discuss.ipfs.io

Getting Started

Prerequisites

Make sure you have installed all of the following prerequisites on your development machine:

• Git - Download & Install Git. OSX and Linux machines typically have this already installed.
• Node.js - Download & Install Node.js and the npm package manager.

Installation

> npm install

Running Examples

> npm run 101-basics
> npm run 201-storage
> npm run 301-networking
> npm run 401-providing

Usage

In this tutorial, we go through spawning a Helia node and interacting with UnixFS, adding bytes, directories, and files to the node and retrieving them.

It is split into multiple parts, each part builds on the previous one - basics of interaction with UnixFS, storage, networking, and finally providing, garbage collection and pinning.

For this tutorial, you need to install all dependencies in the package.json using npm install.

101 - Basics

The first example goes into the the basics of interacting with UnixFS, adding bytes, directories, and files to the node and retrieving them.

To run it, use the following command:

> npm run 101-basics

201 - Storage

Out of the box Helia will store all data in-memory. This makes it easy to get started, and to create short-lived nodes that do not persist state between restarts, but what if you want to store large amounts of data for long amounts of time?

Take a look at 201-storage.js where we explore how to configure different types of persistent storage for your Helia node.

To run it, use the following command:

> npm run 201-storage

If you run the example twice: you may notice that the second time the file is found in the blockstore without being added again.

Blockstore

At it's heart IPFS is about blocks of data addressed by a CID. When you add a file to your local Helia node, it is split up into a number of blocks, all of which are stored in a blockstore.

Each block has a CID, an identifier that is unique to that block and can be used to request it from other nodes in the network.

A blockstore is a key/value store where the keys are CIDs and the values are Uint8Arrays.

By default we're going to use an in-memory blockstore, though later you may wish to use one that stores blocks on a filesystem.

import { MemoryBlockstore } from 'blockstore-core'

const blockstore = new MemoryBlockstore()

There are many blockstore implementations available. Some common ones are:

• blockstore-fs - store blocks in a directory on the filesystem using Node.js
• blockstore-idb - store blocks in IndexedDB in the browser
• blockstore-s3 - store blocks in an AWS S3 bucket

Datastore

Some facility to store information is required, this needs a datastore.

Similar to the blockstore, a datastore is a key/value store where the keys are strings and the values are Uint8Arrays.

import { MemoryDatastore } from 'datastore-core'

const datastore = new MemoryDatastore()

Commonly used datastore implementations are:

• datastore-level - store key/value pairs in a LevelDB instance
• datastore-idb - store key/value pairs in IndexedDB in the browser
• datastore-s3 - store key/value pairs in an AWS S3 bucket

301 - Networking

The final example is 301-networking.js.

Adding blocks to your local blockstore is great but using your Helia node's libp2p instance allows you to unlock the full power of the distributed web.

With libp2p configured you can retrieve blocks from remote peers, and those peers can retrieve blocks from you.

libp2p

libp2p is the networking layer that IPFS works on top of. It is a modular system, comprising of transports, connection encrypters, stream multiplexers, etc.

import { createLibp2p } from 'libp2p'
import { identifyService } from 'libp2p/identify'
import { noise } from '@chainsafe/libp2p-noise'
import { yamux } from '@chainsafe/libp2p-yamux'
import { webSockets } from '@libp2p/websockets'
import { bootstrap } from '@libp2p/bootstrap'
import { MemoryDatastore } from 'datastore-core'

const datastore = new MemoryDatastore()

const libp2p = await createLibp2p({
  datastore,
  transports: [
    webSockets()
  ],
  connectionEncrypters: [
    noise()
  ],
  streamMuxers: [
    yamux()
  ],
  peerDiscovery: [
    bootstrap({
      list: [
        "/dnsaddr/bootstrap.libp2p.io/p2p/QmNnooDu7bfjPFoTZYxMNLWUQJyrVwtbZg5gBMjTezGAJN",
        "/dnsaddr/bootstrap.libp2p.io/p2p/QmQCU2EcMqAqQPR2i9bChDtGNJchTbq5TbXJJ16u19uLTa",
        "/dnsaddr/bootstrap.libp2p.io/p2p/QmbLHAnMoJPWSCR5Zhtx6BHJX9KiKNN6tpvbUcqanj75Nb",
        "/dnsaddr/bootstrap.libp2p.io/p2p/QmcZf59bWwK5XFi76CZX8cbJ4BhTzzA3gU1ZjYZcYW3dwt"
      ]
    })
  ],
  services: {
    identify: identifyService()
  }
})

401 - Providing

The final example is 401-providing.js.

This example shows:

• How to run garbage collection,
• Pin blocks to prevent them from being garbage collected
• Add metadata to pins
• Provide it to the DHT so that other nodes can find and retrieve it.

To run it, use the following command:

> npm run 401-providing

Putting it all together

Since your Helia node is configured with a libp2p node, you can go to an IPFS Gateway and load the printed hash. Go ahead and try it!

> npm run 301-networking

Added file: bafkreife2klsil6kaxqhvmhgldpsvk5yutzm4i5bgjoq6fydefwtihnesa
# Copy that hash and load it on the gateway, here is a prefilled url:
# https://ipfs.io/ipfs/bafkreife2klsil6kaxqhvmhgldpsvk5yutzm4i5bgjoq6fydefwtihnesa

That's it! You just added and retrieved a file from IPFS!

For more examples, please refer to the Documentation

Documentation

• IPFS Primer
• IPFS Docs
• Tutorials
• More examples
• API - Helia
• API - @helia/unixfs

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the IPFS Project
2. Create your Feature Branch (git checkout -b feature/amazing-feature)
3. Commit your Changes (git commit -a -m 'feat: add some amazing feature')
4. Push to the Branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Want to hack on IPFS?

The IPFS implementation in JavaScript needs your help! There are a few things you can do right now to help out:

Read the Code of Conduct and JavaScript Contributing Guidelines.

• Check out existing issues The issue list has many that are marked as 'help wanted' or 'difficulty:easy' which make great starting points for development, many of which can be tackled with no prior IPFS knowledge
• Look at the Helia Roadmap This are the high priority items being worked on right now
• Perform code reviews More eyes will help a. speed the project along b. ensure quality, and c. reduce possible future bugs
• Add tests. There can never be enough tests