DAOIP-3: Attestations for DAOs

[thelastjosh]

Discuss design, implementation, and changes to DAOIP-3 Attestations for DAOs.

[thelastjosh]

Right now, the attestationIssuers is a field we are adding to daoURI that expects an array included inside the JSON returned by daoURI. Instead, would it make sense to replace that array with a separate endpoint, i.e. rename attestationIssuers to attestationIssuersURI? I imagine an attestationIssuersURI might want to have separate (perhaps automated) logic that governs it, rather than having to go through the logic for editing daoURI. For example, you may want to automatically add a trusted attestationIssuer every time a specific event is emitted during a contract interaction between a DAO and an on-chain service, i.e. "I agree to adopt your service".

[frm]

For the past few months, Avenue has been integrating with Govrn through this DAOIP. Currently, contributions made on Govrn show up on Avenue. As an example: https://avenue.place/@m contains several contributions, all implemented through this standard.

Avenue also allows minting contributions automatically on Govrn, which are then resynced to Avenue. However, we realised that we needed a common definition of a contribution to get true value of this integration.

While implementing, we also found some technical changes that should be done to make the data-sharing process viable.

Technical Limitations

• We’re missing pagination - Personally, I was already aware of this and had thought about it before, but didn’t want to add too many technical details to the implementation and limit initial adoption. Given Avenue and Govrn are spearheading this, adding pagination seems straightforward and easy.
• Support contribution schema pre-fetching - Currently, this limitation leaves the API unusable if we want to provide a good experience for the user. Right now the API response merely points to a contribution URI, not making any details available. This is the current scenario:
  • Avenue requests information from Govrn (1 request)
  • Govrn returns the list of attestations/contributions for the user
  • Since each item doesn’t include any contribution details, to make it relevant to the user profile Avenue needs to implement a custom integration with Govrn and consume Govrn’s API (N requests)
  • (Outside of the scope of the EIP but still relevant since it’s a common scenario) Govrn doesn’t include any details in their implementation, only pointers to a third-party off-chain storage like IPFS.
  • Avenue needs to consume information from IPFS for each detail (N requests).

Without support for pre-fetching (i.e. including the contribution details in the original request), the API becomes unbearably slow to make it truly useful. Currently at Avenue we cache every contribution. We are also aware that Govrn does the same. Contributions that are made available on-chain (with their metadata off-chain) are replicated 3x: on Avenue’s database, on Govrn’s database and on-chain (or on IPFS).

However, even if we ended up implementing pre-fetching in it’s current state, it would still be difficult to use without defining a base schema for a contribution and (in the future) for its attestations.

I suggest we keep the technical issues far from this discussion and let engineers at Avenue and Govrn tackle them. These are just two simple technical limitations, without a lot of room for subjectivity. Instead, focus on adding a contribution schema to the standard.

Suggestion for Contribution schema

Before moving to an attestation framework, we need to understand what we're attesting to and further develop the standard. We're starting by defining a contribution schema that can be easily extended by anyone. This process will very much be trial-and-error until the schema stabilises. For that reason, Avenue and Govrn are working closely together to try out the integration as the DAO-IP updates. We started by figuring out what the smallest common ground is and we can later extend the definition as more people and tools join and find more use cases. Regardless, ideally the schema should be as slim as possible, avoiding a large number of fields.

With that in mind, and for the sake of kicking off the conversation, the first suggestion is defining a contribution as having the following fields

• provider - the protocol responsible for hosting the contribution on-chain (e.g. Govrn).
• providerUid - internal UID attributed by provider, needs to be unique for the given provider (e.g. the token ID if the contribution is implemented as an NFT)
• issuer - the platform, if any, where the contribution happened. As an example, a contribution can happen an Avenue and issued by Avenue on Govrn.
• issuerUid - same as providerUid but for the issuer.
• name or title - short name or title attributed to that contribution by the participants.
• description - Description attributed to that contribution by the participants.
• contributors - list of addresses of all participants in that contribution, including the current user. This causes
• dateOfEngagement - date in which the contribution originally happened. This allows for a common understanding of the timeline of contributions without relying on these contributions living on-chain.
• external (optional) - key that allows any platform to extend the contribution with their own data. This should be an object of objects with each first-level being a different provider. As an example:

