Discussion: Modules Registry Curation Mechanism

This is a preliminary proposal to define the curation mechanism and guidelines for the Hats Modules Registry. I am seeking input on all aspects before bring the formal proposal later next week — by November 17 — so please weigh in!

This post has several sections:

  1. Background
  2. Design Goals, Considerations, and Trade-offs
  3. Preliminary Proposal
  4. Open Questions

1. Background

Hats Modules are smart contracts that extend the functionality and behavior of hats, enabling customized and automated management of roles and their attendant authorities. Hats Modules expand Hats Protocol from a useful tool to a flexible and powerful platform for designing, building, and operating modern organizations.

Anybody can build Hats Modules and use them with their hats. Fulfilling their promise as a platform, however, requires separating Builders (ie those who develop modules) from Wearers (ie those who use them). Our goal is to give Wearers the full breadth of modules they need to meet their needs, and one of the best ways to accomplish this is to create strong incentives for Builders to create them. In other words, a marketplace for modules.

Thus far, we have planted the seeds for such a marketplace. Just a couple weeks ago, Haberdasher Labs (increasingly known as Hab Labs :wink:) launched the Hats Modules Registry with a handful of initial modules, launched the Modules SDK that enable apps to distribute them to Wearers, and updated the Hats App with the Modules SDK to enable Wearers to select, configure, and deploy them.

This proposal aims to water those seedlings so that they can grow strong and resilient. It outlines mechanisms for how the Hats Modules Registry can be well-curated while navigating key trade-offs (3.1), and defines an initial curation rubric (3.2). It expects additional evolution and refinement will be necessary in subsequent proposals.

2. Design Goals, Considerations, and Trade-offs

Long-term Considerations

  • Desire to evolve into a true marketplace, where Builders are compensated for the value they create for Wearers in the form of modules.
  • Ability to decentralize over time, likely moving onchain in some form.
  • Design for future automation.

Design Goals

  • Healthy competition between modules drives quality and variety and therefore value to the ecosystem
    • We should encourage developers to create better and more efficient versions of existing modules
    • clear and fair process and requirements
    • ability to compete
    • good response time from the curation process
  • Minimize curation overhead, including effort and attention required
  • Similarly, minimize the amount of time it takes to review new registry submissions
  • Minimize time to value for Builders: less time between building a module and having it distributed to Wearers.
  • Automate what we can now.
  • Wearers need to understand clearly what a given module does, how it’s different from other modules, and (potentially) when it’s useful

Design Constraints and Trade-offs

  • Credible curation neutrality is important to attract Builders; a less opinionated approach is likely necessary to achieve this.
  • Tradeoff between increased demands on curator attention and speed (time to value)
  • Must handle conflicting module names
  • Must disambiguate between similar modules
  • Need to handle module versioning gracefully, including for deprecated / replaced modules
  • Apps can — and probably should — be more opinionated and selective about the modules they serve up to their users
  • Curators will need tools to curate well
  • Module developers need to be able to test how their metadata is handled up the stack (ie the Modules SDK and apps)

3. Preliminary Proposal

3.1 Curation Mechanism

3.1.1 Curation Layers

Just like the multiple layers of the Hats Protocol stack enable broad credible neutrality combined with a variety of more opinionated components, Hats Module curation should have multiple layers.

Base Curation Layer: the Registry

The base layer is the Registry, the primary focus of this proposal. With the exception of the Other Curation Layers section below, the remainder of this proposal relates only to the Registry.

Getting this base layer right will create the conditions for other layers to emerge on top.

The base layer curation is:

  • global: a single Registry shared by the entire Hats Ecosystem
  • focused primarily on objective criteria
  • creates the metadata foundation for apps to distribute modules to Wearers

Other Curation Layers

