2024-04: Data onramp with Filecoin Bridges

https://docs.google.com/document/d/1vjSUCF3JNEE1dFNs-SGLwQcXJR0pg0q3FzQwvlW7nvc

Authors: @nicola, @zenground0
Demo (soon): https://github.com/ZenGround0/onramp-contracts

Goals

The goals of this projects are:

• Exporting Filecoin services to other chains: Data can be stored from other relevant L1s, L2s and other private services into Filecoin.
• Storing small data without effort: Smaller than sector (and piece!) data can be stored into Filecoin with ease.

MVP with Message Passing Bridges (Axelar, Celer, etc)

Participants

• Client: A user that wants to store data.
• Agent: An agent that helps the user store the data on their behalf (optional).
• Buffer: A service that stores data before it gets stored into Filecoin (optional).
• SP: The storage provider that is offering storage services.
• MarketOffchain: The market where agents advertise deals and storage providers commit to them.
• MinerActor: The Filecoin actor that ensures that data is being stored and proven.
• FilecoinBridgeActor: An actor on L1 that sends messages to the bridge to speak to a L2/other chain.
• Bridge: A cross-chain bridge that bridges messages from Filecoin into other systems.

Protocols

Deal and Data Delegation protocols (optional)

This set of protocols are designed to make sure that the User can delegate their data and client making to third parties.

Note the client can also be the buffer and the agent, for simplicity and more modularity we divide their roles here.

sequenceDiagram
autonumber
participant Client
participant Agent
participant Buffer
participant MarketOffchain
participant SP
participant MinerActor
participant FilecoinBridgeActor
participant Bridge

alt Deal delegation
Client -->> Agent: EnageAgent (deal)
end
alt Buffer delegation
Agent -->> Buffer: StoreDeal (deal)
Client -->> Buffer: UploadDealData (piece)
end

Filecoin storage bridge (mandatory)

This set of protocols make the agent advertise the deal so that storage providers can commit to store it, store it into Filecoin and then using the bridge, show that the data has been stored.

This protocol only guarantees that the data has been stored, not that it is continuosly stored. (This is an equivalent to an HTTP POST)

sequenceDiagram
autonumber
participant Client
participant Agent
participant Buffer
participant MarketOffchain
participant SP
participant MinerActor
participant FilecoinBridgeActor
participant Bridge
alt Piece advertise
Agent ->> MarketOffchain: AdvertiseDeal(deal)
end
alt Piece selection
SP -->> MarketOffchain: GetDeals ()
SP ->> MarketOffchain: PickDeals()
SP -->> Buffer: GetPiece (deal)
SP ->> MarketOffchain: CommitDeals (deal), lock X
end
alt Filecoin Storage
SP -->> SP: generateCommD(CommD) -> PoDSI
SP ->> MarketOffchain: UpdateDeal(PoDSI)
SP ->> MinerActor: ProveSector()
end
opt Bridge confirmation
SP ->> FilecoinBridgeActor: Stored(podsi.root)
FilecoinBridgeActor ->> Bridge: AnnounceDealStored(deal)
Bridge ->> MarketOffchain: DealStored(deal)
end

Report faults from Filecoin (optional)

This protocol makes sure that if the data is not stored, the agent can read Filecoin L1 and report this back into the offchain market.

sequenceDiagram
autonumber
participant Client
participant Agent
participant Buffer
participant MarketOffchain
participant SP
participant MinerActor
participant FilecoinBridgeActor
participant Bridge

opt Optional: Agent reporting failed deals
Agent ->> FilecoinBridgeActor: Complain(podsi.root) -> proof
FilecoinBridgeActor ->> Bridge: Complaint
Bridge ->> MarketOffchain: ComplaintSucceeded
end

Project management

Next steps

• MVP
  • (P1) Document more in detail each method, interface and data structure
  • (P1) MVP in code
  • (P2) Change the interface from Bridge to Oracles for future compatibility
  • (P4) Figure out if Axelar can be used without message passing
• Team
  • (P0) Engage with existing onramp designers

sequenceDiagram
  Client ->> Agent: Sign (deal)
Agent ->> Buffer: Store (deal)
Client ->> Buffer: Upload (piece)
Agent ->> MarketOffchain: Advertise(deal)
SP -->> MarketOffchain: GetDeals ()
SP ->> MarketOffchain: PickDeals()
SP ->> Buffer: GetPiece (deal)

SP ->> MarketOffchain: Commit (deal), lock X
SP -->> SP: generate(CommD)
SP ->> MarketOffchain: PoDSI
SP ->> MinerActor: ProveSector()
alt if the SP doesn't ProveSector 
Agent ->> FilecoinOracle: RequestSectorState(podsi.root) -> proof 
Agent ->> MarketOffchain: Complain(commit, proof)
end

sequenceDiagram
Client ->> MarketOnchain: lock tokens
Client ->> Agent: Sign (deal)
Agent ->> Buffer: Store (deal)
Client ->> Buffer: Upload (piece)
Agent ->> MarketOffchain: Advertise(deal)
SP -->> MarketOffchain: GetDeals ()
SP ->> MarketOffchain: PickDeals()
SP ->> Buffer: GetPiece (deal)

SP ->> MarketOffchain: Commit (deal)
SP ->> MarketOnchain: lock X, commitment
SP -->> SP: generate(CommD)
SP ->> MarketOffchain: PoDSI
SP ->> MinerActor: ProveSector()
alt if the SP doesn't ProveSector 
Agent ->> MarketOnchain: Complain(commit)
end

Design decisions and learning

Where do operations happen?

• Payments (most likely L2)
• Market (L2)
• Slashing (L2)

Who verifies the deal of the correctness of the data structure?

• Publicly verifiable deal: the layer 2
• Privately verifiable deal: the client

We decided that deals are publicly verifiable deals

Bridges vs Oracle
If we could replace the message passing (Axelar) with an oracle (Axiom), then any small chain/l2 not supported by Axelar will work.

Ideally we design for oracles and not for bridges.