The w3filecoin client for storacha.network
npm install @storacha/filecoin-clientThe w3filecoin client for https://storacha.network
The @storacha/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 storacha/specs/w3-filecoin.md and is not intended for storacha.network end users.
Install the package using npm:
``bash`
npm install @storacha/filecoin-client
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.
`js
import { Storefront } from '@storacha/filecoin-client'
const res = await Storefront.filecoinOffer(invocationConfig, content, piece)
`
`typescript`
function filecoinOffer(
conf: InvocationConfig,
content: Link, // Content CID
piece: Piece // Filecoin piece
): Promise
More information: InvocationConfig
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.
`js
import { Storefront } from '@storacha/filecoin-client'
const res = await Storefront.filecoinSubmit(invocationConfig, content, piece)
`
`typescript`
function filecoinSubmit(
conf: InvocationConfig,
content: Link, // Content CID
piece: Piece // Filecoin piece
): Promise
More information: InvocationConfig
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.
`js
import { Storefront } from '@storacha/filecoin-client'
const res = await Storefront.filecoinAccept(invocationConfig, content, piece)
`
`typescript`
function filecoinAccept(
conf: InvocationConfig,
content: Link, // Content CID
piece: Piece // Filecoin piece
): Promise
More information: InvocationConfig
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.
`js
import { Aggregator } from '@storacha/filecoin-client'
const res = await Aggregator.pieceOffer(invocationConfig, piece, group)
`
`typescript`
function pieceOffer(
conf: InvocationConfig,
piece: Piece, // Filecoin piece
group: string // Aggregate grouping with different criterium like storefront
): Promise
More information: InvocationConfig
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.
`js
import { Aggregator } from '@storacha/filecoin-client'
const res = await Aggregator.pieceAccept(invocationConfig, piece, group)
`
`typescript`
function pieceAccept(
conf: InvocationConfig,
piece: Piece, // Filecoin piece
group: string // Aggregate grouping with different criterium like storefront
): Promise
More information: InvocationConfig
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.
`js
import { Dealer } from '@storacha/filecoin-client'
const res = await Dealer.aggregateOffer(invocationConfig, aggregate, pieces)
`
`typescript`
function aggregateOffer(
conf: InvocationConfig,
aggregate: Piece, // Filecoin piece representing aggregate
pieces: Piece[] // Filecoin pieces part of the aggregate (sorted)
): Promise
More information: InvocationConfig
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.
`js
import { Dealer } from '@storacha/filecoin-client'
const res = await Dealer.aggregateAccept(invocationConfig, aggregate, pieces)
`
`typescript`
function aggregateAccept(
conf: InvocationConfig,
aggregate: Piece, // Filecoin piece representing aggregate
pieces: Piece[] // Filecoin pieces part of the aggregate (sorted)
): Promise
More information: InvocationConfig
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.
`js
import { DealTracker } from '@storacha/filecoin-client'
const add = await DealTracker.dealInfo(invocationConfig, piece)
`
`typescript`
function dealInfo(
conf: InvocationConfig,
piece: Piece // Filecoin piece to check
): Promise
More information: 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).audience
- The is the principal authority that the UCAN is delegated to.resource
- The (with field) points to a storage space.proofs` are a set of capability delegations that prove the issuer has the capability to perform the action. These might not be required.
- The
Feel free to join in. All welcome. Please open an issue!
Dual-licensed under MIT + Apache 2.0