Other curation layers can and will emerge over time. Compared to the Registry, they will be:

  • pluralistic, multistakeholder, & polycentric
  • more focused on subjective criteria; more selective; more opinionated
  • can/will impose some down-stack pressure on Builders to make high quality submissions to the base layer Registry
  • potential example: module lists
    • similar to token-lists
    • can be created by apps or any member of the ecosystem
  • current thinking: should not require additional data to be added

3.1.2 Curation Committee

Governing and curating the Registry is the responsibility and authority of the protoDAO. Under this proposal, the protoDAO delegates those responsibilities and authorities to a Modules Registry Curation Committee. Committee membership will be defined by a new Modules Registry Curator hat, to be created with this proposal.

The Modules Registry Curation Committee:

  • 3 to ~7 members (initially Stewards) who wear the new Modules Registry Curator hat.

Modules Registry Curator hat

  • Wearers will be selected by the protoDAO
  • Description: The role of the Modules Registry Curator is to foster a healthy ecosystem of Hats Modules and to ensure a high standard of quality and functionality for modules within it. They do so by governing the Hats Modules Registry mechanisms, and by reviewing and approving submissions and modifications to the Hats Modules Registry in accordance with those mechanisms and in collaboration with fellow Curators and the protoDAO at large.
  • Responsibilities
    • Curation
      • review submissions and modification requests per the cadence outlined below
      • uphold high level of quality for modules on registry
    • Mechanism Governance
      • ensure the Registry and Curation Mechanism meet the design goals and improve over time
  • Authorities
    • Curation
      • approve module submission PRs in the modules-registry repository
      • approve registry/schema modification PRs in the repository
      • merge PRs when approved by 2 or more Curators
    • Mechanism Governance
      • make changes to the submission schema and Modules Curation Rubric as needed
  • Accountabilities
  • Mutable
  • Max supply: 9
  • Image: TBD

3.1.3 Curation Actions

  • Github PR approval
  • Each module submission is a separate PR
  • Requires approval from at least two Curators to be merged

3.1.4 Curation Cadence

  • Standard cadence: Monthly.
    • All newly approved modules and changes to registered modules are to be announced at the end of each month
    • To be included in a given month, new submissions or changes must be submitted no later than one week before the end of the month
    • Within this constraint, Curators may review async or devise their own process and timing
  • Expedited review: module developers can request review outside of the standard cadence on an ad hoc basis
    • Curator discretion for when they honor the request

3.2 Modules Curation Rubric

Objective criteria

  • Safety
    • the module works as described; no bugs
    • is not malicious
  • Adheres to the registry submission schema
    • metadata is complete
    • implementation contract is deployed to at least one chain
  • Quality
    • Automated tests pass
    • metadata (including name, descriptions, other documentation) is accurate

Subjective criteria

  • Legibility of metadata (Is it user-friendly? Is it a good name, description, etc?)

Due to the high cost of curator effort/attention at base layer involved in subjective assessment, the inclusion of subjective criteria in the rubric should be re-evaluated as the volume of Registry submissions increases.

4. Open Questions

  • How should changes to the submission schema be handled? For example, what happens to existing submissions when the schema changes?
  • How can we foster neutral access to expedited review? We don’t want to create an inherent advantage for certain Builders (eg Hab Labs) over others, but it’s also important for Hab Labs and other service providers to be able to move quickly when helping Wearers implement their hats trees.
  • Who will the first Modules Registry Curators be? Ideally we can mint the new hat to them as part of this proposal.


This proposal includes insights and perspectives from protoDAO stewards BPetes, Payton, Ido, Scott, Juliette, and Brennan. Thank you!


Here are some related topics that are not part of the proposal itself but may provide helpful context for reviewers.

Submission Schema

