retrievaltypes

package module
v1.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 6, 2023 License: Apache-2.0, MIT Imports: 21 Imported by: 5

README

go-retrieval-types

This is an extraction of types from go-fil-markets used in the libp2p /fil/retrieval/qry/1.0.0 protocol and the Filecoin Markets V1 retrieval protocol

License

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

Copyright 2022. Protocol Labs, Inc.

Documentation

Index

Constants

View Source 
const DealPaymentType = datatransfer.TypeIdentifier("RetrievalDealPayment/1")

DealPaymentType is the DealPayment voucher type

View Source 
const DealProposalType = datatransfer.TypeIdentifier("RetrievalDealProposal/1")

DealProposalType is the DealProposal voucher type

View Source 
const DealResponseType = datatransfer.TypeIdentifier("RetrievalDealResponse/1")

DealResponseType is the DealResponse usable as a voucher type

Variables

View Source 
var AddressBindnodeOption = bindnode.TypedBytesConverter(&address.Address{}, addressFromBytes, addressToBytes)

AddressBindnodeOption converts a filecoin Address type to and from a Bytes field in a schema

View Source 
var BigIntBindnodeOption = bindnode.TypedBytesConverter(&big.Int{}, bigIntFromBytes, bigIntToBytes)

BigIntBindnodeOption converts a big.Int type to and from a Bytes field in a schema

View Source 
var BindnodeRegistry = bindnoderegistry.NewRegistry()
View Source 
var CborGenCompatibleNodeBindnodeOption = bindnode.TypedAnyConverter(&CborGenCompatibleNode{}, cborGenCompatibleNodeFromAny, cborGenCompatibleNodeToAny)

CborGenCompatibleNodeBindnodeOption converts a CborGenCompatibleNode type to and from an Any field in a schema

View Source 
var DealPaymentUndefined = DealPayment{}

DealPaymentUndefined is an undefined deal payment

View Source 
var DealProposalUndefined = DealProposal{}

DealProposalUndefined is an undefined deal proposal

View Source 
var DealResponseUndefined = DealResponse{}

DealResponseUndefined is an undefined deal response

View Source 
var DealStatuses = map[DealStatus]string{
	DealStatusNew:                              "DealStatusNew",
	DealStatusUnsealing:                        "DealStatusUnsealing",
	DealStatusUnsealed:                         "DealStatusUnsealed",
	DealStatusWaitForAcceptance:                "DealStatusWaitForAcceptance",
	DealStatusPaymentChannelCreating:           "DealStatusPaymentChannelCreating",
	DealStatusPaymentChannelAddingFunds:        "DealStatusPaymentChannelAddingFunds",
	DealStatusAccepted:                         "DealStatusAccepted",
	DealStatusFundsNeededUnseal:                "DealStatusFundsNeededUnseal",
	DealStatusFailing:                          "DealStatusFailing",
	DealStatusRejected:                         "DealStatusRejected",
	DealStatusFundsNeeded:                      "DealStatusFundsNeeded",
	DealStatusSendFunds:                        "DealStatusSendFunds",
	DealStatusSendFundsLastPayment:             "DealStatusSendFundsLastPayment",
	DealStatusOngoing:                          "DealStatusOngoing",
	DealStatusFundsNeededLastPayment:           "DealStatusFundsNeededLastPayment",
	DealStatusCompleted:                        "DealStatusCompleted",
	DealStatusDealNotFound:                     "DealStatusDealNotFound",
	DealStatusErrored:                          "DealStatusErrored",
	DealStatusBlocksComplete:                   "DealStatusBlocksComplete",
	DealStatusFinalizing:                       "DealStatusFinalizing",
	DealStatusCompleting:                       "DealStatusCompleting",
	DealStatusCheckComplete:                    "DealStatusCheckComplete",
	DealStatusCheckFunds:                       "DealStatusCheckFunds",
	DealStatusInsufficientFunds:                "DealStatusInsufficientFunds",
	DealStatusPaymentChannelAllocatingLane:     "DealStatusPaymentChannelAllocatingLane",
	DealStatusCancelling:                       "DealStatusCancelling",
	DealStatusCancelled:                        "DealStatusCancelled",
	DealStatusRetryLegacy:                      "DealStatusRetryLegacy",
	DealStatusWaitForAcceptanceLegacy:          "DealStatusWaitForAcceptanceLegacy",
	DealStatusClientWaitingForLastBlocks:       "DealStatusWaitingForLastBlocks",
	DealStatusPaymentChannelAddingInitialFunds: "DealStatusPaymentChannelAddingInitialFunds",
	DealStatusErroring:                         "DealStatusErroring",
	DealStatusRejecting:                        "DealStatusRejecting",
	DealStatusDealNotFoundCleanup:              "DealStatusDealNotFoundCleanup",
	DealStatusFinalizingBlockstore:             "DealStatusFinalizingBlockstore",
}

