Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

feat: add spec for publically verifiable timestamps for UCANs with drand #27

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

feat: add spec for publically verifiable timestamps for UCANs with drand #27

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
21312e5
feat: add spec for publically verifiable timestamps for UCANs with Drand
Jan 3, 2023
5891d50
chore: appease linter
Jan 3, 2023
c1d963e
fix: require round number ofr unchained randomness chains
Jan 3, 2023
5de7a7a
fix: formatting
Jan 3, 2023
34f425c
fix: formating
Jan 3, 2023
68a1147
fix: appease linter
Jan 3, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .github/workflows/words-to-ignore.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,9 @@ URIs
interop
permissionless
stateful
drand
bilinear
mainnet

# actually correct
reimagine
Expand Down
39 changes: 39 additions & 0 deletions Publicly Verifiable UCAN Timestamps.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# Publicly verifiable timestamps for UCANs with Drand

![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square)

## Editors

- [Alan Shaw](https://github.com/alanshaw), [DAG House](https://dag.house/)

## Authors

- [Alan Shaw](https://github.com/alanshaw), [DAG House](https://dag.house/)

# Abstract

Being able to verify that a UCAN invocation happened within a time window gives us some assurances.

Enabling public verification that a UCAN was created on or after a specific time also allows services to be open and transparent.

[Drand](https://drand.love/) is a distributed randomness beacon. Drand nodes produce collective, publicly verifiable, unbiased, unpredictable random values at fixed intervals using bilinear pairings and threshold cryptography.

By including a drand randomness round in a signed UCAN, anyone can prove that it was created _on_ or _after_ that randomness round was generated. There’s a number of uses for this, an example is allowing the web3.storage service to account for `store/add` invocations, publicly proving that we were asked to store data within a given time frame.

Services may choose to reject UCANs with timestamps that do not correspond to a recent randomness round. In this case it's reasonable to assume that the UCAN was _probably_ not generated long after the included randomness round. There is no incentive to do so if it is likely to be rejected on receipt.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I want to better understand this. Is the idea that service will reject invocation even if it still valid (has not expired yet) if it has been issued before some timestamp ?

If so what does drand provides over regular nbf / exp time bounds in UCANs
https://github.com/ucan-wg/spec/#322-time-bounds

E.g. service could deny requests unless nbf is specified and is with-in some time bound. It could also deny service unless exp is specified and is with-in desired time bound. More concretely service could demand that invocation be valid within 24h.

Only difference that I can see here, that unlike drand it would allow issuing a UCAN that will be valid in the future, which seems like pro rather than con, although perhaps there are cases where you want to prevent this ?

If so it might be a good idea to call those out explicitly.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

also cc @ribasushi as he had mentioned desire to do something along those lines & might be able to provide extra context.

Copy link

@mikeal mikeal Jan 5, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don’t think the point here is to replace the timestamp functionality that already works within the trust model of the delegations.

A certifiable method is most useful for reconciling duplicate, similar, or conflicting transactions that happen to be UCANs.

The upload interface has a wonderful lock free mutex we write into, so we don’t have to worry about two people trying to do the same thing, that can both succeed easily.

However, what if an FVM contract wants to award the “first” uploader of the content a reward? DRAND is an easy way to reconcile who the winner would be from two claims.

As we get into mutations and as our internal system gets more complex, will we find distributed system challenges where we have to reconcile UCANs from different actors and this provides a simple and expedient means of reconciliation without any prior knowledge that the transactions would need to be reconciled in this way. If we wait until we have specific definitions for these conflicts, we will no longer be in a position to place information in them that could provide a means of reconciliation. Let’s just add it to everything now so that we won’t ever have this problem :)

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

However, what if an FVM contract wants to award the “first” uploader of the content a reward? DRAND is an easy way to reconcile who the winner would be from two claims.

But you can always pretend to be the older invocation, but you can’t pretend to be the newer, so I’m not sure this helps


## Specification

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).

1. Issuers **must** include a drand randomness round in UCAN [`nnc`](https://github.com/ucan-wg/spec#323-nonce) field.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Any reason to require it in nnc as opposed to fct ? I'm bit hesitant to overloading nnc and it would also prevent issuing two UCANs with same time stamp.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No reason, in fact I'd prefer to put it there now you suggest it :)


1. Issuers **should** include the drand randomness _round number_ in the [`nb`](https://github.com/ucan-wg/spec#241-nb-non-normative-fields) field.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this intentionally vague about how to include this in nb? i.e. under what key (e.g. nb.drand or nb.time)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What's the motivation of this should vs not including it at all? If we can agree on a place to store it in nnc or fct, do we really need to strongly encourage it in nb too?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@gobengo the proposal is to put the actual random value in nnc and the round number in nb. Not intentional under which key in nb - needs specifying (I just forgot).

If fct is more appropriate place for any/all of this then we should put it there! I think it probably a better place seeing as this is not really a nonce but a timestamp.


If included, the round number **must** correspond to the randomness value in the `nnc` field. This field is **required** for ["unchained" drand randomness chains](https://drand.love/blog/2022/02/21/multi-frequency-support-and-timelock-encryption-capabilities/#unchained-randomness-timed-encryption).
Comment on lines +31 to +33
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If it is optional, I would move forward not including it for now. We can just spec as "should" and not implement I guess, but I would favour keeping things less complex until there is a reason where we would want to use "unchained" drand randomness chains


1. Issuers **may** include the "chain hash" of the drand randomness chain in the [`nb`](https://github.com/ucan-wg/spec#241-nb-non-normative-fields) field.

The chain hash uniquely identifies the drand chain the randomness value was taken from, if it is different from the mainnet chain operated by the League of Entropy. If omitted, it is assumed to be `8990e7a9aaed2ffed73dbd7092123d6f289930540d7651336225dc172e51b2ce`.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not sure the above "chain" can be reasonably assumed to be "LoE mainnet"
@yiannisbot @jsoares can you chime in?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

According to https://api.drand.sh/info hash, is the chain hash and also this is the only chain right now according to https://api.drand.sh/chains.

Maybe I should just call it the default/original?

Copy link

@jsoares jsoares Jan 14, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is, indeed, the LoE mainnet chain. However, note that the new high-frequency "chain" (not actually a chain) is planned to go live on 22 February. While there's no schedule for Filecoin consensus to transition to the new chain or for the old chain to be deprecated, that will eventually happen (I'd imagine the former in late '23 and the latter in '24, but I don't speak for the drand, Filecoin, or LoE). Plus, the new chain gives you higher resolution, in case that seems useful.

tl;dr: depending on the timeline, you may or may not want to replace this with the new chain id

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As @jsoares says this chainhash is the LoE mainnet one and will continue to be valid until at least the end of 2023. We expect that Filecoin will switch to the new drand network (and chain hash) within the next couple of quarters. We'll make announcements and we'll have a docs page with references to the chain hashes in existence.

@alanshaw how easy will it be to change the hash to the new one we'll have next week? The new network setup has been postponed to March 1st, so we can provide the new chain hash shortly. We expect that this new one will be longer-lasting than the existing one.

cc: @AnomalRoil @CluEleSsUK


1. Audiences **may** reject a received UCAN if the randomness of the current/recent round does not match the randomness included in the UCAN.