Recommended changes

  • Add an admin-details key for a description of how a module’s admin or owner model works

  • Add an eligibility-type key for more details on eligibility modules, including whether they set eligible and toggle values and what are the defaults for those values.

  • Replace the deployments key with a supported-chainids key (an array of chainIds).

    • The first chainId in the array must be a chain to which the module’s implementation is deployed.
    • Rationale: not all modules will be relevant to all chains, eg when a module serves as an adapter for another protocol that only exists on Optimism.
    • The rest do not need to have deployments of the module implementation
    • This change takes deploying the same module to new chains out of the curation cycle, reducing curation overhead (now anybody — most likely apps — can lazily deploy the implementation when a Wearer first wants to use it on a new chain in the supported list)
    • Crucially, it maintains the ability for automated scripts to test the module’s logic

Other Recommendations

  • Hab Labs should consider enabling its app to support unregistered modules, enabling a tool for developers and curators to test out prospective module registrations.

  • Hats Clients (including those built by HabLabs and Sobol) should consider publishing their own list of accepted modules as well as their criteria for selecting them

    • The protoDAO should consider standardizing this process over time
1 Like

:pray: you for leading this out!

I’m most fascinated by the testing and subsequent release documentation. I imagine that for some modules with higher complexity (e.g. HSG) that there will be warnings/advice surrounding how to config and patterns of composition to avoid. How might we capture and disseminate this for app developers and end users?

1 Like

Can you elaborate on what specifically you mean by release documentation? I suspect a key question will be who is responsible for producing / maintaining it. My current sense is that that should fall to the developer of each module, though there are definitely tradeoffs with that. What do you think?

As an aside, technically HSG does not count as a module, since its neither Eligibility, Toggle, or a Hatter contract. HSG is more like an authority adapter or a hat-gate, which is outside the scope of the Modules Registry. There is, though, definitely value in some sort of curation that includes non-modules — the Hats Community Wiki is kind of a primitive version of this.

1 Like

The module metadata that is included in the registry includes currently three relevant fields for that:

  1. General free text description about the module.
  2. Optional links to external sources, which can include a link to a documentation page
  3. Each creation argument of the module includes a free text description which is intended to include its purpose/functionality

So a module which usage is not trivial, in the sense that there is a wrong way to use it that can cause damage, should probably use these fields to include a clear documentation about these patterns.

In general, I think part of the curation purpose is to make sure that modules are well documented. Question is whether the current fields in the schema are good enough for this purpose, and also what are the right criteria for a good documentation.

A key consideration here is the overhead (time/effort/attention) required to make sure that modules are well-documented. The farther down the curation stack we do this, the costlier it will be.

This is why I’m recommending that base layer curation — ie of the Registry — only include subjective assessment of submission metadata quality temporarily while Registry submission volume is relatively low.

With this in mind I’m going to revise the below text to include a note that subjective criteria be reconsidered often as submission volume increases.

1 Like

Yes, this makes sense and as long as it’s a link pointing to live documentation I could see this working fine.

Gotcha, that was an oversight on my part – I think I was just enamoured and concerned by the complexity of composable adapters like this, but can see that a more simplistic focus on things like the 3 types you mention is helpful. Wonder how or where adapters would be discovered and if it’s expected that groups other that HabLabs would develop and deploy them?

Current thinking is a Hats awesome-list repo or something similar. But it could and maybe should evolve over time into something really robust. Good fodder for protoDAO discussion!

There’s a solid tension between

while minimizing curation overhead.

I do think this layer should focus more on curating working and not malicious modules and defer higher-level curation to token-list style mechanisms for “worthy” modules.

An option could be that the sdk could take in an optional module-list that can filter the “available” modules based on the provided list. Keeping the curation separate from propagation.

You also gesture towards this solution here:

1 Like

Planning on a sort of syllabus (scoring) or is it all or nothing on objective criteria and minimizing impact from subjective criteria?

Yea this is a nice idea. Maybe something like a separate module-list repo that people couple open PRs against to add their own list(s), which the SDK would (optionally?) pull from. Following the token-list example, it would probably eventually make sense to allow apps and users to view lists(s) of their choice.

1 Like