deal

package
v0.1.1 Latest Latest
Warning

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

 Go to latest Published: Jan 11, 2022 License: BSD-3-Clause Imports: 19 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var DefaultPaymentInterval = uint64(1 << 20)

DefaultPaymentInterval is the baseline interval, set to 1Mb if the miner does not explicitly set it otherwise

View Source 
var DefaultPaymentIntervalIncrease = uint64(1 << 20)

DefaultPaymentIntervalIncrease is the amount interval increases on each payment, set to to 1Mb if the miner does not explicitly set it otherwise

View Source 
var DefaultPricePerByte = abi.NewTokenAmount(2)

DefaultPricePerByte is the charge per byte retrieved if the miner does not specifically set it

View Source 
var ProposalUndefined = Proposal{}

ProposalUndefined is an undefined deal proposal

View Source 
var ResponseUndefined = Response{}

ResponseUndefined is an undefined deal response

View Source 
var Statuses = map[Status]string{
	StatusNew:                              "DealStatusNew",
	StatusUnsealing:                        "DealStatusUnsealing",
	StatusUnsealed:                         "DealStatusUnsealed",
	StatusWaitForAcceptance:                "DealStatusWaitForAcceptance",
	StatusPaymentChannelCreating:           "DealStatusPaymentChannelCreating",
	StatusPaymentChannelAddingFunds:        "DealStatusPaymentChannelAddingFunds",
	StatusAccepted:                         "DealStatusAccepted",
	StatusFundsNeededUnseal:                "DealStatusFundsNeededUnseal",
	StatusFailing:                          "DealStatusFailing",
	StatusRejected:                         "DealStatusRejected",
	StatusFundsNeeded:                      "DealStatusFundsNeeded",
	StatusSendFunds:                        "DealStatusSendFunds",
	StatusSendFundsLastPayment:             "DealStatusSendFundsLastPayment",
	StatusOngoing:                          "DealStatusOngoing",
	StatusFundsNeededLastPayment:           "DealStatusFundsNeededLastPayment",
	StatusCompleted:                        "DealStatusCompleted",
	StatusDealNotFound:                     "DealStatusDealNotFound",
	StatusErrored:                          "DealStatusErrored",
	StatusBlocksComplete:                   "DealStatusBlocksComplete",
	StatusFinalizing:                       "DealStatusFinalizing",
	StatusCompleting:                       "DealStatusCompleting",
	StatusCheckComplete:                    "DealStatusCheckComplete",
	StatusCheckFunds:                       "DealStatusCheckFunds",
	StatusInsufficientFunds:                "DealStatusInsufficientFunds",
	StatusPaymentChannelAllocatingLane:     "DealStatusPaymentChannelAllocatingLane",
	StatusCancelling:                       "DealStatusCancelling",
	StatusCancelled:                        "DealStatusCancelled",
	StatusClientWaitingForLastBlocks:       "DealStatusWaitingForLastBlocks",
	StatusPaymentChannelAddingInitialFunds: "DealStatusPaymentChannelAddingInitialFunds",
}

Statuses maps deal status to a human readable representation

Functions

func NewShortfallError 

func NewShortfallError(shortfall abi.TokenAmount) error

NewShortfallError returns a new error indicating a shortfall of funds

Types

type ClientState 

type ClientState struct {
	Proposal
	StoreID              *multistore.StoreID
	ChannelID            datatransfer.ChannelID
	LastPaymentRequested bool
	AllBlocksReceived    bool
	TotalFunds           abi.TokenAmount
	ClientWallet         address.Address
	MinerWallet          address.Address
	PaymentInfo          *PaymentInfo
	Status               Status
	Sender               peer.ID
	TotalReceived        uint64
	Message              string
	BytesPaidFor         uint64
	CurrentInterval      uint64
	PaymentRequested     abi.TokenAmount
	FundsSpent           abi.TokenAmount
	UnsealFundsPaid      abi.TokenAmount
	WaitMsgCID           *cid.Cid // the CID of any message the client deal is waiting for
	VoucherShortfall     abi.TokenAmount
}

ClientState is the current state of a deal from the point of view of a retrieval client

func (*ClientState) MarshalCBOR 

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

func (*ClientState) NextInterval 

func (cs *ClientState) NextInterval() uint64

NextInterval calculates the next payment interval for the current params

func (*ClientState) UnmarshalCBOR 

func (t *ClientState) UnmarshalCBOR(r io.Reader) error

type ID 

type ID uint64

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

func (ID) String 

