update readme

README.md

@@ -1,9 +1,26 @@
-# hats-module-template
+# Allowlist Eligibility Module
 
-Template repo for Hats Module projects.
+A [Hats Protocol](https://github.com/hats-protocol/hats-protocol) eligibility module that uses an allowlist to determine eligibility.
 
 ## Overview and Usage
 
+This module sets up a simple allowlist to determine eligibility for a hat. For a given account (i.e., potential hat wearer), the allowlist stores values for that account's eligibility and standing for the hat. The wearer(s) of the `OWNER_HAT` can add or remove accounts from the allowlist. The wearer(s) of the `ARBITRATOR_HAT` can set the standing of accounts.
+
+This module serves as both a "mechanistic" and "humanistic passthrough" eligibility module. 
+
+### Mechanistic Functionality
+- Wearer(s) of the `OWNER_HAT` can simply add account(s) to the allowlist by calling `addAccount()` or `addAccounts()`.
+- Wearer(s) of the `OWNER_HAT` can simply remove account(s) from the allowlist by calling `removeAccount()` or `removeAccounts()`.
+- Wearer(s) of the `ARBITRATOR_HAT` can simply set the standing of account(s) by calling `setStandingForAccount()` or `setStandingForAccounts()`.
+
+In each of these cases, Hats Protocol will *pull* eligibility and standing data from the module via `getWearerStatus()`. Hats Protocol will not emit an event with any of these eligibility and resulting wearer changes, so front ends pointing only at Hats Protocol events (or the [subgraph](https://github.com/hats-protocol/subgraph)) will not automatically reclect these changes.
+
+### Humanistic Functionality 
+- Wearer(s) of the `OWNER_HAT` can manually revoke an account's hat by calling `removeAccountAndBurnHat()`.
+- Wearer(s) of the `ARBITRATOR_HAT` can manually put an account in bad standing and burn their hat `setStandingForAccountAndBurnHat()`.
+
+In these cases, the module *pushes* eligibility and standing data to Hats Protocol, causing Hats Protocol to emit event(s) reflecting the eligibility and resulting wearer changes. Front ends pointing at Hats Protocol events (or the subgaph) *will* automatically reflect these changes.
+
 ## Development
 
 This repo uses Foundry for development and testing. To get started: