⁂
web3.storage

The w3filecoin client for https://web3.storage

About

The @web3-storage/filecoin-client package provides the "low level" client API to make data uploaded with the w3up platform available in Filecoin Storage providers. It is based on web3-storage/specs/w3-filecoin.md and is not intended for web3.storage end users.

Install

Install the package using npm:

npm install @web3-storage/filecoin-client
Copy

Usage

Storefront.filecoinOffer

The filecoin/offer task can be executed to request storing a content piece in Filecoin. It issues a signed receipt of the execution result.

A receipt for successful execution will contain an effect, linking to a filecoin/submit task that will complete asynchronously.

Otherwise the task is failed and the receipt will contain details of the reason behind the failure.

import { Storefront } from '@web3-storage/filecoin-client'

const res = await Storefront.filecoinOffer(
  invocationConfig,
  content,
  piece
)
Copy

function filecoinOffer(
  conf: InvocationConfig,
  content: Link, // Content CID
  piece: Piece, // Filecoin piece
): Promise<Receipt>
Copy

More information: InvocationConfig

Storefront.filecoinSubmit

The filecoin/submit task is an effect linked from successful execution of a filecoin/offer task, it is executed to issue a receipt for the success or failure of the task.

A receipt for successful execution indicates that the offered piece has been submitted to the pipeline. In this case the receipt will contain an effect, linking to a piece/offer task that will complete asynchronously.

Otherwise the task is failed and the receipt will contain details of the reason behind the failure.

import { Storefront } from '@web3-storage/filecoin-client'

const res = await Storefront.filecoinSubmit(
  invocationConfig,
  content,
  piece
)
Copy

function filecoinSubmit(
  conf: InvocationConfig,
  content: Link, // Content CID
  piece: Piece, // Filecoin piece
): Promise<Receipt>
Copy

More information: InvocationConfig

Storefront.filecoinAccept

The filecoin/accept task is an effect linked from successful execution of a filecoin/offer task, it is executed to issue a receipt for the success or failure of the task.

A receipt for successful execution indicates that the offered piece has been accepted in a Filecoin deal. In this case the receipt will contain proofs that the piece was included in an aggregate and deal.

Otherwise the task is failed and the receipt will contain details of the reason behind the failure.

import { Storefront } from '@web3-storage/filecoin-client'

const res = await Storefront.filecoinAccept(
  invocationConfig,
  content,
  piece
)
Copy

function filecoinAccept(
  conf: InvocationConfig,
  content: Link, // Content CID
  piece: Piece, // Filecoin piece
): Promise<Receipt>
Copy

More information: InvocationConfig

Aggregator.pieceOffer

The piece/offer task can be executed to request that a piece be aggregated for inclusion in an upcoming an Filecoin deal. It issues a signed receipt of the execution result. It is also an effect linked from successful execution of a filecoin/submit task.

A receipt for successful execution will contain an effect, linking to a piece/accept task that will complete asynchronously.

Otherwise the task is failed and the receipt will contain details of the reason behind the failure.

import { Aggregator } from '@web3-storage/filecoin-client'

const res = await Aggregator.pieceOffer(
  invocationConfig,
  piece,
  group
)
Copy

function pieceOffer(
  conf: InvocationConfig,
  piece: Piece, // Filecoin piece
  group: string, // Aggregate grouping with different criterium like storefront
): Promise<Receipt>
Copy

More information: InvocationConfig

Aggregator.pieceAccept

The piece/accept task is an effect linked from successful execution of a piece/offer task, it is executed to issue a receipt for the success or failure of the task.

A receipt for successful execution indicates that the offered piece was included in an aggregate. In this case the receipt will contain the aggregate piece CID and a proof that the piece was included in the aggregate. It also includes an effect, linking to an aggregate/offer task that will complete asynchronously.

Otherwise the task is failed and the receipt will contain details of the reason behind the failure.

import { Aggregator } from '@web3-storage/filecoin-client'

const res = await Aggregator.pieceAccept(
  invocationConfig,
  piece,
  group
)
Copy

function pieceAccept(
  conf: InvocationConfig,
  piece: Piece, // Filecoin piece
  group: string, // Aggregate grouping with different criterium like storefront
): Promise<Receipt>
Copy

More information: InvocationConfig

Dealer.aggregateOffer

The aggregate/offer task can be executed to request an aggregate be added to a deal with a Storage Provider. It issues a signed receipt of the execution result. It is also an effect linked from successful execution of a piece/accept task.

A receipt for successful execution will contain an effect, linking to an aggregate/accept task that will complete asynchronously.

Otherwise the task is failed and the receipt will contain details of the reason behind the failure.

import { Dealer } from '@web3-storage/filecoin-client'

const res = await Dealer.aggregateOffer(
  invocationConfig,
  aggregate,
  pieces
)
Copy

function aggregateOffer(
  conf: InvocationConfig,
  aggregate: Piece, // Filecoin piece representing aggregate
  pieces: Piece[],  // Filecoin pieces part of the aggregate (sorted)
): Promise<Receipt>
Copy

More information: InvocationConfig

Dealer.aggregateAccept

The aggregate/accept task is an effect linked from successful execution of a aggregate/offer task, it is executed to issue a receipt for the success or failure of the task.

A receipt for successful execution indicates that an aggregate has been accepted for inclusion in a Filecoin deal. In this case the receipt will contain proofs that the piece was included in an aggregate and deal.

Otherwise the task is failed and the receipt will contain details of the reason behind the failure, as well as multiple effects, linking to piece/offer tasks that will retry valid pieces and complete asynchronously.

import { Dealer } from '@web3-storage/filecoin-client'

const res = await Dealer.aggregateAccept(
  invocationConfig,
  aggregate,
  pieces
)
Copy

function aggregateAccept(
  conf: InvocationConfig,
  aggregate: Piece, // Filecoin piece representing aggregate
  pieces: Piece[],  // Filecoin pieces part of the aggregate (sorted)
): Promise<Receipt>
Copy

More information: InvocationConfig

DealTracker.dealInfo

The deal/info task can be executed to request deal information for a given piece. It issues a signed receipt of the execution result.

A receipt for successful execution will contain details of deals the provided piece CID is currently active in.

Otherwise the task is failed and the receipt will contain details of the reason behind the failure.

import { DealTracker } from '@web3-storage/filecoin-client'

const add = await DealTracker.dealInfo(
  invocationConfig,
  piece
)
Copy

function dealInfo(
  conf: InvocationConfig,
  piece: Piece, // Filecoin piece to check
): Promise<Receipt>
Copy

More information: InvocationConfig

Types

InvocationConfig

This is the configuration for the UCAN invocation. It is an object with issuer, audience, resource and proofs:

• The issuer is the signing authority that is issuing the UCAN invocation(s).
• The audience is the principal authority that the UCAN is delegated to.
• The resource (with field) points to a storage space.
• The proofs are a set of capability delegations that prove the issuer has the capability to perform the action. These might not be required.

Contributing

Feel free to join in. All welcome. Please open an issue!

License

Dual-licensed under MIT + Apache 2.0