{
  "external": {
    "avenue": {
      "outcomeId": 1,
      "authorId": 2,
      "organizationId": 3
    },
    "govrn": {
      "daoId": 1,
      "bannerUrl": "https://..."
    }
  }
}

This field allows each platform to extend the schema with specific metadata. As an example, a third-party could backlink a contribution to Avenue or Govrn or even integrate with them directly. It’s essential to have such a field that enables custom integrations between tools.

The following fields are security-related:

• providerSignature - sign(provider, providerUid, issuer, issuerUid, name, description, dateOfEngagement) by the provider. Ensures that the contribution hasn’t been tampered with. The idea behind this is to allow for contributions to be broadcast between different platforms or users, which can always be altered by a malicious party. Note the exclusion of the external field, the idea behind it is that the external field can always be extended by subsequent platforms and updated with each new version.
• issuerSignature - same as the providerSignature, but for the issuer.
• contributorSignatures - array of sign(provider, providerUid, issuer, issuerUid, name, description, dateOfEngagement) made by each individual contributor. This is needs to be included to allow contributions with multiple participants. It acts as a step of consent, with each participant signing the set of fields that make up the contribution and thus ensuring they’ve accept to be included in the contribution.

The Final Schema

None of these fields need to be kept on-chain - some even shouldn’t. However, for any provider that implements this DAOIP API endpoint, they should be provided. An example response of this endpoint would be:

{
   "@context":"http://www.daostar.org/schemas",
   "type":"arrayAttestation",
   "issuer":"<Avenue's issuerURI>",
   "member":{
      "type":"ENS",
      "id":"josh.eth"
   },
   "organizations":[
      {
         "expiration":"<ISO-datetime>",
         "attesterURI":"<DAOStar One's membersURI>",
         "name":"DAOstar One",
         "daoURI":"<DAOStar One's daoURI, following EIP-4824>"
      }
   ],
   "contributions":[
      {
         "type":"contribution",
         "referenceURI?":"<URI reference to the tweet on Govrn's platform or IPFS or other storage>",
         "reference?":{
            "provider":"govrn",
            "providerURI":"<Govrn's URI>",
            "providerId":123,
            "providerSignature":"<Govrn's signature>",
            "issuer":"avenue",
            "issuerURI":"<Avenue's URI>",
            "issuerId":"abc123",
            "issuerSignature":"<Avenue's signature>",
            "title":"Took part in a DAOStar Voyager meeting",
            "description":"Meeting happened on 2022-04-12",
            "contributors":[
               "<josh's address>",
               "<mendes's address>",
               "<aaron's address>"
            ],
            "contributorSignatures":[
               "<josh's signature>",
               "<mendes's signature>",
               "<aaron's signature>"
            ],
            "dateOfEngagement":"2022-04-12T17:00:00Z",
            "external":{
               "avenue":{
                  "outcomeId":1,
                  "authorId":2,
                  "organizationId":3
               },
               "govrn":{
                  "daoId":1,
                  "bannerUrl":"https://..."
               }
            }
         }
      }
   ]
}

Next Steps

We’re opening this up for discussion for now, while trying to keep the schema as simple as possible and without relying on specific taxonomies or DSLs to describe a contribution. Ideally, we’d gather feedback around the fields, especially the security-related ones. In the meantime, Avenue and Govrn will be implementing this iteration and posting results soon.

[frm]

After checking with the Govrn team, we realised the following:

• the provider* and issuer* fields should be swapped in terms of naming .
• the providerSignature field isn't actually needed and the issuer fields fit a more specific use case. We're downgrading them to be used in the external field as tools see fit.

There was also a version key missing.

New iteration of the v2 contribution schema:

{
   "@context":"http://www.daostar.org/schemas",
   "type":"arrayAttestation",
   "issuer":"<Avenue's issuerURI>",
   "member":{
      "type":"ENS",
      "id":"josh.eth"
   },
   "organizations":[
      {
         "expiration":"<ISO-datetime>",
         "attesterURI":"<DAOStar One's membersURI>",
         "name":"DAOstar One",
         "daoURI":"<DAOStar One's daoURI, following EIP-4824>"
      }
   ],
   "contributions":[
      {
         "type":"contribution",
         "referenceURI?":"<URI reference to the tweet on Govrn's platform or IPFS or other storage>",
         "reference?":{
            "version": 2,
            "issuer":"govrn",
            "issuerURI":"<Govrn's URI>",
            "issuerId":123,
            "title":"Took part in a DAOStar Voyager meeting",
            "description":"Meeting happened on 2022-04-12",
            "contributors":[
               "<josh's address>",
               "<mendes's address>",
               "<aaron's address>"
            ],
            "contributorSignatures":[
               "<josh's signature>",
               "<mendes's signature>",
               "<aaron's signature>"
            ],
            "dateOfEngagement":"2022-04-12T17:00:00Z",
            "external":{
               "avenue":{
                  "outcomeId":1,
                  "authorId":2,
                  "organizationId":3,
                  "signature":"<Avenue's signature>"
               },
               "govrn":{
                  "daoId":1,
                  "bannerUrl":"https://..."
               }
            }
         }
      }
   ]
}

[wallyfresh]

To contextualize the value of the contributions and start getting feedback from users, I believe that we need to add a Category field:

Drop down options for the Category field

• Documentation
• Content Creation
• Process
• Repository
• Mentorship
• Discourse
• Other

This will also help DAOs to understand where most of contributions are taking place.

[thelastjosh]

In discussion with @bryce at EAS: would it be useful to incorporate the uid field that exists in all EAS attestations, which is just a b32 hash of the entire data, using their same process? This might make attestations published here more interoperable with EAS attestations. Bryce can speak more to why that might be a good idea.

[wallyfresh]

After chatting with @frm and Aaron, for the v1 contributions schema we are not including the category field with a drop-down list since it will require us to reconcile when users use the 'others' field but use different naming convention to describe similar contributions. Additionally, we want to wait and monitor how users leverage the contribution schema.

[thelastjosh]

