Knowledge Base Home

IPFS

IPFS, in a similar manner to blockchain, addresses the issue of central server data ownership by dispersing file contents across multiple nodes. This peer-to-peer file sharing technique removes the possibility of censorship or unilateral deletion, because no single party owns or controls the data once it has been uploaded to the network. In fact, if a user chooses to “pin” a file to one or more of their IPFS nodes, the file will always be available for themselves and the entirety of the network to retrieve. The act of pinning, while not strictly necessary, is a strategic tactic that permanently preserves a file so that the network does not run the risk of losing critical blocks as nodes go offline and/or perform database cleanups.

The IPFS user interface provides a clean and simple experience for uploading, retrieving and viewing files. Upon upload, files are carved into 256kb shards, designated with a unique identifying hash and randomly disseminated to various nodes in the network. Files can then be immediately retrieved and inspected by simply referencing the corresponding hash. This combination of distributed computing and content-based addressing (as opposed to location-based addressing) makes IPFS both highly-performant and reliably persistent. As such, IPFS can serve as a trusted data store for high memory files (e.g. images and multi-page contracts) with the blockchain layer needing only a reference to the hash.

Provision IPFS Nodes

You can elect for one of two approaches to provision IPFS Nodes: Kaleido Console UI or Admin API. For users unfamiliar with the Kaleido REST API, the console interface is the recommended happy path. Both approaches will ultimately result in a new IPFS node running within the specified environment.

UI:

  • Navigate to an existing environment, and click the +ADD dropdown in the top right portion of the screen.
  • Select the Add Services option. This will open a new panel exposing the currently available Kaleido Services.
  • Click the ADD button beneath IPFS.
  • Supply an arbitrary name for the node and click ADD. Click DONE to finish the deployment.
  • The newly created IPFS node will appear at the bottom of your environment panel under MEMBER SERVICES.
  • Repeat the process to provision additional nodes.

API:

NOTE: The following deployment approach assumes a strong understanding of the Kaleido APIs. Please refer to the Kaleido Resource Model for object relationships, the API 101 topic for sample CRUD operations and Understanding the Kaleido API for detailed descriptions of the various endpoints and routes.

IPFS nodes are provisioned against the /services API endpoint and exist as “member” type services.  In other words, the resource is fully-owned and controlled by the provisioning member.

To programmatically create an IPFS node, specify the consortia and environment IDs in the path and POST to the /services endpoint with a name, the service type and membership ID in the body of the call. The forthcoming sample commands assume that the following environment variables have been set as follows:

export APIURL="https://console.kaleido.io/api/v1"
export APIKEY="YOUR_API_KEY"
export HDR_AUTH="Authorization: Bearer $APIKEY"
export HDR_CT="Content-Type: application/json"

If you are targeting an environment outside of the US, make sure to modify your URL accordingly. The ap qualifier resolves to Sydney, while ko resolves to Seoul:

export APIURL="https://console-eu.kaleido.io/api/v1"
export APIURL="https://console-ap.kaleido.io/api/v1"
export APIURL="https://console-ko.kaleido.io/api/v1"

Use the POST method to provision the service and optionally format the output using jq:

# replace the membership_id placeholder with one of your membership IDs
curl -X POST -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/environments/{environment_id}/services" -d '{"name":"exampleIPFSnode", "service":"ipfs", "membership_id":"{membership_id}"}' | jq

This will return you a JSON payload containing the service ID.  Next, you can call a GET on the /services endpoint and specify the service ID for your IPFS node.  For example:

curl -X GET -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/environments{environment_id}/services/{service_id}" | jq

This call returns a JSON payload containing the node specific details.  Namely it provides the targetable URL for interaction with your IPFS node. For example:

{
  "_id": "u0ria6l9rx",
  "name": "exampleIPFSnode",
  "service": "ipfs",
  "membership_id": "u0bvfy5467",
  "details": {},
  "service_guid": "1878bcdf-a5b5-45a9-b279-5f8bb38d36da",
  "service_type": "member",
  "state": "started",
  "_revision": "1",
  "created_at": "2018-09-28T15:17:18.687Z",
  "environment_id": "u0iwnhf0ir",
  "urls": {
    "http": "https://u0kn2j7tub-u0tbrb4lmi-ipfs.kaleido.io"
    "webui": "https://u0kn2j7tub-u0tbrb4lmi-ipfs.kaleido.io/ipfs/Qmbo8PfVs4WWanjFPMboP8Gx5hunN1Tn5kLMmhvB3L1LVd"
  },
  "updated_at": "2018-09-28T15:17:23.184Z"
}