DealStatuses maps deal status to a human readable representation

View Source 
var QueryResponseUndefined = QueryResponse{}

QueryResponseUndefined is an empty QueryResponse

View Source 
var QueryUndefined = Query{}

QueryUndefined is a query with no values

View Source 
var SignatureBindnodeOption = bindnode.TypedBytesConverter(&crypto.Signature{}, signatureFromBytes, signatureToBytes)

SignatureBindnodeOption converts a filecoin Signature type to and from a Bytes field in a schema

View Source 
var TokenAmountBindnodeOption = bindnode.TypedBytesConverter(&abi.TokenAmount{}, tokenAmountFromBytes, tokenAmountToBytes)

TokenAmountBindnodeOption converts a filecoin abi.TokenAmount type to and from a Bytes field in a schema

Functions

func RetrievalTypeFromVoucher added in v1.1.0 

func RetrievalTypeFromVoucher(tv datatransfer.TypedVoucher) (interface{}, error)

Types

type CborGenCompatibleNode 

type CborGenCompatibleNode struct {
	Node datamodel.Node
}

CborGenCompatibleNode is for cbor-gen / go-ipld-prime compatibility, to replace Deferred types that are used to represent datamodel.Nodes. This shouldn't be used as a pointer (nullable/optional) as it can consume "Null" tokens and therefore be a Null. Instead, use CborGenCompatibleNode#IsNull to check for null status.

func (CborGenCompatibleNode) IsNull 

func (sn CborGenCompatibleNode) IsNull() bool

func (*CborGenCompatibleNode) MarshalCBOR 

func (sn *CborGenCompatibleNode) MarshalCBOR(w io.Writer) error

MarshalCBOR is for cbor-gen compatibility

func (*CborGenCompatibleNode) UnmarshalCBOR 

func (sn *CborGenCompatibleNode) UnmarshalCBOR(r io.Reader) error

UnmarshalCBOR is for cbor-gen compatibility

type DealID 

type DealID uint64

DealID is an identifier for a retrieval deal (unique to a client)

func (DealID) String 

func (d DealID) String() string

type DealPayment 

type DealPayment struct {
	ID             DealID
	PaymentChannel address.Address
	PaymentVoucher *paychtypes.SignedVoucher
}

DealPayment is a payment for an in progress retrieval deal

func DealPaymentFromNode 

func DealPaymentFromNode(node datamodel.Node) (*DealPayment, error)

func (*DealPayment) AsVoucher added in v1.1.0 

func (dp *DealPayment) AsVoucher() datatransfer.TypedVoucher

func (*DealPayment) MarshalCBOR 

func (t *DealPayment) MarshalCBOR(w io.Writer) error

func (*DealPayment) UnmarshalCBOR 

func (t *DealPayment) UnmarshalCBOR(r io.Reader) (err error)

type DealProposal 

type DealProposal struct {
	PayloadCID cid.Cid
	ID         DealID
	Params
}

DealProposal is a proposal for a new retrieval deal

func DealProposalFromNode 

func DealProposalFromNode(node datamodel.Node) (*DealProposal, error)

func (*DealProposal) AsVoucher added in v1.1.0 

func (dp *DealProposal) AsVoucher() datatransfer.TypedVoucher

func (*DealProposal) MarshalCBOR 

func (t *DealProposal) MarshalCBOR(w io.Writer) error

func (*DealProposal) UnmarshalCBOR 

func (t *DealProposal) UnmarshalCBOR(r io.Reader) (err error)

type DealResponse 

type DealResponse struct {
	Status DealStatus
	ID     DealID

	// payment required to proceed
	PaymentOwed abi.TokenAmount

	Message string
}

DealResponse is a response to a retrieval deal proposal

func DealResponseFromNode 

func DealResponseFromNode(node datamodel.Node) (*DealResponse, error)

func (*DealResponse) AsVoucher added in v1.1.0 

func (dr *DealResponse) AsVoucher() datatransfer.TypedVoucher

func (*DealResponse) MarshalCBOR 

func (t *DealResponse) MarshalCBOR(w io.Writer) error

func (*DealResponse) UnmarshalCBOR 

func (t *DealResponse) UnmarshalCBOR(r io.Reader) (err error)

type DealStatus 

