boostly

README

Boostly

Filecoin Boost Client Library in Go

Boostly is a lightweight and efficient Go client library for Filecoin Boost. This library simplifies the process of integrating and interacting programmatically with Boost APIs, tailored specifically for Go developers.

Features

• Deal Making: Seamlessly initiate deals with a Filecoin storage provider.
• Deal Status Check: Query and monitor the status of your deals in real-time.
• Retrieval Transports Query: Fetch retrieval transports offered by a Boost SP.

Installation

go get github.com/filecoin-shipyard/boostly@latest

Status

🚧 This repository is under active development. 🚧

Please be aware that while we strive to keep the master branch stable, breaking changes may be introduced as we push forward. We recommend using released versions for production systems and always checking the release notes before updating.

Documentation

For detailed usage and integration guidance, please refer to godoc documentation.

Resources

• Boost Filecoin Official Site

Contribution

Contributions are welcome! Please see the CONTRIBUTING.md for more details.

License

This project is licensed under the MIT and Apache 2.0 Licenses - see the LICENSE.md file for details.

Documentation

Index

• Constants
• type DealProposal
  • func (t *DealProposal) MarshalCBOR(w io.Writer) error
  • func (t *DealProposal) UnmarshalCBOR(r io.Reader) (err error)
• type DealProposalResponse
  • func ProposeDeal(ctx context.Context, h host.Host, spID peer.ID, proposal DealProposal) (*DealProposalResponse, error)
  • func (t *DealProposalResponse) MarshalCBOR(w io.Writer) error
  • func (t *DealProposalResponse) UnmarshalCBOR(r io.Reader) (err error)
• type DealStatus
  • func (t *DealStatus) MarshalCBOR(w io.Writer) error
  • func (t *DealStatus) UnmarshalCBOR(r io.Reader) (err error)
• type DealStatusRequest
  • func (t *DealStatusRequest) MarshalCBOR(w io.Writer) error
  • func (t *DealStatusRequest) UnmarshalCBOR(r io.Reader) (err error)
• type DealStatusResponse
  • func GetDealStatus(ctx context.Context, h host.Host, id peer.ID, dealUUID uuid.UUID, ...) (*DealStatusResponse, error)
  • func (t *DealStatusResponse) MarshalCBOR(w io.Writer) error
  • func (t *DealStatusResponse) UnmarshalCBOR(r io.Reader) (err error)
• type HttpRequest
• type StorageAsk
  • func (t *StorageAsk) MarshalCBOR(w io.Writer) error
  • func (t *StorageAsk) UnmarshalCBOR(r io.Reader) (err error)
• type Transfer
  • func (t *Transfer) MarshalCBOR(w io.Writer) error
  • func (t *Transfer) UnmarshalCBOR(r io.Reader) (err error)
• type TransferState
• type TransferStatus
• type TransportDealInfo
• type TransportEvent
• type TransportsQueryResponse
  • func QueryTransports(ctx context.Context, h host.Host, id peer.ID) (*TransportsQueryResponse, error)

Constants

const (
	FilRetrievalTransportsProtocol_1_0_0 = "/fil/retrieval/transports/1.0.0"
)

const (
	FilStorageMarketProtocol_1_2_0 = "/fil/storage/mk/1.2.0"
)

const FilStorageStatusProtocol_1_2_0 = "/fil/storage/status/1.2.0"

const (
	FilStorageTransferProtocol_1_0_0 = "/fil/storage/transfer/1.0.0"
)

Types

type DealProposal

type DealProposal struct {
	DealUUID           uuid.UUID
	IsOffline          bool
	ClientDealProposal market.ClientDealProposal
	DealDataRoot       cid.Cid
	Transfer           Transfer // Transfer params will be the zero value if this is an offline deal
	RemoveUnsealedCopy bool
	SkipIPNIAnnounce   bool
}

func (*DealProposal) MarshalCBOR

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

func (*DealProposal) UnmarshalCBOR

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

type DealProposalResponse

type DealProposalResponse struct {
	Accepted bool
	// Message is the reason the deal proposal was rejected. It is empty if
	// the deal was accepted.
	Message string
}

func ProposeDeal

func ProposeDeal(ctx context.Context, h host.Host, spID peer.ID, proposal DealProposal) (*DealProposalResponse, error)

func (*DealProposalResponse) MarshalCBOR

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

func (*DealProposalResponse) UnmarshalCBOR

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

type DealStatus

type DealStatus struct {
	// Error is non-empty if the deal is in the error state
	Error string
	// Status is a string corresponding to a deal checkpoint
	Status string
	// SealingStatus is the sealing status reported by lotus miner
	SealingStatus string
	// Proposal is the deal proposal
	Proposal market.DealProposal
	// SignedProposalCid is the cid of the client deal proposal + signature
	SignedProposalCid cid.Cid
	// PublishCid is the cid of the Publish message sent on chain, if the deal
	// has reached the publish stage
	PublishCid *cid.Cid
	// ChainDealID is the id of the deal in chain state
	ChainDealID abi.DealID
}

func (*DealStatus) MarshalCBOR

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

func (*DealStatus) UnmarshalCBOR

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

type DealStatusRequest

type DealStatusRequest struct {
	DealUUID  uuid.UUID
	Signature crypto.Signature
}

DealStatusRequest is sent to get the current state of a deal from a storage provider

func (*DealStatusRequest) MarshalCBOR

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

func (*DealStatusRequest) UnmarshalCBOR

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

type DealStatusResponse

type DealStatusResponse struct {
	DealUUID uuid.UUID
	// Error is non-empty if there is an error getting the deal status
	// (eg invalid request signature)
	Error          string
	DealStatus     *DealStatus
	IsOffline      bool
	TransferSize   uint64
	NBytesReceived uint64
}

DealStatusResponse is the current state of a deal

func GetDealStatus

func GetDealStatus(ctx context.Context, h host.Host, id peer.ID, dealUUID uuid.UUID, signer func(context.Context, []byte) (*crypto.Signature, error)) (*DealStatusResponse, error)

func (*DealStatusResponse) MarshalCBOR

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

func (*DealStatusResponse) UnmarshalCBOR

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

type HttpRequest

type HttpRequest struct {
	// URL can be
	// - an http URL:
	//   "https://example.com/path"
	// - a libp2p URL:
	//   "libp2p:///ip4/104.131.131.82/tcp/4001/ipfs/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ"
	//   Must include a Peer ID
	URL string
	// Headers are the HTTP headers that are sent as part of the request,
	// eg "Authorization"
	Headers map[string]string
}

HttpRequest has parameters for an HTTP transfer

type StorageAsk

type StorageAsk struct {
	// Price per GiB / Epoch
	Price         abi.TokenAmount
	VerifiedPrice abi.TokenAmount

	MinPieceSize abi.PaddedPieceSize
	MaxPieceSize abi.PaddedPieceSize
	Miner        address.Address
}

StorageAsk defines the parameters by which a miner will choose to accept or reject a deal. Note: making a storage deal proposal which matches the miner's ask is a precondition, but not sufficient to ensure the deal is accepted (the storage provider may run its own decision logic).

func (*StorageAsk) MarshalCBOR

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

func (*StorageAsk) UnmarshalCBOR

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

type Transfer

type Transfer struct {
	// The type of transfer eg "http"
	Type string
	// An optional ID that can be supplied by the client to identify the deal
	ClientID string
	// A byte array containing marshalled data specific to the transfer type
	// eg a JSON encoded struct { URL: "<url>", Headers: {...} }
	Params []byte
	// The size of the data transferred in bytes
	Size uint64
}

Transfer has the parameters for a data transfer

func (*Transfer) MarshalCBOR

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

func (*Transfer) UnmarshalCBOR

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

type TransferState

type TransferState struct {
	ID         string
	LocalAddr  string
	RemoteAddr string
	Status     TransferStatus
	Sent       uint64
	Received   uint64
	Message    string
	PayloadCid cid.Cid
}

TransferState describes a transfer's current state

type TransferStatus

type TransferStatus string

TransferStatus describes the status of a transfer (started, completed etc)

const (
	// TransferStatusStarted is set when the transfer starts
	TransferStatusStarted TransferStatus = "TransferStatusStarted"
	// TransferStatusRestarted is set when the transfer restarts after previously starting
	TransferStatusRestarted TransferStatus = "TransferStatusRestarted"
	TransferStatusOngoing   TransferStatus = "TransferStatusOngoing"
	TransferStatusCompleted TransferStatus = "TransferStatusCompleted"
	TransferStatusFailed    TransferStatus = "TransferStatusFailed"
)

type TransportDealInfo

type TransportDealInfo struct {
	OutputFile string
	DealUuid   uuid.UUID
	DealSize   int64
}

TransportDealInfo has parameters for a transfer to be executed

type TransportEvent

type TransportEvent struct {
	NBytesReceived int64
	Error          error
}

TransportEvent is fired as a transfer progresses

type TransportsQueryResponse

type TransportsQueryResponse struct {
	Protocols []struct {
		Name      string                `json:"name,omitempty"`
		Addresses []multiaddr.Multiaddr `json:"addresses,omitempty"`
	} `json:"protocols,omitempty"`
}

func QueryTransports

func QueryTransports(ctx context.Context, h host.Host, id peer.ID) (*TransportsQueryResponse, error)