go-fil-commcid

Conversion Utilities Between CID and Piece/Data/Replica Commitments

Description

This provides utility functions to convert from commitment hashes used by Filecoin and Content IDs that meet the CIDv1 standard

Table of Contents

• Background
• Usage
• Contribute

Background

See the Filecoin PoRep Spec and the Filecoin Paper for how these commitment hashes (Piece Commitment, Data Commitment, Replica Commitment) are generated.

This library adds codes neccesary to convert those commitment hashes to CIDs

We define two combinations of codec and multihash:

• fil-commitment-unsealed + sha2-256-trunc254-padded for Piece Commitments and Data Commitments (shared due to identical underlying structure)
• fil-commitment-sealed + poseidon-bls12_381-a2-fc1 for Replica Commitments

Usage

Requires go 1.13

Install the module in your package or app with go get "github.com/filecoin-project/go-fil-commcid"

Generating CIDs for CommP, CommD, CommR

package mypackage

import (
        commcid "github.com/filecoin-project/go-fil-commcid"
)

var commP []byte
var commD []byte
var commR []byte            

// will error if the given commX is not the expected size (currently 32 bytes)
pieceCID, err := commcid.PieceCommitmentV1ToCID(commP)
unsealedSectorCID, err := commcid.DataCommitmentV1ToCID(commD)
sealedSectorCID, err := commcid.ReplicaCommitmentV1ToCID(commR)

Getting a raw CommP, CommR, CommD from a CID

package mypackage

import (
        commcid "github.com/filecoin-project/go-fil-commcid"
)

var pieceCID cid.Cid
var unsealedSectorCID cid.Cid
var sealedSectorCID cid.Cid           

// will error if pieceCID does not have the correct codec & hash type
commP, err := commcid.CIDToPieceCommitmentV1(pieceCID)

// will error if unsealedSectorCID does not have the correct codec & hash type
commD, err := commcid.CIDToDataCommitmentV1(unsealedSectorCID)

// will error if sealedSectorCID does not have the correct codec & hash type
commR, err := commcid.CIDToReplicaCommitmentV1(sealedSectorCID)

Going from arbitrary commitment to CID and back

As Filecoin evolves, there will likely be new and better constructions for both sealed and unsealed data. Note V1 in front of the above method names.

To support future evolution, we provide more generalized methods for going back and forth:

package mypackage

import (
        commcid "github.com/filecoin-project/go-fil-commcid"
)

var commIn []byte
var filCodec commcid.FilMultiCodec
var filHashAlg commcid.FilMultiHash

commCID, err := commcid.CommmitmentToCID(filCodecIn, filHashAlgIn, commIn)

filCodecOut, filHashOut, commOut, err := commcid.CIDToCommitment(commCID)

Contributing

PRs are welcome! Please first read the design docs and look over the current code. PRs against master require approval of at least two maintainers. For the rest, please see our CONTRIBUTING guide.

License

This repository is dual-licensed under Apache 2.0 and MIT terms.

Copyright 2019. Protocol Labs, Inc.