func (d ID) String() string

type Mgr 

type Mgr struct {
	// contains filtered or unexported fields
}

Mgr is a deal manager implementation which keeps track of offers and ongoing deal balances which may encompass multiple transfers.

func NewManager 

func NewManager(price abi.TokenAmount) *Mgr

NewManager creates a new deal manager instance for a given default provider price the provider price will define the baseline price per byte at which the provider node will serve deals

func (*Mgr) FindOfferByCid 

func (mgr *Mgr) FindOfferByCid(k cid.Cid) (Offer, error)

FindOfferByCid returns an offer if available for a given cid or an error if none if found

func (*Mgr) GetFundsForCid 

func (mgr *Mgr) GetFundsForCid(k cid.Cid) abi.TokenAmount

GetFundsForCid returns a token amount available for a given cid or 0

func (*Mgr) GetOfferForCid 

func (mgr *Mgr) GetOfferForCid(k cid.Cid) Offer

GetOfferForCid returns a specific offer for the given content ID. If no offer has been registered it will return a default offer based on the default provier price.

func (*Mgr) RemoveOffer 

func (mgr *Mgr) RemoveOffer(k cid.Cid) error

RemoveOffer clear the offer for a given root CID for examplie if the offer is expired

func (*Mgr) SetFundsForCid 

func (mgr *Mgr) SetFundsForCid(k cid.Cid, funds abi.TokenAmount)

SetFundsForCid saves a token amount for a given root CID it will overried any existing amount

func (*Mgr) SetOfferForCid 

func (mgr *Mgr) SetOfferForCid(k cid.Cid, offer Offer) error

SetOfferForCid stores an offer for a given content ID

type Offer 

type Offer struct {
	ID                         string
	PeerAddr                   []byte
	PayloadCID                 cid.Cid
	Size                       uint64
	PaymentAddress             address.Address
	MinPricePerByte            abi.TokenAmount
	MaxPaymentInterval         uint64
	MaxPaymentIntervalIncrease uint64
	UnsealPrice                abi.TokenAmount
}

Offer is the conditions under which a provider is willing to approve a transfer @TODO: maybe should have an associated selector?

func (Offer) AddrInfo 

func (o Offer) AddrInfo() (*peer.AddrInfo, error)

AddrInfo returns the peer info to connect with the provider of this offer

func (Offer) AsQueryResponse 

func (o Offer) AsQueryResponse() QueryResponse

AsQueryResponse retrofits an Offer into a QueryResponse message

func (*Offer) MarshalCBOR 

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

func (Offer) RetrievalPrice 

func (o Offer) RetrievalPrice() abi.TokenAmount

RetrievalPrice is the total price to retrieve the content from this offer

func (*Offer) UnmarshalCBOR 

func (t *Offer) UnmarshalCBOR(r io.Reader) error

type Params 

