---
# System prepended metadata

title: w3filecoin <-> Spade

---

# w3filecoin <-> Spade

## Background

[w3filecoin] is the filecoin pipeline for w3up platform. This pipeline acts on new CAR files that are stored by applications/users into w3up. As CARs come in the pipeline, they are registered as `cargo` that is filling up a `ferry`. Once a `ferry` has enough accumulated size to fit a Filecoin deal, it is closed and marked as ready to make it to a deal.

[spade] is a filecoin broker that facilitates the storage of CAR files into filecoin storage providers. It can be seen as a marketplace.

## Architecture

### w3filecoin

![](https://i.imgur.com/Xcw253c.jpg)

### w3filecoin integration with spade

Spade enables w3up to get stored CAR files into Filecoin deals without all the complexity involved with establishing the deal.

The end goal of this integration should rely on an UCAN protocol to achieve full verifiability of Filecoin deals from user uploads. This protocol is being defined in [web3-storage/specs#51](https://github.com/web3-storage/specs/pull/51)

For w3up MVP we should look into an initial end-to-end milestone without all the UCAN story in place.

Spade team requires that tenants provide a design based on pull API rather than providing tenants a push based API. To achieve this, `w3filecoin` should expose an API endpoint like `https://filecoin.web3.storage/new-ferry` that Spade can call once they are ready to fulfill a deal for `w3up`.

In case `w3filecoin` already has a ferry ready to go, it will return a JSON response with format:

```json
{
    "id": "ferryIdentifier0",
    "cars": [
        {
            "cid": "bag...",
            "size": 110101,
            "md5": "md5...",
            "commP": "commP...",
            "url": "https://.../bag(...).car"
        }
    ]
}
```

If there is not ferry ready to go, `w3filecoin` will return 404.

Notes for discussion:
- In this first milestone, we can put a proxy in between w3filecoin and Spade so that we can get the UCAN protocol in place until it goes upstream to Spade
- Preferred pull method (by Spade team) is fine in a non UCAN world, however it does not look natural flow from the UCANTO based APIs we have been writing so far.
    - in UCANTO based APIs we rely on RPC calls, where in this case we would design a protocol `filecoin/*` where we would ask Spade to `filecoin/add` a given Set of CAR files, Spade would generate a receipt for this invocation and later on invoke `filecoin/deal` when a deal is achieved.
    - We can have `w3filecoin` return a CAR file with a UCAN, from which Spade would create a receipt signed by them, as well as a UCAN when deal is performed
- ...

[w3filecoin]: https://github.com/web3-storage/w3filecoin
[spade]: https://spade.storage