@xinfin/osx-sdk-ipfs

Aragon JS SDK IPFS

@aragon/sdk-ifps provides a wrapper to send requests to an IPFS Cluster using the IPFS API. It supports standard requests as well as streamed requests.

Installation

Use npm or yarn to install @xinfin/osx-ipfs.

npm install @xinfin/osx-ipfs
yarn add @xinfin/osx-ipfs

Usage

IPFS Client

The Aragon infrastructure uses an IPFS cluster which requires authentication based on an API key. The provided Client works as well on any canonical deployment by just not providing any API key in the headers.

import { Client as IpfsClient } from "@xinfin/osx-ipfs";

const headers = {
  "X-API-KEY": "1234...",
};
const client = new IpfsClient(clusterUrl, headers);

Node info

Retrieves the details of the node behind the endpoint.

const client = new IpfsClient(clusterUrl, headers);

const versionInfo = await client.nodeInfo();
console.log(versionInfo);
// {
//   id: string;
//   addresses: string[];
//   agentVersion: string;
//   protocolVersion: string;
//   protocols: string[];
//   publicKey: string;
// }

IPFS add

Uploads data to the IPFS cluster and returns the hash of the newly pinned file. The following data types are supported:

As a string (preferred)

const client = new IpfsClient(clusterUrl, headers);

const content = "I am a test";
const { hash } = await client.add(content);
console.log(hash);
// QmeJ4kRW21RRgjywi9ydvY44kfx71x2WbRq7ik5xh5zBZK

Uint8Array (preferred)

const client = new IpfsClient(clusterUrl, headers);

const content = Uint8Array([73, 32, 97, 109, 32, 97, 32, 116, 101, 115, 116]);
const { hash } = await client.add(content);
console.log(hash);
// QmeJ4kRW21RRgjywi9ydvY44kfx71x2WbRq7ik5xh5zBZK

File (browser-only)

const client = new IpfsClient(clusterUrl, headers);

const content = new File(["I am a test"], "test.txt", { type: "text/plain" });
const { hash } = await client.add(content);
console.log(hash);
// QmeJ4kRW21RRgjywi9ydvY44kfx71x2WbRq7ik5xh5zBZK

Blob (browser-only)

const client = new IpfsClient(clusterUrl, headers);

const content = new File(["I am a test"], { type: "text/plain" });
const { hash } = await client.add(content);
console.log(hash);
// QmeJ4kRW21RRgjywi9ydvY44kfx71x2WbRq7ik5xh5zBZK

IPFS cat

Fetches the content behind the given CiD and returns it as a Uint8Array.

const client = new IpfsClient(clusterUrl, headers);

const cid = "QmeJ4kRW21RRgjywi9ydvY44kfx71x2WbRq7ik5xh5zBZK";
const recoveredBytes = await client.cat(cid);
console.log(recoveredBytes);
// Uint8Array(11) [
//    73, 32,  97, 109,  32,
//    97, 32, 116, 101, 115,
//   116
// ]

Decoding as text

const recoveredString = new TextDecoder().decode(recoveredBytes);
console.log(recoveredString);
// I am a test

IPFS pin

Requests the node to keep a local copy of the data behind the given CiD.

const client = new IpfsClient(clusterUrl, headers);

const cid = "QmeJ4kRW21RRgjywi9ydvY44kfx71x2WbRq7ik5xh5zBZK";
const { pins } = await client.pin(cid);
console.log(pins);
// ["QmeJ4kRW21RRgjywi9ydvY44kfx71x2WbRq7ik5xh5zBZK"]

Note: Using IPFS pin on the Aragon IPFS cluster may be restricted. Use IPFS add instead.

IPFS unpin

Requests the node to keep a local copy of the data behind the given CiD.

const client = new IpfsClient(clusterUrl, headers);

const cid = "QmeJ4kRW21RRgjywi9ydvY44kfx71x2WbRq7ik5xh5zBZK";
const { pins } = await client.unpin(cid);
console.log(pins);
// ["QmeJ4kRW21RRgjywi9ydvY44kfx71x2WbRq7ik5xh5zBZK"]

Note: Using IPFS unpin on the Aragon IPFS cluster may be restricted.

Testing

To execute library tests just run:

yarn build
yarn test