type DealStatus uint64
const (
	// DealStatusNew is a deal that nothing has happened with yet
	DealStatusNew DealStatus = iota

	// DealStatusUnsealing means the provider is unsealing data
	DealStatusUnsealing

	// DealStatusUnsealed means the provider has finished unsealing data
	DealStatusUnsealed

	// DealStatusWaitForAcceptance means we're waiting to hear back if the provider accepted our deal
	DealStatusWaitForAcceptance

	// DealStatusPaymentChannelCreating is the status set while waiting for the
	// payment channel creation to complete
	DealStatusPaymentChannelCreating

	// DealStatusPaymentChannelAddingFunds is the status when we are waiting for funds
	// to finish being sent to the payment channel
	DealStatusPaymentChannelAddingFunds

	// DealStatusAccepted means a deal has been accepted by a provider
	// and its is ready to proceed with retrieval
	DealStatusAccepted

	// DealStatusFundsNeededUnseal means a deal has been accepted by a provider
	// and payment is needed to unseal the data
	DealStatusFundsNeededUnseal

	// DealStatusFailing indicates something went wrong during a retrieval,
	// and we are cleaning up before terminating with an error
	DealStatusFailing

	// DealStatusRejected indicates the provider rejected a client's deal proposal
	// for some reason
	DealStatusRejected

	// DealStatusFundsNeeded indicates the provider needs a payment voucher to
	// continue processing the deal
	DealStatusFundsNeeded

	// DealStatusSendFunds indicates the client is now going to send funds because we reached the threshold of the last payment
	DealStatusSendFunds

	// DealStatusSendFundsLastPayment indicates the client is now going to send final funds because
	// we reached the threshold of the final payment
	DealStatusSendFundsLastPayment

	// DealStatusOngoing indicates the provider is continuing to process a deal
	DealStatusOngoing

	// DealStatusFundsNeededLastPayment indicates the provider needs a payment voucher
	// in order to complete a deal
	DealStatusFundsNeededLastPayment

	// DealStatusCompleted indicates a deal is complete
	DealStatusCompleted

	// DealStatusDealNotFound indicates an update was received for a deal that could
	// not be identified
	DealStatusDealNotFound

	// DealStatusErrored indicates a deal has terminated in an error
	DealStatusErrored

	// DealStatusBlocksComplete indicates that all blocks have been processed for the piece
	DealStatusBlocksComplete

	// DealStatusFinalizing means the last payment has been received and
	// we are just confirming the deal is complete
	DealStatusFinalizing

	// DealStatusCompleting is just an inbetween state to perform final cleanup of
	// complete deals
	DealStatusCompleting

	// DealStatusCheckComplete is used for when the provided completes without a last payment
	// requested cycle, to verify we have received all blocks
	DealStatusCheckComplete

	// DealStatusCheckFunds means we are looking at the state of funding for the channel to determine
	// if more money is incoming
	DealStatusCheckFunds

	// DealStatusInsufficientFunds indicates we have depleted funds for the retrieval payment channel
	// - we can resume after funds are added
	DealStatusInsufficientFunds

	// DealStatusPaymentChannelAllocatingLane is the status when we are making a lane for this channel
	DealStatusPaymentChannelAllocatingLane

	// DealStatusCancelling means we are cancelling an inprogress deal
	DealStatusCancelling

	// DealStatusCancelled means a deal has been cancelled
	DealStatusCancelled

	// DealStatusRetryLegacy means we're attempting the deal proposal for a second time using the legacy datatype
	DealStatusRetryLegacy

	// DealStatusWaitForAcceptanceLegacy means we're waiting to hear the results on the legacy protocol
	DealStatusWaitForAcceptanceLegacy

	// DealStatusClientWaitingForLastBlocks means that the provider has told
	// the client that all blocks were sent for the deal, and the client is
	// waiting for the last blocks to arrive. This should only happen when
	// the deal price per byte is zero (if it's not zero the provider asks
	// for final payment after sending the last blocks).
	DealStatusClientWaitingForLastBlocks

	// DealStatusPaymentChannelAddingInitialFunds means that a payment channel
	// exists from an earlier deal between client and provider, but we need
	// to add funds to the channel for this particular deal
	DealStatusPaymentChannelAddingInitialFunds

	// DealStatusErroring means that there was an error and we need to
	// do some cleanup before moving to the error state
	DealStatusErroring

	// DealStatusRejecting means that the deal was rejected and we need to do
	// some cleanup before moving to the rejected state
	DealStatusRejecting

	// DealStatusDealNotFoundCleanup means that the deal was not found and we
	// need to do some cleanup before moving to the not found state
	DealStatusDealNotFoundCleanup

	// DealStatusFinalizingBlockstore means that all blocks have been received,
	// and the blockstore is being finalized
	DealStatusFinalizingBlockstore
)

func (DealStatus) String 

func (s DealStatus) String() string

type Params 

type Params struct {
	Selector                CborGenCompatibleNode // V1
	PieceCID                *cid.Cid
	PricePerByte            abi.TokenAmount
	PaymentInterval         uint64 // when to request payment
	PaymentIntervalIncrease uint64
	UnsealPrice             abi.TokenAmount
}

