Hypercerts: Recognizing and Rewarding Impact – ATProto Implementation

Share your project
1

Hi all, excited to share some of what we’ve been building and to introduce hypercerts to the ATProto community.

Where we started

The hypercerts project began at Protocol Labs with a simple goal: improve how we fund public goods. Many of the contributions society relies on most—open-source software, scientific R&D, and ecological regeneration—remain underfunded because their value is hard to see, coordinate around, and reward.

What are hypercerts

Hypercerts address this by serving as digital impact certificates. At their core, they capture structured claims about impactful work: who did what, when, and where. These claims can be enriched with additional evidence such as reports, measurements, and expert or community judgment. Funding mechanisms—grants, milestone payments, bounties, and retroactive rewards—can then be built on top. In this way, hypercerts form an open, shared, decentralized data layer for impact funding.

Switching to ATProto

Over the past months, we’ve been exploring ATProto as the infrastructure for this data layer. By now, we are convinced it’s the right foundation to build on:

  • Like posting on social media, value creators publish structured claims about their work.

  • Like replies, multiple evaluators can attach structured assessments.

  • Over time, projects accumulate a durable track record—made possible by the persistent, portable identifiers that ATProto provides.

Together, this enables a legible, interoperable impact graph that funding platforms can use.

What this unlocks

For projects and individual contributors, the goal is simple: remove as much friction from bureaucratic grant applications and other funding mechanisms as possible. Make it effortless to show your work and tap into (novel) funding mechanisms that reward the value you create.

For funders, the goal is equally straightforward: reduce the cost of due diligence, see the full context of a project’s work, enable better coordination, and allocate resources with greater confidence and transparency.

What we’ve built and experimented with so far

Applications being built on top

Hypercerts is a protocol to allow multiple funding platforms to use the same schemas and data. We’re currently collaborating with Ma Earth and GainForest to build crowdfunding and collective funding platforms for regenerative land projects. These are our real-world testbeds for demonstrating how funding on hypercerts can work end-to-end.

We are excited to be here

We’d love to hear your thoughts, questions, feedback, pointers, etc. And we’re happy to share more about our work and learn from this community as we continue building.

If you want to dive deeper, here’s a recent blog post outlining our approach: https://hypercerts.leaflet.pub/3m6mnb2riz22o

14 Likes
Representing groups and other shared resources in ATProto
PDS Implementation - DAO PDS via Internet Computer
2

Welcome @holke.xyz

I found your Hypercerts account and write up

The multi-user collab work is very interesting! One of the things we talked about in Montreal is how to have different network services.

(The private data stuff goes into detail around maybe having a PrivateDataServer entry in the DID doc)

Right now if I read this currently an account would need to be on an SDS in order for this to work? That is, if I have a self hosted PDS and I login to your app can I participate? Or do I need an account on the SDS

There are also details on an alternate pattern where you create a community DID, @bnewbold.net wrote this up

What are you looking for right now? How can we help?

3 Likes
3

Hey @bmann.ca! Thanks for the reply. I’m working with @holke.xyz and others on Hypercerts.

You can try out the SDS by logging into https://sds-demo.test.certified.app/ via any PDS, self-hosted or otherwise – that’s how it’s designed to work and that’s how we’ve been testing it so far. We decided to keep the SDS purely for hosting shared repos, but theoretically it could also host individual users as well.

Here is a Loom video demonstrating the above (also credits to @bitbeckers.bsky.social who has done some of the heavily lifting on the SDS): Demonstrating a Shared Data Server for Collaborative Repositories 📂 | Loom

Please note that this is all still in the prototype phase – it seems to work great for us so far, but even in a hypothetical future where the community was 100% on board with the design, it would need some cleanup before being submitted upstream. In particular, packages/sds currently duplicates a bunch of code from packages/pds, so I expect we would need to refactor away that duplication in order to provide a clean diff.