As is the case with a regular node, the ingress to the IPFS node is TLS protected. All calls require the presence of application credentials that have been generated against the same membership ID that provisioned the node.

Interacting with an IPFS Node

The easiest way to interact with IPFS is via the Kaleido console and the simple IPFS user interface.  From your environment panel:

  • Click the dropdown next to your IPFS node.  Select View Dashboard.
  • This opens a new window.  You have the option of leveraging existing application credentials to connect to the IPFS node or you can generate a new set of credentials specifically for your IPFS node. If you choose to generate new credentials, copy them and store the secret somewhere safe.  You will always need to supply a set of active credentials corresponding to the IPFS node’s membership ID for any interactions with the IPFS node.
  • Click the OPEN IPFS WEB UI button at the bottom of the screen.
  • This will open a new window within which you can interact with your IPFS node and the rest of the network.

IPFS Web UI

  • The Home screen within the IPFS UI will display specific details about the IPFS node.  Namely it exposes:  Peer ID, Protocol Version, Agent Version and Public Key.
  • The Connections screen displays all other IPFS nodes that are active in the environment.  A peer to peer gossip protocol allows all IPFS nodes to immediately discover newly joined peers.
  • Use the Files screen to create directory structures and upload files/images to the network. Create a new directory by clicking the Create Folder hyperlink and inputting a name for the folder.  Add a new file to the network by clicking the Upload hyperlink and then selecting the desired file on your local system.  If you want to upload the file into an existing directory, click into the folder and then use the Upload hyperlink.
  • Use the DAG (directed acyclic graph) screen to view directory contents and to see the various shards of specific files.  The DAG screen is particularly useful when you want to see a listing of all files in a directory and/or you want to download specific portions of a file.  For example, perhaps you only want the first five minutes of an uploaded video.

IPFS API

If you prefer to programmatically interact with your IPFS node(s) there are two convenient endpoints for file upload and retrieval – /add & /cat

  • To upload a file use the /add endpoint and specify the path to file on your local machine.  This call is a --form entry with name of the entry specified as “path” and the route to the local file supplied as a value.  The IPFS endpoint must be fronted by a valid set of application credentials created against the same membership that provisioned the node.  For example, to upload a text file named file.txt from your $HOME directory:

curl --form "path=@/Users/johndoe/file.txt" https://u0kxkv4m7p:YFdCpp72cShpFqrhmy-EvBPUBzo9wgN1kVL5bs2e8Kg@zzol84uiv1-u0m93jbc8p-ipfs.kaleido.io/api/v0/add | jq

  • This will return a JSON object containing the file name, the hash and the file size.  For example:
{
  "Name": "file.txt",
  "Hash": "QmfM2r8seH2GiRaC4esTjeraXEachRt8ZsSeGaWTPLyMoG",
  "Size": "21"
}
  • Use the /cat endpoint along with a file hash to retrieve an uploaded file.  By default files are returned as text representations of the referenced hash, therefore you are responsible for supplying a file name with the proper extension in order to successfully download properly formatted files.  For example, to retrieve a .png file and output it into your $HOME directory:

curl https://u0kxkv4m7p:YFdCpp72cShpFqrhmy-EvBPUBzo9wgN1kVL5bs2e8Kg@zzol84uiv1-u0m93jbc8p-ipfs.kaleido.io/api/v0/cat/{file-hash} -o /Users/johndoe/image.png

IPFS nodes are provisioned against the /services API and require the enumeration of the service type in the body of the call.

  • Refer to the API Reference documentation for the full /services specification.
  • Refer back to the Tech Info tab for sample calls and additional clarification.  For example, to provision an IPFS node:

curl -X POST -H "$HDR_AUTH" -H "$HDR_CT" "$APIURL/consortia/{consortia_id}/environment{environment_id}/services" -d '{"membership_id":"{membership_id}", "name":"IPFSnode", "service":"ipfs"}' | jq

Interact with an IPFS node in the Kaleido Samples Gallery.  The IPFS sample is reliant on the following configuration parameters:

  • Consortia ID
  • App Credentials username and password
  • IPFS RPC endpoint

You can create these resources using the Kaleido Console or via the administrative API.

Prev HD Wallet Next On-Chain Registry