Params are the parameters requested for a retrieval deal proposal

func NewParamsV1 

func NewParamsV1(pricePerByte abi.TokenAmount, paymentInterval uint64, paymentIntervalIncrease uint64, sel datamodel.Node, pieceCid *cid.Cid, unsealPrice abi.TokenAmount) (Params, error)

NewParamsV1 generates parameters for a retrieval deal, including a selector

func (Params) IntervalLowerBound 

func (p Params) IntervalLowerBound(currentInterval uint64) uint64

func (*Params) MarshalCBOR 

func (t *Params) MarshalCBOR(w io.Writer) error

func (Params) NextInterval 

func (p Params) NextInterval(fundsReceived abi.TokenAmount) uint64

NextInterval produces the maximum data that can be transferred before more payment is request

func (Params) OutstandingBalance 

func (p Params) OutstandingBalance(fundsReceived abi.TokenAmount, sent uint64, inFinalization bool) big.Int

OutstandingBalance produces the amount owed based on the deal params for the given transfer state and funds received

func (Params) SelectorSpecified 

func (p Params) SelectorSpecified() bool

func (*Params) UnmarshalCBOR 

func (t *Params) UnmarshalCBOR(r io.Reader) (err error)

type Query 

type Query struct {
	PayloadCID  cid.Cid // V0
	QueryParams         // V1
}

Query is a query to a given provider to determine information about a piece they may have available for retrieval

func NewQueryV1 

func NewQueryV1(payloadCID cid.Cid, pieceCID *cid.Cid) Query

NewQueryV1 creates a V1 query (which has an optional pieceCID)

func (*Query) MarshalCBOR 

func (t *Query) MarshalCBOR(w io.Writer) error

func (*Query) UnmarshalCBOR 

func (t *Query) UnmarshalCBOR(r io.Reader) (err error)

type QueryItemStatus 

type QueryItemStatus uint64

QueryItemStatus (V1) indicates whether the requested part of a piece (payload or selector) is available for retrieval 

const (
	// QueryItemAvailable indicates requested part of the piece is available to be
	// served
	QueryItemAvailable QueryItemStatus = iota

	// QueryItemUnavailable indicates the piece either does not contain the requested
	// item or it cannot be served
	QueryItemUnavailable

	// QueryItemUnknown indicates the provider cannot determine if the given item
	// is part of the requested piece (for example, if the piece is sealed and the
	// miner does not maintain a payload CID index)
	QueryItemUnknown
)

type QueryParams 

type QueryParams struct {
	PieceCID *cid.Cid // optional, query if miner has this cid in this piece. some miners may not be able to respond.

}

QueryParams - V1 - indicate what specific information about a piece that a retrieval client is interested in, as well as specific parameters the client is seeking for the retrieval deal

func (*QueryParams) MarshalCBOR 

func (t *QueryParams) MarshalCBOR(w io.Writer) error

func (*QueryParams) UnmarshalCBOR 

func (t *QueryParams) UnmarshalCBOR(r io.Reader) (err error)

type QueryResponse 

type QueryResponse struct {
	Status        QueryResponseStatus
	PieceCIDFound QueryItemStatus // V1 - if a PieceCID was requested, the result

	Size uint64 // Total size of piece in bytes

	PaymentAddress             address.Address // address to send funds to -- may be different than miner addr
	MinPricePerByte            abi.TokenAmount
	MaxPaymentInterval         uint64
	MaxPaymentIntervalIncrease uint64
	Message                    string
	UnsealPrice                abi.TokenAmount
}

QueryResponse is a miners response to a given retrieval query

func (*QueryResponse) MarshalCBOR 

func (t *QueryResponse) MarshalCBOR(w io.Writer) error

func (QueryResponse) PieceRetrievalPrice 

func (qr QueryResponse) PieceRetrievalPrice() abi.TokenAmount

PieceRetrievalPrice is the total price to retrieve the piece (size * MinPricePerByte + UnsealedPrice)

func (*QueryResponse) UnmarshalCBOR 

func (t *QueryResponse) UnmarshalCBOR(r io.Reader) (err error)

type QueryResponseStatus 

type QueryResponseStatus uint64

QueryResponseStatus indicates whether a queried piece is available 

const (
	// QueryResponseAvailable indicates a provider has a piece and is prepared to
	// return it
	QueryResponseAvailable QueryResponseStatus = iota

	// QueryResponseUnavailable indicates a provider either does not have or cannot
	// serve the queried piece to the client
	QueryResponseUnavailable

	// QueryResponseError indicates something went wrong generating a query response
	QueryResponseError
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.