Hats Protocol Docs
hatsprotocol.xyzGithub
  • ๐Ÿ‘‹Welcome to Hats Protocol
  • ๐ŸงขGetting Started with Hats
  • โญQuick Start
  • Using The Hats App
    • ๐Ÿค Essentials For Hat Wearers
    • ๐ŸŽฉCreating My First Hat
    • ๐Ÿง™Admins: Creating, Issuing, and Revising Hats
    • ๐Ÿ‘ฅWhat Hats Do I Need?
    • ๐ŸŒณDrafting, Exporting, and Deploying Tree Changes
    • ๐Ÿ—๏ธSetting a Hat's Basic Properties
    • ๐ŸฅณAdding Wearers
    • ๐Ÿ”Connecting Hats w/ Permissions & Authorities
      • Types of Hat-Powered Authorities
      • Connecting Hats to Token Gates
        • Hats Protocol Contract Addresses
        • Finding a Hat's Token ID
      • Documenting Hat Powers & Responsibilities
    • ๐ŸŒŸRevocation & Eligibility: Requirements for Wearers
    • โšกDeactivating & Reactivating Hats
    • โœ…Making Hats Claimable
    • ๐Ÿ”—Linking Trees Together
    • โ›“๏ธHats Protocol Supported Chains
    • โ“Glossary & FAQ
  • Hats Integrations
    • ๐Ÿ”Permissions & Authorities
      • Coordinape
      • Council Voting Vault
      • Charmverse
      • Discord
        • Collab.Land --> Discord
        • Guild.xyz --> Discord
      • Farcaster Casting Rights
      • Fileverse
      • Google Workspace
      • Hats Account
      • Role-Based Compensation
      • Safe Multisig Signing Authority
      • Telegram
        • Collab.Land --> Telegram
        • Guild.xyz --> Telegram
      • Snapshot: Voting, Weight & Proposal Creation
      • Wonderverse
    • ๐ŸŒŸEligibility & Accountability Criteria
      • Agreement Eligibility
      • Allow-List Eligibility
      • CoLinks Eligibility
      • ERC20 Eligibility
      • ERC721 Eligibility
      • ERC1155 Eligibility
      • Hat-Wearing Eligibility
      • Hats Election Eligibility
      • JokeRace Eligibility
      • Pass-Through (Hat-Based) Eligibility
      • Staking Eligibility
      • Subscription or Membership Fee (Unlock Protocol)
      • Gitcoin Passport Eligibility
    • โšกActivation & Deactivation Criteria
      • Seasonal/ Time-Expiry Toggle
      • Pass-Through (Hat-Based) Toggle
    • ๐Ÿ‘ทHatter Modules
      • Multi Claims Hatter
      • DAOhaus Moloch v3 Membership & Share Allocation
  • For Developers
    • ๐Ÿ‘ทHats Protocol, for Developers
      • Hat Properties
      • Wearing a Hat
      • Hat Admins & Hatter Contracts
      • Hats Trees
      • Hat IDs
      • Linking Hats Trees
      • Eligibility Modules
      • Toggle Modules
      • Hat Mutability and Editing
      • Creating Hats
      • Minting Hats
      • Transfering Hats
      • Renouncing Hats
      • Batch Actions
      • Hat Image URIs
      • ERC1155 Compatibility
      • โ›“๏ธSupported Chains
    • ๐Ÿค–v1 Protocol Spec
      • Hats.sol
      • HatsEvents.sol
      • HatsErrors.sol
      • HatsIdUtilities.sol
      • Interfaces
        • IHats.sol
        • IHatsIdUtilities.sol
        • IHatsEligibility.sol
        • IHatsToggle.sol
    • ๐Ÿ–ฅ๏ธv1 SDK
      • Core
        • Getting Started
        • Onchain Reads
        • Onchain Writes
        • Multicall
        • Claiming Hats
        • Utilities
      • Subgraph
        • Getting Started
        • Fetching Hats
        • Fetching Wearers
        • Fetching Trees
        • Misc
        • Types
      • Hat Details
        • Getting Started
        • Usage
    • ๐Ÿ”ญv1 Subgraphs
    • ๐ŸงฉHats Modules
      • ๐Ÿ”ŒModules SDK
        • Getting Started
        • Get Available Modules
        • Create New Instance/s
        • Composing Modules
        • Interact With Instances
        • Utilities
        • Types
      • โš’๏ธBuilding Hats Modules
        • Inside a Hats Module
          • Immutable Arguments
          • Module Setup
          • Versioning
        • Creating New Modules
        • How Module Instances Are Deployed
        • Modules Registry
        • About Module Chains
    • ๐Ÿ”Hats Signer Gate v2
    • ๐Ÿ‘’Hats Signer Gate SDK
      • Getting Started
      • Creating New Instances
      • Hats Signer Gate
      • Multi Hats Signer Gate
      • HSG & MHSG Handlers
    • ๐Ÿ’ผHats Account SDK
      • 1 of N Hats Account
        • Getting Started
        • Creating New Instances
        • Executing From An Instance
        • Constants
        • Types
    • ๐ŸŒHats Security Audits
  • Legal
    • Terms
      • Terms of Service
      • Acceptable Use
      • Privacy Policy
      • Cookie Policy
      • Attribution
