Storacha Brings the Receipts

Let’s talk about paper trails. Or rather — the digital ones.

Not the most thrilling way to start a blog post, we know. But stick with us, because this is where things get interesting. At the heart of decentralized systems lies a fundamental question:

who did what, and when — and can we prove it?

In other words, it all comes down to trust. Or more accurately, the ability to verify so we don’t have to trust.

An audit trail removes that trust issue, right? If there’s an audit trail, you can account for actions. How do we do that though? By signing stuff. Yeah exactly, but instead of regular pen-on-paper signatures we use cryptographic signatures. Ooh fancy!

The best bit about cryptographic signatures is that you can’t forge them. Well, there’s an infinitesimally small chance you could generate a key that is the same as someone else’s, but it’s practically impossible, so forget that. Physical world signatures on the other hand are easily forged — it’s a well known fact, and yet, we still use them today! <insert this is fine fire dog meme> Anyway, I digress.

Asymmetric keys is how things work. It’s actually a key pair — a public key and a private key. You keep the private key erm, private and never show it to anyone. You sign a document (some bytes) with your private key and whoever receives the document can verify you signed it, using your public key. Got it? Sign with private, verify with public.

Deep diving a little — the input to the signing operation is the bytes of the document you’re signing as well as (and this is maybe obvious) your private key bytes. The output is some more bytes — the signature. For the verify operation the input is the signature bytes, the document bytes and (you guessed it) the public key bytes.

The cool thing about this process is that if the document gets changed you won’t be able to verify it, because the signature will be invalid — the signature will be for a different document — the one that was not changed. Likewise if the signature is changed, it can no longer be verified to have signed the document. Only the private key holder can create a signature for that particular version of the document, so you can infer that, at some point, the private key holder was in agreement with the intention of the document, or otherwise they wouldn’t have signed it.

Bam! Okay, signed documents 101 complete. Good job you!

At this point it may not surprise you to learn that at Storacha we literally sign everything. Sometimes just for LOLs. Seriously though, every request you make to the Storacha Network is signed by you. Any node on the network that receives that request will operate on it and send back a (yep that’s right) signed receipt. By the way, we call requests “invocations”, and we’ll refer to them as that from now on.

The receipt attests to work done. We haven’t quite got to verifiable compute yet but the receipt proves some node tried to do a thing and sent you back a result, that they signed. What’s more, we literally craft the audit trail by linking back to the original invocation from the receipt. We use the power of hash for this. Cryptographic hashes that is.

Don’t know what hashes are? Keep reading. A hashing function takes some bytes as it’s input (any number of bytes, pick a number, any number), and returns a fixed number of bytes that correspond to the input bytes. Correspond? Yes, correspond because if you give that same function the same set of bytes again, you’ll get the same bytes back, and importantly, no other set of input bytes will produce the same output.

Excellent, so reciepts link back to invocations by their hash so you can trace back from receipt to invocation or forward from invocation to receipt. Trail riding. Love it.

One quick note on the verifiable compute thing. Typically Storacha’s invocations are not compute intensive things and the correctness of the result is easily verifiable. For example, the most frequent invocation is “store this data for me” where the result in the receipt is a URL where you can put the data. You will immediately verify that is a good URL when you send a HTTP PUT request to it that succeeds. Eventually you’ll receive another signed receipt that says the data has been accepted and is available. You can then easily verify that fact by making a request to our network to retrieve the data. We use hashes to address data, and we avoid having to verify that a hash was generated correctly by not trusting anyone to generate it for you. So when you say “store this data for me”, you actually just send the hash of the data you want to store. The receipient can then verify it received the intended data and whoever accesses it can verify it is un-altered when it is retrieved.

Oftentimes tasks need to happen asynchronously, either because they just take a long time and it’s not practical to wait for their completion or because they are dependant on other tasks. Receipts allow you to communicate additional async tasks that need to happen, and results can be blocked on another task completing. Since we hash address everything, it’s super easy to block a result on a dependant task, you just reference the task’s hash, and specify the selector for the value e.g. .out.ok.site

We build up a paper trail of invocations and receipts like this:

(invocation) ← (invocation receipt) → (async task) ← (async task receipt) → ...

Where each item is signed and content addressed and links forward or backward to other tasks or receipts. This is all UCAN tech by the way, and we use it extensively in the Storacha Network stack.

Lets do examples! Here’s what the upload paper trail looks like:

1. Client → Service — blob/add invocation (asking to store some data)
2. Service → Client — blob/add receipt with async tasks for blob/allocate, http/put & blob/accept (allocation task is already complete - this was invoked by the service on the storage node due to receive the data. The HTTP PUT task is for the client to perform, and the accept task is blocked on the service receiving a receipt for the HTTP PUT task)
3. Client → Service — http/put receipt (after it has performed the task)
4. Service → Client — blob/accept receipt (after service has verified with storage node that upload was received)

…and here’s our Filecoin aggregation pipeline:

1. Client → Service — filecoin/offer invocation (offering a piece of data to the pipeline)
2. Service → Client — filecoin/offer receipt with async tasks for filecoin/submit and filecoin/accept (submit task completes when the piece gets submitted to the aggregation process and the accept task completes when the piece has been accepted into an on-chain Filecoin deal)
3. Servce → Client — filecoin/submit receipt with async task for piece/offer to the aggregation service (the service invokes the aggregator to get the piece into an aggregate)
4. Aggregator → Service — piece/offer receipt with async task for piece/accept (accept task indicates the piece made it into a new aggregate)
5. Aggregator → Service — piece/accept receipt with async task for aggregate/offer (communicating the proof of aggregation. The aggregator service invokes the dealer service to get the aggregate into a Filecoin deal)
6. Dealer → Aggregator — aggregate/offer receipt with async task for aggregate/accept (accept task completes when the aggregate has been stored by at least one Filecoin Storage Provider)
7. Dealer → Aggregator — aggregate/accept receipt with details of the deal(s) for the offered piece.
8. Service → Client — filecoin/accept receipt with details of the aggregate inclusion proof and the deal(s) for the offered piece.

You can read more about our filecoin pipeline here. Note how from the first invocation you can either follow the chain all the way to aggregate/accept or you can skip to the end by requesting the filecoin/accept receipt! Pretty cool huh!

Those are the two biggest paper trails we got going in Storacha right now. They are epic, we know. Paper trails exist for every operation in the Storacha Network, providing a verifiable chain of events that minimises trust. Hopefully this chain of words has convinced you that paper trails, and by virtue, UCANs are awesome things and we hope you’ve learned a little about how Storacha works in the process!