type Params struct {
	Selector                *cbg.Deferred
	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 NewParams 

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

NewParams 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(currentInterval uint64) uint64

NextInterval calculates the next interval increasing the current interval with the given parameters

func (Params) SelectorSpecified 

func (p Params) SelectorSpecified() bool

SelectorSpecified returns whether we decoded any serialized selector

func (*Params) UnmarshalCBOR 

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

type Payment 

type Payment struct {
	ID             ID
	PaymentChannel address.Address
	PaymentVoucher *paych.SignedVoucher
}

Payment is a payment for an in progress retrieval deal

func (*Payment) MarshalCBOR 

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

func (*Payment) Type 

func (dr *Payment) Type() datatransfer.TypeIdentifier

Type method makes DealPayment usable as a voucher

func (*Payment) UnmarshalCBOR 

func (t *Payment) UnmarshalCBOR(r io.Reader) error

type PaymentInfo 

type PaymentInfo struct {
	PayCh address.Address
	Lane  uint64
}

PaymentInfo is the payment channel and lane for a deal, once it is setup

func (*PaymentInfo) MarshalCBOR 

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

func (*PaymentInfo) UnmarshalCBOR 

func (t *PaymentInfo) UnmarshalCBOR(r io.Reader) error

type Proposal 

type Proposal struct {
	PayloadCID cid.Cid
	ID         ID
	Params
}

Proposal is a proposal for a new retrieval deal

func ProposalFromVoucher 

func ProposalFromVoucher(voucher datatransfer.Voucher) (*Proposal, bool)

ProposalFromVoucher casts a data transfer voucher into a deal Proposal

func (*Proposal) MarshalCBOR 

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

func (*Proposal) Type 

func (dp *Proposal) Type() datatransfer.TypeIdentifier

Type method makes DealProposal usable as a voucher

func (*Proposal) UnmarshalCBOR 

func (t *Proposal) UnmarshalCBOR(r io.Reader) error

type ProviderDealIdentifier 

type ProviderDealIdentifier struct {
	Receiver peer.ID
	DealID   ID
}

ProviderDealIdentifier is a value that uniquely identifies a deal

func (ProviderDealIdentifier) String 

func (p ProviderDealIdentifier) String() string

type ProviderState 

type ProviderState struct {
	Proposal
	StoreID         multistore.StoreID
	ChannelID       datatransfer.ChannelID
	Status          Status
	Receiver        peer.ID
	TotalSent       uint64
	FundsReceived   abi.TokenAmount
	Message         string
	CurrentInterval uint64
	// Added PayCh field so we can get the reference to the payment channel
	// in fsm event subscriber
	PayCh *address.Address
}

ProviderState is the current state of a deal from the point of view of a retrieval provider

func (ProviderState) Identifier 

func (ps ProviderState) Identifier() ProviderDealIdentifier

Identifier provides a unique id for this provider deal

func (*ProviderState) IntervalLowerBound 

func (ps *ProviderState) IntervalLowerBound() uint64

func (*ProviderState) MarshalCBOR 

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

func (*ProviderState) NextInterval 

func (ps *ProviderState) NextInterval() uint64

func (*ProviderState) UnmarshalCBOR 

func (t *ProviderState) UnmarshalCBOR(r io.Reader) error

type Query 

type Query struct {
	PayloadCID cid.Cid
	QueryParams
}

Query is a query to a given provider to determine information about a piece they may have available for retrieval If we don't have a specific provider in mind we can use gossip Hop to find one

func (*Query) MarshalCBOR 

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

func (*Query) UnmarshalCBOR 

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

type QueryItemStatus 

type QueryItemStatus uint64

QueryItemStatus 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.
	Selector *cbg.Deferred
}

QueryParams - 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 NewQueryParams 

func NewQueryParams(sel ipld.Node) (QueryParams, error)

NewQueryParams formats QueryParams into a struct ready to be encoded for transport

func (*QueryParams) MarshalCBOR 

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

func (*QueryParams) UnmarshalCBOR 

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

type QueryResponse 

type QueryResponse struct {
	Status                     QueryResponseStatus
	PieceCIDFound              QueryItemStatus // 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) 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
)

type Response 

type Response struct {
	Status Status
	ID     ID

	// payment required to proceed
	PaymentOwed abi.TokenAmount

	Message string
}

Response is a response to a retrieval deal proposal

func ResponseFromVoucherResult 

func ResponseFromVoucherResult(vres datatransfer.VoucherResult) (*Response, bool)

ResponseFromVoucherResult casts a data transfer voucher result into a deal Response

func (*Response) MarshalCBOR 

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

func (*Response) Type 

func (dr *Response) Type() datatransfer.TypeIdentifier

Type method makes DealResponse usable as a voucher result

func (*Response) UnmarshalCBOR 

func (t *Response) UnmarshalCBOR(r io.Reader) error

type ShortfallError 

type ShortfallError struct {
	// contains filtered or unexported fields
}

ShortfallError is an error that indicates a short fall of funds

func (ShortfallError) Error 

func (se ShortfallError) Error() string

func (ShortfallError) Shortfall 

func (se ShortfallError) Shortfall() abi.TokenAmount

Shortfall returns the numerical value of the shortfall

type Status 

type Status uint64

Status is the status of a retrieval deal returned by a provider in a DealResponse 

const (
	// StatusNew is a deal that nothing has happened with yet
	StatusNew Status = iota

	// StatusUnsealing means the provider is unsealing data
	StatusUnsealing

	// StatusUnsealed means the provider has finished unsealing data
	StatusUnsealed

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

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

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

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

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

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

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

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

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

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

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

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

	// StatusCompleted indicates a deal is complete
	StatusCompleted

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

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

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

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

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

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

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

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

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

	// StatusCancelling means we are cancelling an inprogress deal
	StatusCancelling

	// StatusCancelled means a deal has been cancelled
	StatusCancelled

	// StatusClientWaitingForLastBlocks 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).
	StatusClientWaitingForLastBlocks

	// StatusPaymentChannelAddingInitialFunds 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
	StatusPaymentChannelAddingInitialFunds
)

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.