Ah, that’s super helpful thanks! We’ve gone for a hybrid approach quite similar to what’s described in the last section of that post:

  1. Organization handles have the SDS hostname as the suffix, just like it already works with regular user handles and PDS hostnames. However I do like the idea of hierarchical namespaces described in the “Namespace IDs (NSIDs)” section.
  2. Organization profile data is stored as records (including but not limited to app.bsky.actor.profile) within that organization repository.

One question we have is regarding the entryway. We were hoping to deploy one so that in the future we could host PDSen (PDS’s? what’s the plural? :sweat_smile:) in multiple geographic regions, but have users who sign up via one of those[1] receive a shorter cleaner handle which doesn’t include the region in the domain suffix. However, my understanding is that it’s currently closed source. Is that correct, and is there any possibility it might be open sourced later? If not, are there any other ways of achieving the same thing?

[1] Note that we will always support use of Hypercerts from any PDS; we just want to offer the option of creating an account on one of the PDS we host.

4

Very interesting!

It’s highly unlikely that bsky will take this upstream. You should prepare to host this as a fork.

This is why Bryan’s write up suggests “community accounts” - same as other accounts, but set up to be managed by multiple other accounts, while not losing any of the flexibility of base ATProto accounts. I’m trying to figure out if that’s what you’ve done.

I logged in and created an account.

I can browse it https://atproto-browser.vercel.app/at/atproto.sds-eu-west4.test.certified.app

But when I try and use it to login somewhere, I can’t. I think what you’d maybe need to do is actually chain authentication? That is, I got to login with a community account, it bounces me to the SDS server, I auth there with the account that has access, then it bounces back with a session for the community account. But that gets back to … these accounts should probably just be “regular” accounts?

Can this SDS account also migrate to (I guess, other SDS servers), or is it trapped on that one?

There is a DID doc. Hmm. Yeah, the more I look at this, I think the shared management of a community account should just be done in the background with auth – having these slightly different accounts is going to have compatibility issues.

Yes, this is just a native property of ATProto accounts - you get a handle by default, but can map any domain to it. Since there is a DID doc, I would expect to be able to map a custom domain name to it.

@baileytownsend.dev has been working on a gateway implementation. Don’t think the bsky one will be OSS any time soon.

And yes, for smooth UX at scale, having a PDS that people can sign up for immediately is a good idea.

Geographic regions is probably overkill to start with, but it’s also not that hard to run a PDS. There is a bunch of extra auth forwarding stuff with the entryway that in your scenario could be quite a headache.

5

Good to know – any chance you could share the reasons why it’s unlikely? Would be helpful to understand in case there are ways we could try to avoid blockers.

Yes that’s pretty much what we’ve done. It’s just a lightweight extension of normal repos which introduces simple access control for multiple users.

Right – that’s by design. It’s a shared access repository, not a new identity for authentication. It’s very similar to how GitHub and several other platforms support the creation and management of organizations to which users can be granted different levels of access. When you create a GitHub org, that doesn’t mean you can now log in as the org itself. From the perspective of best practices in operational security, it’s generally better to require every user to have to log in using their own personal account, since logging in via an organization-wide account would need to bypass all governance mechanisms and obfuscate audit trails.

The way it works is that when you do your regular PDS login via OAuth, you get a JWT which proves your identity. This is then passed to the SDS in the XRPC call, so the SDS is able to a) verify the user’s identity and b) check in its local access control database whether the user is permitted to perform that operation on that shared repo.

From a developer perspective, this requires minimal changes over making a normal XRPC call to a PDS. The only difference is that you’re sending the call to a different server.

We haven’t implemented that yet, but I think it could work largely in the same way as normal user account migration does. Off the top of my head, I can imagine three different routes:

  1. self-custodied recovery keys (my understanding is that the servers support these for UIs to take advantage of, but they are not offered on Bluesky account creation, or at least not by default, right? I don’t remember being offered them when creating my Bluesky account)
  2. server-side migration based on governance policies, e.g. if the organisation has 5 members, it could require at least 3 to cooperate and request migration before authorising it
  3. recovery key sharding, achieving a kind of hybrid of the above two