Powered by GitBook
On this page
  • Zodiac Module
  • Zodiac Guard
  • Signer Management
  • Threshold Configuration
  • Delegatecall Targets
  • Security Considerations
  • Contract Ownership
  • Deploying New Instances
  • Security Audits
  • Recent Deployments
  1. For Developers

Hats Signer Gate v2

This page describes the second version of Hats Signer Gate.

PreviousAbout Module ChainsNextHats Signer Gate SDK

Last updated 4 months ago

Hats Signer Gate (HSG) v2 is a contract that grants multisig signing rights to addresses wearing a given hats, enabling on-chain organizations to revocably delegate to individuals constrained authority and responsibility to operate an account (i.e. a Safe) owned by the organization.

Zodiac Module

is a module that...

  1. Grants multisig signing rights to addresses based on whether they are wearing the appropriate Hat(s).

  2. Removes signers who are no long valid (i.e. no longer wearing the signer Hat)

  3. Manages the multisig threshold within the owner-specified range as new signers are added or removed.

Zodiac Guard

Since Hat-wearing is dynamic โ€” Hats can be programmatically revoked from wearers โ€” this contract also services as a guard to ensure that:

A) Only valid signers can execute transactions, i.e. only signatures made by accounts currently wearing a valid signer Hat count towards the threshold.

B) Signers cannot execute transactions that remove the constraint in (A). Specifically, this contract guards against signers...

  1. Executing calls to the Safe itself. This prevents the signers from changing any of the Safe's storage values, including those referenced below.

  2. Executing delegatecalls to any not approved by the HSG owner

  3. Executing any delegatecall (even to an approved target contract) that does the any of following

    1. Removes HSG as a guard on the Safe

    2. Removes HSG as a module on the Safe โ€” or changing/adding any other modules

    3. Changes the Safe threshold

    4. Changes the Safe owners (aka signers)

    5. Changes the Safe fallback handler

Protections against (3c) and (3d) above only hold if the Safe does not have any authority over the signer Hat(s). If it does โ€” e.g. it wears an admin Hat of the signer Hat(s) or is an eligibility or toggle module on the signer Hat(s) โ€” then in some cases the signers may be able to indirectly change the Safe threshold or owners.

Proceed with caution if granting such authority to a Safe attached to HatsSignerGate.

Signer Management

Hats Signer Gate provides several ways to manage Safe signers based on their hat-wearing status:

Claiming Signer Rights

  • Individual hat wearers can claim their own signing rights via claimSigner()

  • Must be wearing a valid signer hat at time of claim

  • Each signer's hat ID is registered and tracked for future validation

Claiming for Others

When enabled by the owner (claimableFor = true):

  • Anyone can claim signing rights on behalf of valid hat wearers via claimSignerFor() or claimSignersFor()

  • Useful for batch onboarding of signers

  • Prevents re-registration if signer is still wearing their currently registered hat

