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
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.