Hi folks, just a heads up that I shipped a major new version of the standard (see #156), with the following changes:

1. interoperated with the verifiable credential specification; added new rationale
2. changed member to subject, memberAttestationsURI to subjectAttestationsURI to make the schema more widely applicable / analogous to verifiable credentials
3. changed issuerURI to just issuer, since issuerURI is effectively "issuer" in the VC specification
4. changed expiration to expirationDate, following the VC specification
5. adjusted the "id" to conform to the VC specification, though we've retained a "type" field in the credentialSubject object
6. changed attestationIssuer field to attestationIssuerURI field; added new schema for attestationIssuerURI
7. changed capitalization of all types to TypeName from typeName to match schema.org examples
8. created a new generic Attestation type, added issuerURI and attestationURI to it
9. added a new schema for attestation types (moved over from regulatory interop), and removed extensions section
10. added a new schema for contributions
11. added apiURI to support OpenAPI interop
12. added a signature section
13. added a use-case for publishing daoURI as an attestation through a service such as EAS

[thelastjosh]

From a call today, answers to some questions:

1. Where are Attestation Type JSONs published? The standard does not specify how to publish attestation types. However, one way to deal with this in the meantime is to just assume that new attestation types are published as additional DAOIPs, and that DAOstar will (eventually) publish a computable readable version of these schemas. So, for example, the regulatory interoperability standard will define a bunch of new attestation types.

2. How does an issuer who is already publishing attestations through EAS go about adopting DAOIP-3? For example, LXDAO already has a daoURI, and is separately publishing attestations through EAS for their Fairsharing app. First, they (or we) need to deploy a schema on EAS that is compliant with DAOIP-3. Two problems: first, it is unclear, right now, whether EAS allows nesting of fields as JSON does, and second, EAS schemas cannot be easily extended, i.e. you can't just add new fields in an EAS attestation—so this makes it slightly difficult to publish a JSON with a bunch of attestations all together, though you can assume that certain fields are arrays and just load a bunch of data through that field. Let's suppose that these problems are fixed, and that there is a complete schema that exists on EAS of the form

{
	"@context": ["https://daostar.org/schemas", "https://www.w3.org/ns/credentials/v2"],
	"type": ["VerifiableCredential", "Attestation", "<the type of the attestation if any>"],
	"issuer": "<URI returning data conforming to the Attestation Issuer JSON-LD Schema>",
	"attestationURI": "<the URI or API request from which someone can obtain the attestation>",
	"expirationDate": "<ISO DateTime>",
	"credentialSubject": {
		"<mySubjectProperty>": "<mySubjectValue>"
	}
}

LXDAO/Fairsharing needs to publish issuer such that the resolved address should return a JSON following the Attestation Issuer JSON in the standard. We can make this easier by creating a schema on EAS conforming to the Attestation Issuer JSON, but the issuer field still needs to point at the actual hosted data (whether on IPFS or somewhere else), not something hosted by EAS. It's up to LXDAO/Fairsharing to decide whether the issuer is LXDAO the organization or Fairsharing the app. Probably it makes more sense for LXDAO to do this, since it is the larger / more durable entity?

For the attestationURI field, LXDAO wants to point this at the actual EAS attestation, BUT an EAS attestation encodes the actual data, so you cannot point attestationURI at the raw EAS attestation—it needs to be decoded first. This is okay for now since most EAS users get the decoded data directly from EAS's servers. For example, this is how Fairsharing currently does it. So in this case, attestationURI should point directly to EAS's servers / endpoints. Note that this does not require us to change the issuer from LXDAO/Fairsharing to EAS. EAS is just additional infrastructure for hosting attestation data, but the "trust" is with LXDAO/Fairsharing.

Most of the data falls within credentialSubject. Let's go through an example. Here is a typical attestation from LXDAO, visible here. The only tricky thing about filling this out is deciding what field counts as the ``credential subject''.

{
	"@context": ["http://www.daostar.org/schemas", "https://www.w3.org/ns/credentials/v2"],
	"type": ["VerifiableCredential", "Attestation", "MembershipAttestation"],
	"issuer": "<URI returning data conforming to the Attestation Issuer JSON-LD Schema>",
	"attestationURI": "<the URI or API request from which someone can obtain the attestation>",
	"expirationDate": "<ISO DateTime>",
	"credentialSubject": {
		"type": "EthereumAddress",
		"id": "0x8ada9BB0982a269d232186013d39C37e21655046",
		"contributionId": "0x7de3000a3ad70fe308f34e088890ff562bb9f364b0e09a6c27cd6b16c1f347ae",
		"details": "??",
		"contributionType": "0x8ada9BB0982a269d232186013d39C37e21655046",
		"proof": "0x8ada9BB0982a269d232186013d39C37e21655046",
		"startDate": "0x8ada9BB0982a269d232186013d39C37e21655046",
		"endDate": "0x8ada9BB0982a269d232186013d39C37e21655046",
		"tokenAmount": "0x8ada9BB0982a269d232186013d39C37e21655046",
		"extended": "0x8ada9BB0982a269d232186013d39C37e21655046",
	}
}

To adopt, LXDAO should deploy a new schema that looks like the above. Effectively, because EAS doesn't allow nesting, the schema on EAS should effectively just have a "@context", "type", "issuer", "attestationURI", "expirationDate", and "credentialSubject" field. This does make it a little bit harder to index (i.e. you can't use EAS to differentiate the schemas, because the key differences are all nested within credentialSubject). @bryce it would be nice if EAS supported schemas with nesting.

Note that we had to rename "type" in LXDAO's original schema to "contributionType", since "type" is reserved in DAOstar's schemas (here, to refer to the type of credentialSubject, i.e. whether it's an Ethereum address, a DID address, etc.).

3. What is the minimum that an issuer needs to do to count as "adopting" the standard?

TBD!

Some to-dos: additional EAS schemas to deploy

1. For base adoption of daoURI
2. Attestation Issuer schema
3. Definitely more that I'm missing atm

[amanwithwings]

@thelastjosh, from DAOIP-3: "...note the mandatory inclusion of an expirationDate field on every attestation as well as attestationURI, which is the URI or request through which someone can reproduce the attestation. ".

If we are talking about a URI that points to a specific attestation, that URI wouldn't be available until after the attestation is made, right? Or does attestationURI here correspond to a broader location (say if it is an attestation through EAS that uses a schema defined by Fairsharing. Then the attestationsURI could be the link to the schema and not the particular attestation in question)?

[amanwithwings]

@crazyyuan, @mike, is it safe to say that EAS does support nesting in some sense if the input of a field is set to an array?

The schema in the picture: https://optimism-goerli-bedrock.easscan.org/schema/view/0xc57e76eb1ef07cc577da25bdccac94f022201bb9b39157467822f65cd050366f