Signer Removal

  • Signers who no longer wear their registered hat can be removed via removeSigner()

  • Threshold automatically adjusts according to the threshold configuration

  • If the removed signer was the last valid signer, the contract itself becomes the sole owner

Threshold Configuration

The threshold (number of required signatures) is managed dynamically based on the ThresholdConfig:

Threshold Types

  1. ABSOLUTE

    • Sets a fixed target number of required signatures

    • Example: Always require exactly 3 signatures

    • Bounded by min threshold and number of valid signers

  2. PROPORTIONAL

    • Sets a percentage of total signers required (in basis points)

    • Example: Require 51% of signers (5100 basis points)

    • Actual number of required signatures rounds up

    • Still bounded by min threshold

Configuration Parameters

  • min: Minimum number of required signatures (must be > 0)

  • target: Either fixed number (ABSOLUTE) or percentage in basis points (PROPORTIONAL)

  • thresholdType: ABSOLUTE (0) or PROPORTIONAL (1)

The Safe's threshold is automatically adjusted when:

  • New signers are added

  • Existing signers are removed

  • Threshold configuration is changed

Delegatecall Targets

HSG restricts delegatecalls to protect the Safe from unauthorized modifications. Only approved targets can receive delegatecalls.

Default Enabled Targets

The following MultiSend libraries are enabled by default:

Address
Version
Type

0x40A2aCCbd92BCA938b02010E17A5b8929b49130D

v1.3.0

canonical

0xA1dabEF33b3B82c7814B6D82A79e50F4AC44102B

v1.3.0

eip155

0x9641d764fc13c8B624c04430C7356C1C7C8102e2

v1.4.1

canonical

Security Considerations

  • Delegatecalls can modify Safe state if not properly restricted. Owners should NOT approve delegatecall targets that enable the following:

    • Directly modifying any of the Safe's state, including the Safe's nonce.

  • HSG validates that approved delegatecalls don't modify critical Safe parameters, but relies on the Safe' nonce to do so.

  • Direct calls to the Safe are always prohibited

  • When detaching HSG from a Safe โ€” i.e. when calling detach() โ€” the owner must trust that admin(s) of the signer Hat(s) will not front-run the detachment to add arbitrary signers. Since admins in Hats Protocol are already trusted (and can be revoked, held accountable, etc.) this is not an additional risk, but HSG owners should nonetheless be aware of this risk.

Contract Ownership

The wearer of the ownerHat can make the following changes to Hats Signer Gate:

  1. "Transfer" ownership to a new Hat by changing the ownerHat

  2. Change the threshold configuration

  3. Enable other Zodiac modules on HSG itself

  4. Enable another Zodiac guard on HSG itself

  5. Add other Hats as valid signer Hats

  6. Enable or disable the ability for others to claim signer rights on behalf of valid hat wearers (claimableFor)

  7. Detach HatsSignerGate from the Safe (removing it as both guard and module)

  8. Migrate to a new HatsSignerGate instance

  9. Enable or disable specific delegatecall targets

  10. Lock the contract permanently, preventing any further owner changes

Deploying New Instances

Instances can be created for an existing Safe by passing the Safe address on initialization, or for a new Safe to be deployed from within HSG's initialization.

Security Audits

v2 โ€” the present version โ€” has received the following security audits. See the v2 audits directory for the detailed reports.

Auditor
Report Date
Commit Hash
Notes

Sherlock

December 13, 2024

166 auditors participated

Since this audit was completed, HSG code was updated to add a variable salt to the Safe proxy creation within the SafeManagerLib.deploySafeAndAttachHSG function. This ensures that the address of the Safe proxy is unique to the HSG instance.

Recent Deployments

See for more information.

Additional delegatecalls. For example, the library that is not "call only" should not be approved. The is approved by default.

Instances of HSG can be created via the .

See for deployments. Specific deployment parameters are stored here.

๐Ÿ”
safe-deployments
MultiSend.sol
MultiSendCallOnly.sol
Zodiac module proxy factory
Releases
HatsSignerGate.sol
Zodiac
Zodiac
target contract
a9e3f4f