The first of these would be closest to the existing mechanism (perhaps even identical), but would allow a single user holding the recovery keys to migrate the organisation elsewhere, which is not ideal in many organisations.

The second would be nicely convenient in terms of setting / maintaining governance policies as organisation membership changes over time, but depends on the SDS being alive and cooperative to facilitate a migration, which is not ideal either.

The third is the best of both worlds in terms of operational security, but would require rotating shards if any of the org admins change, which might be difficult to achieve without UX friction.

Which compatibility issues do you have in mind? So far we’ve been delighted to find that everything relating to shared repos has worked seamlessly out of the box with the rest of ATProto.

Granted, of course shared repos only work on a PDS which has been extended with the extra SDS functionality, but I’m doubtful it’s possible to implement shared access to data in a secure manner (in particular not requiring users to share identities and credentials) without changing the PDS code. And of course the intention would be to expand the number of PDS instances with this SDS functionality over time, facilitating migration.

Right. We didn’t test custom domain names for these yet, but based on what I know about how that works I can’t immediately think of any reason why it shouldn’t already work.

2 Likes
6

OK thanks. Would be good to know how soon that implementation might be ready for testing. Also curious to learn why the bsky one is unlikely to be OSS, but appreciate that might not be something which can be shared publicly.

If we were to start with a single PDS hosted on our domain certified.app, and then an entryway implementation became available later, do you happen to know the likely feasibility of switching to running an entryway on certified.app and having it proxy to the existing PDS which we would have migrated to run on something like pds-eu-west4.certified.app? Would this require PLC registry updates for each user with a pre-existing account on that PDS?

1 Like
7

Yes. This is what we talked about in Montreal.

Right now you overload the PDS entry in the DID doc.

What we talked about in Montreal for @iame.li custom PDS was a second did entry - so a user account could control which SDS server it is linked to.

1 Like
8

Yes. You can see this in the DID doc history of when bsky team migrated everyone to mushroom servers. See my bmann.ca history for an example.

@alex.bsky.team got any thoughts on entryway practices here? Urgency is going up as people do for real production deploys.

9

Bluesky runs it in production and keeps the repo pretty locked down pushing even contributions like docker images or deploy tips to separate repos.

If I were them, I also wouldn’t take in this change, especially with future directions for private data not settled at all.

Changes like this are likely better done as a community maintained fork. And I use the term fork loosely, as SDS is a pretty big change. But one that is likely of interest to many!

So - totally encourage you to fork and brand this. We’re going to have more and more PDS and variants over time. That’s what protocols and specs are for - we can interop across many code implementations!

10

We should probably try to clean up the code for the gateways mentioned in PDS Entryway | Bluesky so we can let others run them as (relatively) easily as PDSes! It’s a good thing to call out.

3 Likes
11

I just thought about this some more and had an “ah ha”.

Basically — if you make these “shared accounts” fully work as first class regular accounts, then they will automatically work with any app, in which case using the PDS service entry in the DID doc makes sense.

The flow would look like this

Let’s say I want to run a shared calendar on smokesignal.events

I create an SDS account, give myself @ngerakines.me @knowtheory.net @tynanpurdy.com access to it. I use the domain handle calendar.atprotocol.community

On smoke signal, I put in that handle. It bounces to the SDS server for auth. I then auth in with my bmann.ca account, and I return to smoke signal logged in with this calendar account.

This would be huge for ANY ATProto app!

6 Likes
Representing groups and other shared resources in ATProto
12

Ah ha indeed, very interesting idea! So if I understand you correctly, you’re saying that we could extend our existing SDS approach to achieve out-of-the-box compatibility with all existing ATProto apps, by supporting OAuth login against the SDS? And we could use the existing mechanism whereby the SDS receives a JWT from the PDS proving the logged in user’s identity, to avoid requiring any extra credentials. Kind of like OAuth on OAuth, maybe, where the SDS is both acting as an OAuth provider and an OAuth client against the user’s PDS :grin:

I think our current UX is a bit lower friction than this approach, since there is no need to perform an extra login into the shared handle. If you’re already logged in as yourself, you’re already able to write to any SDS repo you have access to.

That said, the downside of our current approach is that it requires any client app supporting this to be modified so that it knows the difference between the PDS the user is logged into, and the SDS they are writing to.

So maybe we could support both approaches simultaneously. I totally agree with you that out-of-the-box compatibility with all existing ATProto apps would be huge! Thanks so much for this idea - we’ll look into it for sure! :sunglasses:

1 Like
13

Something like this, perhaps?

image
image1943×1581 165 KB

14

Interesting prospect. One case to consider is that logging in and taking actions with the shared account directly obscures authorship of those actions. For some sharing groups that’s fine. For others, tracing contributions is essential.

3 Likes
15

Yes exactly! The need to support the latter is why we (again, credit mainly to @bitbeckers.bsky.social here) built it in a way that actions are traceable back to individuals. The downside is that this requires extra work to build apps which understand the distinction between the individual and the organisation.

I think being able to support apps in both modes of operations would be the ideal scenario, and I’ve started looking into the feasibility of this. That said, we have other burning priorities right now, so it might take a little while to make progress.

16

You can implement logging/audits because everything is going through the PDS and you know what user you’ve issued auth to.

eg I’m logged into exampleApp with an active session. Your SDS database knows that was issued to my user.

This is what you’re already doing but only for SDS operations.

1 Like
17

True. The app wouldn’t know the full picture by itself though, because it would believe that the shared DID (organization) in the SDS is a normal user. The full audit trail would only be available by combining app logs with SDS logs:

  1. The app would know which organization DID performed an operation.
  2. The SDS would know which user was issued which auth token to act as the org.

This might pose additional challenges though, e.g. if two users are both logged in as the org at the same time, the auditor (human or otherwise) would probably have figure out which auth token was used for each SDS operation.

Also the auditor would need access to the SDS logs. These could be made either totally public (e.g. via Firehose), or readable only by members of the organization. This choice could perhaps even be given each organization separately.

However if code was going to be written to support better audit trails for an app in this manner when SDS instances are involved, it might be easier to simply enhance the app to support the approach we currently take, i.e. that XRPC calls to the shared org repo in the SDS originate from the user DID rather than from the org DID.

In addition to avoiding the need for extra org login steps and getting a clear audit trail, I think this has other benefits, e.g. being able to write to multiple shared repos / organizations whilst logged in from a single user account. This is a pretty common UX pattern these days, seen on many platforms including GitHub, GitLab, Notion etc.

That said, there may be situations in which it’s not possible or desirable to modify an existing app, and where building audit capabilities for an app outside its codebase is the preferred way to go. In that case, perhaps the approach I outlined above could work.

N.B. This is all off the top of my head, so I reserve the right to be horribly wrong :winking_face_with_tongue:

18

The “competition” is sharing passwords to a community account right now.

This would probably be useful to step back and examine the users and use cases. I think what you’ve built is a really great start, and I encourage you to make it work out of the box with many different things, rather than requiring each app to explicitly support what you’re doing, if you want the broadest adoption.

We don’t really know how this is going to work, and mostly app builders are going to make choices here, so more experiments is better!

2 Likes
19

Agreed on all points! I want us to aim for the best of both worlds: fully support existing apps (albeit with a slightly degraded UX) whilst retaining support for apps which are natively “SDS-aware”. We already have three of the latter as early adopters of this new generation of the Hypercerts architecture, with another probably to follow soon.

I’m fairly optimistic it will prove possible to support both types of app within the same SDS.

20

@alex.bsky.team Ha, I’m actually just waiting for a client to sponsor me doing a full entryway implementation after I did one on top of the PDS codebase (because I didn’t want to copy+paste all the OAuth related code).

I spent ages researching and reverse engineering what’s necessary to make an open source entryway setup

1 Like