README
¶
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.
Documentation
¶
Overview ¶
Package commcid provides helpers to convert between Piece/Data/Replica Commitments and their CID representation
Index ¶
- Constants
- Variables
- func CIDToCommitment(c cid.Cid) (FilMultiCodec, FilMultiHash, []byte, error)
- func CIDToDataCommitmentV1(c cid.Cid) ([]byte, error)
- func CIDToReplicaCommitmentV1(c cid.Cid) ([]byte, error)
- func CommitmentToCID(mc FilMultiCodec, mh FilMultiHash, commX []byte) (cid.Cid, error)
- func DataCommitmentV1ToCID(commD []byte) (cid.Cid, error)
- func ReplicaCommitmentV1ToCID(commR []byte) (cid.Cid, error)
- type FilMultiCodec
- type FilMultiHash
Constants ¶
const FILCODEC_UNDEFINED = FilMultiCodec(0)
FILCODEC_UNDEFINED is just a signifier for "no codec determined
const FILMULTIHASH_UNDEFINED = FilMultiHash(0)
FILMULTIHASH_UNDEFINED is a signifier for "no multihash etermined"
Variables ¶
var ( // ErrIncorrectCodec means the codec for a CID is a block format that does not match // a commitment hash ErrIncorrectCodec = errors.New("unexpected commitment codec") // ErrIncorrectHash means the hash function for this CID does not match the expected // hash for this type of commitment ErrIncorrectHash = errors.New("incorrect hashing function for data commitment") )
var CIDToPieceCommitmentV1 = CIDToDataCommitmentV1
CIDToPieceCommitmentV1 converts a CID to a commP -- it is just a helper function that is equivalent to CIDToDataCommitmentV1.
var PieceCommitmentV1ToCID = DataCommitmentV1ToCID
PieceCommitmentV1ToCID converts a commP to a CID -- it is just a helper function that is equivalent to DataCommitmentV1ToCID.
Functions ¶
func CIDToCommitment ¶
func CIDToCommitment(c cid.Cid) (FilMultiCodec, FilMultiHash, []byte, error)
CIDToCommitment extracts the raw commitment bytes, the FilMultiCodec and FilMultiHash from a CID, after validating that the codec and hash type are consistent
func CIDToDataCommitmentV1 ¶
CIDToDataCommitmentV1 extracts the raw data commitment from a CID after checking for the correct codec and hash types.
func CIDToReplicaCommitmentV1 ¶
CIDToReplicaCommitmentV1 extracts the raw replica commitment from a CID after checking for the correct codec and hash types.
func CommitmentToCID ¶
func CommitmentToCID(mc FilMultiCodec, mh FilMultiHash, commX []byte) (cid.Cid, error)
CommitmentToCID converts a raw commitment hash to a CID by adding: - the given filecoin codec type - the given filecoin hash type
func DataCommitmentV1ToCID ¶
DataCommitmentV1ToCID converts a raw data commitment to a CID by adding: - codec: cid.FilCommitmentUnsealed - hash type: multihash.SHA2_256_TRUNC254_PADDED
func ReplicaCommitmentV1ToCID ¶
ReplicaCommitmentV1ToCID converts a raw data commitment to a CID by adding: - codec: cid.FilCommitmentSealed - hash type: multihash.POSEIDON_BLS12_381_A1_FC1
Types ¶
type FilMultiCodec ¶
type FilMultiCodec uint64
FilMultiCodec is a uint64-sized type representing a Filecoin-specific codec
type FilMultiHash ¶
type FilMultiHash uint64
FilMultiHash is a uint64-sized type representing a Filecoin-specific multihash
Source Files