A governance repo for all things of the hypercollective
feat: initialize Hypercollective with LIR governance process
- Lexicon Indexing Request (LIR) governance framework
- LIR-0001: GainForest Lexicons (Darwin Core, Evaluator, Organization)
- LIR-0002: Impact Indexer Review System (comments, likes)
- LIR-0003: Hypercerts Lexicons (claims, funding, badges, locations)
- GitHub issue template for easy LIR submission
- Contributing organizations: GainForest, Hypercerts, Ma Earth
+1854
+177
.github/ISSUE_TEMPLATE/lexicon-indexing-request.yml
+177
.github/ISSUE_TEMPLATE/lexicon-indexing-request.yml
···
1
+
name: Lexicon Indexing Request (LIR)
2
+
description: Propose a new Lexicon to be indexed by Hypergoat
3
+
title: "LIR: [Lexicon Name]"
4
+
labels: ["lir", "triage"]
5
+
body:
6
+
- type: markdown
7
+
attributes:
8
+
value: |
9
+
## Lexicon Indexing Request (LIR)
10
+
11
+
Use this form to propose a new AT Protocol Lexicon for indexing in the Hypersphere ecosystem.
12
+
13
+
**Before submitting:**
14
+
- Read the [governance process](../blob/main/GOVERNANCE.md)
15
+
- Check existing LIRs to avoid duplicates
16
+
- Review the [example LIR](../blob/main/lirs/LIR-0000-example.md)
17
+
18
+
- type: input
19
+
id: nsid
20
+
attributes:
21
+
label: Lexicon NSID
22
+
description: The Namespaced Identifier for this lexicon
23
+
placeholder: "app.example.collection.name"
24
+
validations:
25
+
required: true
26
+
27
+
- type: textarea
28
+
id: abstract
29
+
attributes:
30
+
label: Abstract
31
+
description: A brief (2-3 sentence) summary of the lexicon and why it should be indexed
32
+
placeholder: |
33
+
This lexicon defines [what it represents]. Indexing it enables [use cases].
34
+
validations:
35
+
required: true
36
+
37
+
- type: textarea
38
+
id: motivation
39
+
attributes:
40
+
label: Motivation
41
+
description: |
42
+
Explain why this lexicon should be added to Hypersphere:
43
+
- What problem does this solve?
44
+
- Who will benefit?
45
+
- What use cases are enabled?
46
+
- Is there existing adoption?
47
+
placeholder: |
48
+
### Problem
49
+
[Describe the problem]
50
+
51
+
### Who Benefits
52
+
[List stakeholders]
53
+
54
+
### Use Cases
55
+
1. [Use case 1]
56
+
2. [Use case 2]
57
+
58
+
### Existing Adoption
59
+
[Describe current usage]
60
+
validations:
61
+
required: true
62
+
63
+
- type: textarea
64
+
id: schema
65
+
attributes:
66
+
label: Lexicon Schema
67
+
description: Paste the full lexicon JSON schema
68
+
render: json
69
+
placeholder: |
70
+
{
71
+
"lexicon": 1,
72
+
"id": "app.example.collection.name",
73
+
"defs": {
74
+
"main": {
75
+
"type": "record",
76
+
...
77
+
}
78
+
}
79
+
}
80
+
validations:
81
+
required: true
82
+
83
+
- type: textarea
84
+
id: example
85
+
attributes:
86
+
label: Example Record
87
+
description: Provide an example record that conforms to this schema
88
+
render: json
89
+
placeholder: |
90
+
{
91
+
"$type": "app.example.collection.name",
92
+
"field1": "value",
93
+
"createdAt": "2024-01-15T10:30:00.000Z"
94
+
}
95
+
validations:
96
+
required: true
97
+
98
+
- type: textarea
99
+
id: queries
100
+
attributes:
101
+
label: Example GraphQL Queries
102
+
description: Show how users would query this data via the Hypergoat GraphQL API
103
+
render: graphql
104
+
placeholder: |
105
+
query GetRecords {
106
+
appExampleCollectionName(first: 10) {
107
+
edges {
108
+
node {
109
+
uri
110
+
did
111
+
field1
112
+
}
113
+
}
114
+
}
115
+
}
116
+
validations:
117
+
required: false
118
+
119
+
- type: textarea
120
+
id: hypergoat
121
+
attributes:
122
+
label: Hypergoat Changes
123
+
description: What needs to happen in Hypergoat?
124
+
placeholder: |
125
+
- [ ] Upload lexicon schema
126
+
- [ ] Configure Jetstream subscription
127
+
- [ ] Trigger backfill
128
+
- [ ] Custom indexing requirements (if any)
129
+
validations:
130
+
required: false
131
+
132
+
- type: textarea
133
+
id: impactindexer
134
+
attributes:
135
+
label: Impact Indexer Changes
136
+
description: What documentation or UI changes are needed?
137
+
placeholder: |
138
+
- [ ] Add to Lexicon Reference page
139
+
- [ ] Create collection-specific visualization
140
+
- [ ] Update API documentation
141
+
validations:
142
+
required: false
143
+
144
+
- type: textarea
145
+
id: security
146
+
attributes:
147
+
label: Security Considerations
148
+
description: Any privacy or security concerns?
149
+
placeholder: |
150
+
- Does this data contain PII?
151
+
- Are there access control requirements?
152
+
validations:
153
+
required: false
154
+
155
+
- type: dropdown
156
+
id: priority
157
+
attributes:
158
+
label: Priority
159
+
description: How urgent is this request?
160
+
options:
161
+
- Low - Nice to have
162
+
- Medium - Would be useful
163
+
- High - Blocking a project
164
+
validations:
165
+
required: true
166
+
167
+
- type: checkboxes
168
+
id: checklist
169
+
attributes:
170
+
label: Checklist
171
+
options:
172
+
- label: I have read the [governance process](../blob/main/GOVERNANCE.md)
173
+
required: true
174
+
- label: The lexicon schema is valid and complete
175
+
required: true
176
+
- label: I have checked for duplicate LIRs
177
+
required: true
+168
GOVERNANCE.md
+168
GOVERNANCE.md
···
1
+
# Hypercollective Governance
2
+
3
+
This document describes the governance processes for the Hypercollective, including how to propose changes, the review process, and decision criteria.
4
+
5
+
## Lexicon Indexing Request (LIR)
6
+
7
+
A **Lexicon Indexing Request (LIR)** is a formal proposal to add a new AT Protocol Lexicon to the indexing infrastructure.
8
+
9
+
### What is a Lexicon?
10
+
11
+
In the AT Protocol, a **Lexicon** defines the schema for a record type. Lexicons use NSIDs (Namespaced Identifiers) like:
12
+
13
+
- `app.bsky.feed.post` - Bluesky posts
14
+
- `org.hypercerts.claim.activity` - Hypercerts activity records
15
+
- `app.gainforest.dwc.occurrence` - Darwin Core biodiversity occurrences
16
+
17
+
When Hypergoat indexes a lexicon, it:
18
+
1. Subscribes to real-time events for that collection via Jetstream
19
+
2. Stores records in the database
20
+
3. Generates GraphQL types and resolvers dynamically
21
+
4. Exposes the data via the GraphQL API
22
+
23
+
### LIR States
24
+
25
+
```
26
+
┌─────────┐ ┌──────────────┐ ┌──────────┐ ┌─────────────┐
27
+
│ Draft │ ──► │ Under Review │ ──► │ Accepted │ ──► │ Implemented │
28
+
└─────────┘ └──────────────┘ └──────────┘ └─────────────┘
29
+
│
30
+
│
31
+
▼
32
+
┌──────────┐
33
+
│ Rejected │
34
+
└──────────┘
35
+
```
36
+
37
+
| State | Description |
38
+
|-------|-------------|
39
+
| **Draft** | Initial proposal, may be incomplete |
40
+
| **Under Review** | Being actively discussed by maintainers |
41
+
| **Accepted** | Approved for implementation |
42
+
| **Implemented** | Deployed to production |
43
+
| **Rejected** | Not accepted (with documented reasoning) |
44
+
45
+
### LIR Numbering
46
+
47
+
LIRs are numbered sequentially: `LIR-0001`, `LIR-0002`, etc.
48
+
49
+
The filename format is: `LIR-XXXX-short-title.md`
50
+
51
+
Example: `LIR-0001-darwin-core-occurrences.md`
52
+
53
+
---
54
+
55
+
## Decision Criteria
56
+
57
+
When reviewing a LIR, maintainers consider the following criteria:
58
+
59
+
### Required
60
+
61
+
- [ ] **Valid Lexicon Schema** - The lexicon must have a valid JSON schema that conforms to the AT Protocol Lexicon specification
62
+
- [ ] **Published NSID** - The NSID must be properly namespaced (e.g., under a domain you control)
63
+
- [ ] **Clear Use Case** - The proposal must explain why this data should be indexed
64
+
65
+
### Strongly Encouraged
66
+
67
+
- [ ] **Existing Adoption** - Are there already records being created with this lexicon?
68
+
- [ ] **Community Demand** - Is there demonstrated interest from multiple parties?
69
+
- [ ] **Data Quality** - Is the schema well-designed with appropriate types and validation?
70
+
71
+
### Considerations
72
+
73
+
- [ ] **Maintenance Burden** - How much ongoing maintenance will this require?
74
+
- [ ] **Storage Impact** - Will this significantly increase database size?
75
+
- [ ] **Query Patterns** - Are the expected query patterns efficient?
76
+
- [ ] **Privacy/Security** - Does the data have any sensitive content?
77
+
78
+
### Automatic Acceptance
79
+
80
+
The following lexicons are automatically accepted:
81
+
82
+
1. **Hypercerts lexicons** (`org.hypercerts.*`)
83
+
2. **GainForest lexicons** (`app.gainforest.*`)
84
+
3. **Core AT Protocol lexicons** (as needed for ecosystem functionality)
85
+
86
+
---
87
+
88
+
## Review Process
89
+
90
+
### 1. Submission
91
+
92
+
Author submits a LIR via:
93
+
- GitHub Issue (recommended)
94
+
- Pull Request with markdown file
95
+
96
+
### 2. Initial Triage (1-3 days)
97
+
98
+
A maintainer will:
99
+
- Assign a LIR number if not already assigned
100
+
- Check for completeness
101
+
- Request clarifications if needed
102
+
- Move to "Under Review" status
103
+
104
+
### 3. Discussion Period (1-2 weeks)
105
+
106
+
- Community feedback is gathered
107
+
- Technical feasibility is assessed
108
+
- Questions are addressed by the author
109
+
110
+
### 4. Decision
111
+
112
+
Maintainers will:
113
+
- **Accept** - Move forward with implementation
114
+
- **Request Changes** - Ask for modifications before acceptance
115
+
- **Reject** - Decline with documented reasoning
116
+
117
+
### 5. Implementation
118
+
119
+
Once accepted:
120
+
1. Lexicon is uploaded to Hypergoat
121
+
2. Backfill is triggered (if historical data exists)
122
+
3. Impact Indexer documentation is updated
123
+
4. LIR status is updated to "Implemented"
124
+
125
+
---
126
+
127
+
## How to Write a Good LIR
128
+
129
+
### Do
130
+
131
+
- Provide a clear, concise abstract
132
+
- Explain the motivation and use cases
133
+
- Include a complete lexicon schema
134
+
- Show example records
135
+
- Provide sample GraphQL queries
136
+
137
+
### Don't
138
+
139
+
- Submit incomplete lexicon schemas
140
+
- Propose lexicons without clear use cases
141
+
- Request indexing of personal/private data
142
+
- Duplicate existing functionality
143
+
144
+
---
145
+
146
+
## Governance Roles
147
+
148
+
| Role | Responsibilities |
149
+
|------|------------------|
150
+
| **Author** | Writes and champions the LIR |
151
+
| **Maintainer** | Reviews LIRs, makes decisions |
152
+
| **Implementer** | Adds lexicon to Hypergoat |
153
+
| **Documenter** | Updates Impact Indexer docs |
154
+
155
+
Current maintainers:
156
+
- GainForest core team
157
+
158
+
---
159
+
160
+
## Amendments
161
+
162
+
This governance document may be updated via pull request. Significant changes require approval from at least two maintainers.
163
+
164
+
---
165
+
166
+
## Questions?
167
+
168
+
Open a discussion or issue in this repository.
+81
README.md
+81
README.md
···
1
+
# Hypercollective
2
+
3
+
Central repository for feature requests, governance proposals, and Lexicon Indexing Requests (LIRs) for the open AT Protocol impact ecosystem.
4
+
5
+
## What is the Hypercollective?
6
+
7
+
An open AT Protocol ecosystem for environmental impact tracking, biodiversity data, and decentralized public goods infrastructure. Key components include:
8
+
9
+
| Project | Description | Live URL |
10
+
|---------|-------------|----------|
11
+
| **Hypergoat** | Go ATProto AppView that indexes Lexicon-defined records and exposes them via GraphQL | [hypergoat.vercel.app](https://hypergoat.vercel.app) |
12
+
| **Impact Indexer** | Data explorer - Real-time visualization of indexed data | [impactindexer.org](https://impactindexer.org) |
13
+
14
+
### Live Services
15
+
16
+
- **Hypergoat GraphQL API**: https://hypergoat.vercel.app/graphql
17
+
- **Hypergoat GraphiQL**: https://hypergoat.vercel.app/graphiql
18
+
- **Impact Indexer**: https://impactindexer.org
19
+
- **Lexicon Reference**: https://impactindexer.org/lexicon
20
+
21
+
## Governance Processes
22
+
23
+
### Lexicon Indexing Request (LIR)
24
+
25
+
A **LIR** is a formal proposal to add a new Lexicon to the indexing infrastructure. This includes:
26
+
27
+
1. Adding the lexicon to Hypergoat for indexing
28
+
2. Updating Impact Indexer documentation and visualization
29
+
30
+
**Quick Links:**
31
+
- [LIR Template](./templates/LIR-TEMPLATE.md) - Start a new request
32
+
- [Governance Process](./GOVERNANCE.md) - Full process documentation
33
+
- [Example LIR](./lirs/LIR-0000-example.md) - See a completed example
34
+
35
+
### How to Submit a LIR
36
+
37
+
#### Option 1: GitHub Issue (Recommended)
38
+
39
+
1. Go to [Issues](../../issues) and click "New Issue"
40
+
2. Select "Lexicon Indexing Request"
41
+
3. Fill out the form
42
+
43
+
#### Option 2: Pull Request
44
+
45
+
1. Copy `templates/LIR-TEMPLATE.md` to `lirs/LIR-XXXX-your-title.md`
46
+
2. Fill out all sections
47
+
3. Submit a PR
48
+
49
+
## Directory Structure
50
+
51
+
```
52
+
hypercollective/
53
+
├── README.md # This file
54
+
├── GOVERNANCE.md # LIR process & decision criteria
55
+
├── templates/
56
+
│ └── LIR-TEMPLATE.md # Blank LIR template
57
+
└── lirs/
58
+
└── LIR-0000-example.md # Example LIR
59
+
```
60
+
61
+
## Related Repositories
62
+
63
+
| Repository | Purpose |
64
+
|------------|---------|
65
+
| [GainForest/lexicons](https://github.com/GainForest/lexicons) | GainForest ATProto lexicon schemas |
66
+
| [hypercerts-org/hypercerts-lexicon](https://github.com/hypercerts-org/hypercerts-lexicon) | Hypercerts protocol lexicon schemas |
67
+
| [hypercollective](https://tangled.org/gainforest.earth/hypercollective) | This repository - governance & feature requests |
68
+
69
+
## Contributing Organizations
70
+
71
+
- [GainForest](https://gainforest.earth) - Environmental impact & biodiversity
72
+
- [Hypercerts](https://hypercerts.org) - Impact certification protocol
73
+
- [Ma Earth](https://maearth.com) - Regenerative land funding & education
74
+
75
+
## Resources
76
+
77
+
- [AT Protocol Documentation](https://atproto.com/docs)
78
+
79
+
## License
80
+
81
+
This repository is licensed under the Apache License 2.0.
+311
lirs/LIR-0000-example.md
+311
lirs/LIR-0000-example.md
···
1
+
# LIR-0000: Darwin Core Occurrence Records (Example)
2
+
3
+
| Field | Value |
4
+
|-------|-------|
5
+
| **LIR Number** | 0000 |
6
+
| **Title** | Darwin Core Occurrence Records |
7
+
| **Author** | GainForest Team |
8
+
| **Status** | Implemented |
9
+
| **Created** | 2024-06-01 |
10
+
| **Updated** | 2024-06-15 |
11
+
12
+
> **Note**: This is an example LIR to demonstrate the format. LIR-0000 is reserved for documentation purposes.
13
+
14
+
---
15
+
16
+
## Abstract
17
+
18
+
Add support for indexing Darwin Core occurrence records (`app.gainforest.dwc.occurrence`) in Hypergoat. This lexicon represents biodiversity observations including species sightings, bioacoustic recordings, and environmental monitoring data. Indexing this data enables real-time biodiversity monitoring and conservation impact tracking.
19
+
20
+
---
21
+
22
+
## Motivation
23
+
24
+
### Problem Statement
25
+
26
+
Biodiversity data is fragmented across multiple centralized databases (GBIF, iNaturalist, eBird). Researchers and conservationists need a decentralized way to publish and query species occurrence data that:
27
+
28
+
- Maintains data sovereignty for indigenous communities
29
+
- Enables real-time streaming of observations
30
+
- Supports multimedia (audio, images, video)
31
+
- Integrates with the AT Protocol identity system
32
+
33
+
### Who Benefits
34
+
35
+
- **Conservation organizations** - Track species populations in real-time
36
+
- **Researchers** - Query biodiversity data via GraphQL
37
+
- **Field workers** - Publish observations from remote locations
38
+
- **AI systems** - Process real-time species detection data
39
+
40
+
### Use Cases
41
+
42
+
1. **Bioacoustic monitoring** - Stream audio detections from forest sensors
43
+
2. **Camera trap data** - Publish wildlife imagery with species classifications
44
+
3. **Community science** - Enable decentralized species reporting
45
+
4. **Impact verification** - Prove conservation outcomes on-chain
46
+
47
+
### Existing Adoption
48
+
49
+
- GainForest has deployed 50+ acoustic sensors using this lexicon
50
+
- Over 100,000 occurrence records already published to AT Protocol
51
+
- Multiple conservation partners actively using the format
52
+
53
+
---
54
+
55
+
## Lexicon Specification
56
+
57
+
### NSID
58
+
59
+
```
60
+
app.gainforest.dwc.occurrence
61
+
```
62
+
63
+
### Schema Reference
64
+
65
+
Based on [Darwin Core Standard](https://dwc.tdwg.org/) with AT Protocol adaptations.
66
+
67
+
### Full Schema
68
+
69
+
```json
70
+
{
71
+
"lexicon": 1,
72
+
"id": "app.gainforest.dwc.occurrence",
73
+
"defs": {
74
+
"main": {
75
+
"type": "record",
76
+
"description": "A Darwin Core occurrence record representing a species observation",
77
+
"key": "tid",
78
+
"record": {
79
+
"type": "object",
80
+
"required": ["scientificName", "eventDate"],
81
+
"properties": {
82
+
"occurrenceID": {
83
+
"type": "string",
84
+
"description": "Unique identifier for this occurrence"
85
+
},
86
+
"scientificName": {
87
+
"type": "string",
88
+
"description": "Scientific name of the observed taxon"
89
+
},
90
+
"vernacularName": {
91
+
"type": "string",
92
+
"description": "Common name of the species"
93
+
},
94
+
"eventDate": {
95
+
"type": "string",
96
+
"format": "datetime",
97
+
"description": "Date/time of the observation"
98
+
},
99
+
"decimalLatitude": {
100
+
"type": "number",
101
+
"description": "Latitude in decimal degrees"
102
+
},
103
+
"decimalLongitude": {
104
+
"type": "number",
105
+
"description": "Longitude in decimal degrees"
106
+
},
107
+
"country": {
108
+
"type": "string",
109
+
"description": "Country where observation occurred"
110
+
},
111
+
"locality": {
112
+
"type": "string",
113
+
"description": "Specific location description"
114
+
},
115
+
"basisOfRecord": {
116
+
"type": "string",
117
+
"description": "Type of evidence (HumanObservation, MachineObservation, etc.)"
118
+
},
119
+
"media": {
120
+
"type": "array",
121
+
"items": {
122
+
"type": "ref",
123
+
"ref": "#mediaItem"
124
+
},
125
+
"description": "Associated media files"
126
+
},
127
+
"identificationRemarks": {
128
+
"type": "string",
129
+
"description": "Notes on species identification"
130
+
},
131
+
"confidence": {
132
+
"type": "number",
133
+
"minimum": 0,
134
+
"maximum": 1,
135
+
"description": "Confidence score for ML-based identifications"
136
+
}
137
+
}
138
+
}
139
+
},
140
+
"mediaItem": {
141
+
"type": "object",
142
+
"required": ["type", "url"],
143
+
"properties": {
144
+
"type": {
145
+
"type": "string",
146
+
"knownValues": ["audio", "image", "video", "spectrogram"]
147
+
},
148
+
"url": {
149
+
"type": "string",
150
+
"format": "uri"
151
+
},
152
+
"mimeType": {
153
+
"type": "string"
154
+
}
155
+
}
156
+
}
157
+
}
158
+
}
159
+
```
160
+
161
+
### Example Record
162
+
163
+
```json
164
+
{
165
+
"$type": "app.gainforest.dwc.occurrence",
166
+
"occurrenceID": "GF-2024-001234",
167
+
"scientificName": "Panthera onca",
168
+
"vernacularName": "Jaguar",
169
+
"eventDate": "2024-06-15T08:30:00.000Z",
170
+
"decimalLatitude": -3.4653,
171
+
"decimalLongitude": -62.2159,
172
+
"country": "Brazil",
173
+
"locality": "Uatumã Biological Reserve",
174
+
"basisOfRecord": "MachineObservation",
175
+
"media": [
176
+
{
177
+
"type": "image",
178
+
"url": "https://cdn.gainforest.earth/occurrences/jaguar-001234.jpg",
179
+
"mimeType": "image/jpeg"
180
+
}
181
+
],
182
+
"confidence": 0.94,
183
+
"identificationRemarks": "Identified by camera trap AI model v2.1"
184
+
}
185
+
```
186
+
187
+
---
188
+
189
+
## Hypergoat Changes
190
+
191
+
- [x] Upload lexicon schema
192
+
- [x] Configure Jetstream subscription for `app.gainforest.dwc.occurrence`
193
+
- [x] Trigger backfill for existing records
194
+
- [x] No custom indexing requirements
195
+
196
+
### Expected Query Patterns
197
+
198
+
1. **By location** - Occurrences within geographic bounds
199
+
2. **By species** - Filter by `scientificName`
200
+
3. **By time range** - Recent observations
201
+
4. **By author** - Records from specific observers/sensors
202
+
5. **Aggregations** - Species counts by location
203
+
204
+
---
205
+
206
+
## Impact Indexer Changes
207
+
208
+
- [x] Add to Lexicon Reference page at `/lexicon/app.gainforest.dwc.occurrence`
209
+
- [x] Create Occurrence Feed component with map visualization
210
+
- [x] Add audio waveform player for bioacoustic recordings
211
+
- [x] Update `/feed` page to include occurrence stream
212
+
213
+
---
214
+
215
+
## Example Queries
216
+
217
+
### Fetch Recent Occurrences
218
+
219
+
```graphql
220
+
query GetRecentOccurrences {
221
+
appGainforestDwcOccurrence(first: 20) {
222
+
edges {
223
+
node {
224
+
uri
225
+
did
226
+
scientificName
227
+
vernacularName
228
+
eventDate
229
+
decimalLatitude
230
+
decimalLongitude
231
+
media {
232
+
type
233
+
url
234
+
}
235
+
}
236
+
}
237
+
pageInfo {
238
+
hasNextPage
239
+
endCursor
240
+
}
241
+
}
242
+
}
243
+
```
244
+
245
+
### Fetch by Species
246
+
247
+
```graphql
248
+
query GetJaguarSightings {
249
+
appGainforestDwcOccurrence(
250
+
where: { scientificName: { eq: "Panthera onca" } }
251
+
first: 50
252
+
) {
253
+
edges {
254
+
node {
255
+
uri
256
+
eventDate
257
+
decimalLatitude
258
+
decimalLongitude
259
+
locality
260
+
confidence
261
+
}
262
+
}
263
+
totalCount
264
+
}
265
+
}
266
+
```
267
+
268
+
### Subscribe to New Occurrences
269
+
270
+
```graphql
271
+
subscription OnNewOccurrence {
272
+
recordCreated(collection: "app.gainforest.dwc.occurrence") {
273
+
uri
274
+
did
275
+
record
276
+
createdAt
277
+
}
278
+
}
279
+
```
280
+
281
+
---
282
+
283
+
## Security Considerations
284
+
285
+
- **Location sensitivity**: Some species locations may need to be fuzzed to prevent poaching
286
+
- **No PII**: Occurrence records do not contain personal information
287
+
- **Public data**: All occurrence data is intended to be publicly accessible
288
+
289
+
---
290
+
291
+
## Backwards Compatibility
292
+
293
+
This is a new lexicon with no backwards compatibility concerns.
294
+
295
+
---
296
+
297
+
## References
298
+
299
+
- [Darwin Core Standard](https://dwc.tdwg.org/)
300
+
- [GainForest Documentation](https://docs.gainforest.earth/)
301
+
- [AT Protocol Lexicon Spec](https://atproto.com/specs/lexicon)
302
+
303
+
---
304
+
305
+
## Changelog
306
+
307
+
| Date | Change |
308
+
|------|--------|
309
+
| 2024-06-01 | Initial draft |
310
+
| 2024-06-10 | Added media support |
311
+
| 2024-06-15 | Implemented and deployed |
+230
lirs/LIR-0001-gainforest-lexicons.md
+230
lirs/LIR-0001-gainforest-lexicons.md
···
1
+
# LIR-0001: GainForest Lexicons
2
+
3
+
| Field | Value |
4
+
|-------|-------|
5
+
| **LIR Number** | 0001 |
6
+
| **Title** | GainForest Lexicons |
7
+
| **Author** | GainForest Team |
8
+
| **Status** | Implemented |
9
+
| **Created** | 2024-01-01 |
10
+
| **Updated** | 2025-01-29 |
11
+
12
+
> **Note**: This is a retroactive LIR documenting the GainForest lexicons that are already indexed in Hypergoat.
13
+
14
+
---
15
+
16
+
## Abstract
17
+
18
+
Index the core GainForest lexicons (`app.gainforest.*`) in Hypergoat. These lexicons define biodiversity records (Darwin Core), decentralized evaluator services, and organization data structures used throughout the Hypersphere ecosystem for environmental impact tracking.
19
+
20
+
---
21
+
22
+
## Motivation
23
+
24
+
### Problem Statement
25
+
26
+
Environmental and biodiversity data is fragmented across centralized platforms. GainForest needs a decentralized infrastructure to:
27
+
28
+
- Publish biodiversity observations with full provenance
29
+
- Enable AI/human evaluator services to annotate data
30
+
- Track conservation organizations and their activities
31
+
- Maintain data sovereignty for indigenous communities
32
+
33
+
### Who Benefits
34
+
35
+
- **Conservation organizations** - Publish and track biodiversity data
36
+
- **Researchers** - Query standardized Darwin Core records via GraphQL
37
+
- **AI systems** - Process and evaluate biodiversity observations
38
+
- **Field workers** - Record observations with proper attribution
39
+
40
+
### Use Cases
41
+
42
+
1. **Biodiversity monitoring** - Darwin Core occurrence records for species observations
43
+
2. **Quality assessment** - Evaluator services that annotate records with confidence scores
44
+
3. **Organization profiles** - Track conservation projects and their data layers
45
+
4. **Acoustic monitoring** - Store and query bioacoustic recordings
46
+
47
+
### Existing Adoption
48
+
49
+
- GainForest production systems actively publishing to these lexicons
50
+
- Hundreds of thousands of occurrence records indexed
51
+
- Multiple conservation partners using the infrastructure
52
+
53
+
---
54
+
55
+
## Lexicon Specification
56
+
57
+
### NSIDs
58
+
59
+
The GainForest lexicons span multiple namespaces:
60
+
61
+
| Namespace | Description |
62
+
|-----------|-------------|
63
+
| `app.gainforest.common.*` | Shared definitions (blobs, images, URIs) |
64
+
| `app.gainforest.dwc.*` | Darwin Core biodiversity records |
65
+
| `app.gainforest.evaluator.*` | Decentralized evaluator services |
66
+
| `app.gainforest.organization.*` | Organization profiles and data |
67
+
68
+
### Schema Reference
69
+
70
+
Full schemas available at: https://github.com/GainForest/lexicons
71
+
72
+
### Key Record Types
73
+
74
+
#### Darwin Core (`app.gainforest.dwc`)
75
+
76
+
| Lexicon | Type | Description |
77
+
|---------|------|-------------|
78
+
| `dwc.event` | record | Sampling/collecting event with location and protocol |
79
+
| `dwc.occurrence` | record | Single organism observation at a place and time |
80
+
| `dwc.measurement` | record | Measurements linked to an occurrence |
81
+
82
+
#### Evaluator (`app.gainforest.evaluator`)
83
+
84
+
| Lexicon | Type | Description |
85
+
|---------|------|-------------|
86
+
| `evaluator.service` | record | Declaration registering an account as an evaluator |
87
+
| `evaluator.evaluation` | record | Evaluation result with typed results and confidence |
88
+
| `evaluator.subscription` | record | User subscribes to an evaluator's outputs |
89
+
90
+
#### Organization (`app.gainforest.organization`)
91
+
92
+
| Lexicon | Type | Description |
93
+
|---------|------|-------------|
94
+
| `organization.info` | record | Organization profile information |
95
+
| `organization.defaultSite` | record | Default site configuration |
96
+
| `organization.layer` | record | Map layer definitions |
97
+
| `observations/*` | record | Various observation types (dendogram, fauna, flora) |
98
+
| `predictions/*` | record | Prediction records |
99
+
100
+
### Example Record (Darwin Core Occurrence)
101
+
102
+
```json
103
+
{
104
+
"$type": "app.gainforest.dwc.occurrence",
105
+
"basisOfRecord": "HumanObservation",
106
+
"scientificName": "Panthera onca",
107
+
"vernacularName": "Jaguar",
108
+
"eventDate": "2024-06-15T08:30:00.000Z",
109
+
"decimalLatitude": -3.4653,
110
+
"decimalLongitude": -62.2159,
111
+
"country": "Brazil",
112
+
"locality": "Uatumã Biological Reserve",
113
+
"occurrenceStatus": "present",
114
+
"createdAt": "2024-06-15T08:30:00.000Z"
115
+
}
116
+
```
117
+
118
+
---
119
+
120
+
## Hypergoat Changes
121
+
122
+
- [x] Upload all GainForest lexicon schemas
123
+
- [x] Configure Jetstream subscription for all collections
124
+
- [x] Trigger backfill for historical data
125
+
- [x] Generate GraphQL types dynamically from schemas
126
+
127
+
### Expected Query Patterns
128
+
129
+
- By species (`scientificName`)
130
+
- By location (coordinates, country, locality)
131
+
- By time range (`eventDate`)
132
+
- By organization
133
+
- By evaluator (for evaluation records)
134
+
135
+
---
136
+
137
+
## Impact Indexer Changes
138
+
139
+
- [x] Add GainForest lexicons to Lexicon Reference at `/lexicon`
140
+
- [x] Create occurrence feed visualization with map
141
+
- [x] Add audio waveform player for bioacoustic recordings
142
+
- [x] Display evaluator service information
143
+
144
+
---
145
+
146
+
## Example Queries
147
+
148
+
### Fetch Recent Occurrences
149
+
150
+
```graphql
151
+
query GetRecentOccurrences {
152
+
appGainforestDwcOccurrence(first: 20) {
153
+
edges {
154
+
node {
155
+
uri
156
+
did
157
+
scientificName
158
+
vernacularName
159
+
eventDate
160
+
decimalLatitude
161
+
decimalLongitude
162
+
}
163
+
}
164
+
}
165
+
}
166
+
```
167
+
168
+
### Fetch Evaluations for a Record
169
+
170
+
```graphql
171
+
query GetEvaluations($subjectUri: String!) {
172
+
appGainforestEvaluatorEvaluation(
173
+
where: { subject: { uri: { eq: $subjectUri } } }
174
+
) {
175
+
edges {
176
+
node {
177
+
uri
178
+
did
179
+
evaluationType
180
+
confidence
181
+
result
182
+
}
183
+
}
184
+
}
185
+
}
186
+
```
187
+
188
+
### Subscribe to New Occurrences
189
+
190
+
```graphql
191
+
subscription OnNewOccurrence {
192
+
recordCreated(collection: "app.gainforest.dwc.occurrence") {
193
+
uri
194
+
did
195
+
record
196
+
createdAt
197
+
}
198
+
}
199
+
```
200
+
201
+
---
202
+
203
+
## Security Considerations
204
+
205
+
- Location data for endangered species may need coordinate fuzzing
206
+
- Organization data is public by design
207
+
- Evaluator results are attributed to their source DID
208
+
209
+
---
210
+
211
+
## Backwards Compatibility
212
+
213
+
These are established lexicons with existing data. No breaking changes.
214
+
215
+
---
216
+
217
+
## References
218
+
219
+
- [GainForest Lexicons Repository](https://github.com/GainForest/lexicons)
220
+
- [Darwin Core Standard](https://dwc.tdwg.org/)
221
+
- [AT Protocol Lexicon Spec](https://atproto.com/specs/lexicon)
222
+
223
+
---
224
+
225
+
## Changelog
226
+
227
+
| Date | Change |
228
+
|------|--------|
229
+
| 2024-01-01 | Initial implementation |
230
+
| 2025-01-29 | Retroactive LIR documentation |
+309
lirs/LIR-0002-impactindexer-review.md
+309
lirs/LIR-0002-impactindexer-review.md
···
1
+
# LIR-0002: Impact Indexer Review System
2
+
3
+
| Field | Value |
4
+
|-------|-------|
5
+
| **LIR Number** | 0002 |
6
+
| **Title** | Impact Indexer Review System |
7
+
| **Author** | GainForest Team |
8
+
| **Status** | Implemented |
9
+
| **Created** | 2025-01-26 |
10
+
| **Updated** | 2025-01-29 |
11
+
12
+
> **Note**: This is a retroactive LIR documenting the Impact Indexer review lexicons that are now indexed in Hypergoat.
13
+
14
+
---
15
+
16
+
## Abstract
17
+
18
+
Index the Impact Indexer review lexicons (`org.impactindexer.review.*`) in Hypergoat. These lexicons enable a decentralized review system where users can comment on and like AT-Proto entities including records, users, PDSes, and lexicons. This enables community engagement and feedback directly on [impactindexer.org](https://impactindexer.org).
19
+
20
+
---
21
+
22
+
## Motivation
23
+
24
+
### Problem Statement
25
+
26
+
The Hypersphere Explorer (Impact Indexer) displays records from across the AT Protocol network, but users have no way to:
27
+
28
+
- Leave feedback or comments on records they view
29
+
- Like or endorse high-quality data
30
+
- Discuss lexicon schemas and their usage
31
+
- Provide reviews of PDS providers
32
+
33
+
### Who Benefits
34
+
35
+
- **Data consumers** - Leave feedback on records they use
36
+
- **Data publishers** - Receive community validation
37
+
- **Researchers** - Discuss methodology via comments
38
+
- **Developers** - Review and discuss lexicon designs
39
+
40
+
### Use Cases
41
+
42
+
1. **Record feedback** - Comment on biodiversity occurrences with corrections or additional context
43
+
2. **User endorsement** - Like profiles of trusted data contributors
44
+
3. **PDS reviews** - Community feedback on PDS reliability
45
+
4. **Lexicon discussion** - Comments on schema design decisions
46
+
47
+
### Existing Adoption
48
+
49
+
- New lexicons created for Impact Indexer v2
50
+
- Review UI implemented at impactindexer.org/review
51
+
52
+
---
53
+
54
+
## Lexicon Specification
55
+
56
+
### NSIDs
57
+
58
+
```
59
+
org.impactindexer.review.defs
60
+
org.impactindexer.review.comment
61
+
org.impactindexer.review.like
62
+
```
63
+
64
+
### Schema Reference
65
+
66
+
Full schemas at: https://github.com/GainForest/lexicons/tree/main/lexicons/org/impactindexer/review
67
+
68
+
### Full Schemas
69
+
70
+
#### Shared Definitions (`org.impactindexer.review.defs`)
71
+
72
+
```json
73
+
{
74
+
"lexicon": 1,
75
+
"id": "org.impactindexer.review.defs",
76
+
"defs": {
77
+
"subjectType": {
78
+
"type": "string",
79
+
"knownValues": ["record", "user", "pds", "lexicon"]
80
+
},
81
+
"subjectRef": {
82
+
"type": "object",
83
+
"required": ["uri", "type"],
84
+
"properties": {
85
+
"uri": { "type": "string", "maxLength": 8192 },
86
+
"type": { "type": "ref", "ref": "#subjectType" },
87
+
"cid": { "type": "string", "maxLength": 128 }
88
+
}
89
+
}
90
+
}
91
+
}
92
+
```
93
+
94
+
#### Comment (`org.impactindexer.review.comment`)
95
+
96
+
```json
97
+
{
98
+
"lexicon": 1,
99
+
"id": "org.impactindexer.review.comment",
100
+
"defs": {
101
+
"main": {
102
+
"type": "record",
103
+
"key": "tid",
104
+
"record": {
105
+
"type": "object",
106
+
"required": ["subject", "text", "createdAt"],
107
+
"properties": {
108
+
"subject": { "type": "ref", "ref": "org.impactindexer.review.defs#subjectRef" },
109
+
"text": { "type": "string", "maxLength": 20480, "maxGraphemes": 6000 },
110
+
"replyTo": { "type": "string", "format": "at-uri" },
111
+
"createdAt": { "type": "string", "format": "datetime" }
112
+
}
113
+
}
114
+
}
115
+
}
116
+
}
117
+
```
118
+
119
+
#### Like (`org.impactindexer.review.like`)
120
+
121
+
```json
122
+
{
123
+
"lexicon": 1,
124
+
"id": "org.impactindexer.review.like",
125
+
"defs": {
126
+
"main": {
127
+
"type": "record",
128
+
"key": "tid",
129
+
"record": {
130
+
"type": "object",
131
+
"required": ["subject", "createdAt"],
132
+
"properties": {
133
+
"subject": { "type": "ref", "ref": "org.impactindexer.review.defs#subjectRef" },
134
+
"createdAt": { "type": "string", "format": "datetime" }
135
+
}
136
+
}
137
+
}
138
+
}
139
+
}
140
+
```
141
+
142
+
### Example Records
143
+
144
+
#### Comment on a Record
145
+
146
+
```json
147
+
{
148
+
"$type": "org.impactindexer.review.comment",
149
+
"subject": {
150
+
"uri": "at://did:plc:abc123/app.gainforest.dwc.occurrence/3lbq...",
151
+
"type": "record"
152
+
},
153
+
"text": "Great observation! The coordinates match the known range for this species.",
154
+
"createdAt": "2025-01-26T10:30:00.000Z"
155
+
}
156
+
```
157
+
158
+
#### Like on a User
159
+
160
+
```json
161
+
{
162
+
"$type": "org.impactindexer.review.like",
163
+
"subject": {
164
+
"uri": "did:plc:trusted-contributor",
165
+
"type": "user"
166
+
},
167
+
"createdAt": "2025-01-26T10:30:00.000Z"
168
+
}
169
+
```
170
+
171
+
#### Comment on a Lexicon
172
+
173
+
```json
174
+
{
175
+
"$type": "org.impactindexer.review.comment",
176
+
"subject": {
177
+
"uri": "app.gainforest.dwc.occurrence",
178
+
"type": "lexicon"
179
+
},
180
+
"text": "Would be great to add support for `occurrenceEvidence` field from DwC.",
181
+
"createdAt": "2025-01-26T10:30:00.000Z"
182
+
}
183
+
```
184
+
185
+
---
186
+
187
+
## Hypergoat Changes
188
+
189
+
- [x] Upload review lexicon schemas
190
+
- [x] Configure Jetstream subscription for `org.impactindexer.review.*`
191
+
- [x] No backfill needed (new lexicons)
192
+
193
+
### Expected Query Patterns
194
+
195
+
- Comments/likes by subject URI
196
+
- Comments/likes by author DID
197
+
- Threaded comment replies (via `replyTo`)
198
+
- Like counts per subject
199
+
- Recent activity feed
200
+
201
+
---
202
+
203
+
## Impact Indexer Changes
204
+
205
+
- [x] Add review lexicons to Lexicon Reference at `/lexicon/org.impactindexer.review.*`
206
+
- [x] Create review UI at `/review`
207
+
- [x] Display comment counts and like counts on records
208
+
- [x] Enable inline commenting on record detail pages
209
+
210
+
---
211
+
212
+
## Example Queries
213
+
214
+
### Fetch Comments for a Record
215
+
216
+
```graphql
217
+
query GetComments($subjectUri: String!) {
218
+
orgImpactindexerReviewComment(
219
+
where: { subject: { uri: { eq: $subjectUri } } }
220
+
first: 50
221
+
) {
222
+
edges {
223
+
node {
224
+
uri
225
+
did
226
+
text
227
+
replyTo
228
+
createdAt
229
+
}
230
+
}
231
+
totalCount
232
+
}
233
+
}
234
+
```
235
+
236
+
### Fetch Like Count for a Subject
237
+
238
+
```graphql
239
+
query GetLikeCount($subjectUri: String!) {
240
+
orgImpactindexerReviewLike(
241
+
where: { subject: { uri: { eq: $subjectUri } } }
242
+
) {
243
+
totalCount
244
+
}
245
+
}
246
+
```
247
+
248
+
### Check if User Liked a Subject
249
+
250
+
```graphql
251
+
query DidUserLike($subjectUri: String!, $userDid: String!) {
252
+
orgImpactindexerReviewLike(
253
+
where: {
254
+
subject: { uri: { eq: $subjectUri } }
255
+
did: { eq: $userDid }
256
+
}
257
+
) {
258
+
edges {
259
+
node {
260
+
uri
261
+
}
262
+
}
263
+
}
264
+
}
265
+
```
266
+
267
+
### Subscribe to New Comments
268
+
269
+
```graphql
270
+
subscription OnNewComment {
271
+
recordCreated(collection: "org.impactindexer.review.comment") {
272
+
uri
273
+
did
274
+
record
275
+
createdAt
276
+
}
277
+
}
278
+
```
279
+
280
+
---
281
+
282
+
## Security Considerations
283
+
284
+
- Comments are public and attributed to the author's DID
285
+
- No moderation system yet (future enhancement)
286
+
- One like per subject per user (enforced by rkey uniqueness)
287
+
288
+
---
289
+
290
+
## Backwards Compatibility
291
+
292
+
New lexicons with no backwards compatibility concerns.
293
+
294
+
---
295
+
296
+
## References
297
+
298
+
- [GainForest Lexicons - Review](https://github.com/GainForest/lexicons/tree/main/lexicons/org/impactindexer/review)
299
+
- [Impact Indexer](https://impactindexer.org)
300
+
- [AT Protocol Lexicon Spec](https://atproto.com/specs/lexicon)
301
+
302
+
---
303
+
304
+
## Changelog
305
+
306
+
| Date | Change |
307
+
|------|--------|
308
+
| 2025-01-26 | Initial implementation |
309
+
| 2025-01-29 | Retroactive LIR documentation |
+380
lirs/LIR-0003-hypercerts-lexicons.md
+380
lirs/LIR-0003-hypercerts-lexicons.md
···
1
+
# LIR-0003: Hypercerts Lexicons
2
+
3
+
| Field | Value |
4
+
|-------|-------|
5
+
| **LIR Number** | 0003 |
6
+
| **Title** | Hypercerts Lexicons |
7
+
| **Author** | Hypercerts Organization |
8
+
| **Status** | Implemented |
9
+
| **Created** | 2024-01-01 |
10
+
| **Updated** | 2025-01-29 |
11
+
12
+
> **Note**: This is a retroactive LIR documenting the Hypercerts lexicons that are already indexed in Hypergoat.
13
+
14
+
---
15
+
16
+
## Abstract
17
+
18
+
Index the Hypercerts protocol lexicons (`org.hypercerts.*` and `app.certified.*`) in Hypergoat. These lexicons define the core data structures for tracking impact work, contributions, evaluations, measurements, and funding in the Hypercerts v0.2 protocol on AT Protocol.
19
+
20
+
---
21
+
22
+
## Motivation
23
+
24
+
### Problem Statement
25
+
26
+
Impact certification and funding attribution lack standardized, decentralized infrastructure. Hypercerts provides a protocol for:
27
+
28
+
- Recording and certifying impact work with proper attribution
29
+
- Tracking contributions from multiple parties with weights
30
+
- Evaluating and measuring impact outcomes
31
+
- Managing rights and funding flows
32
+
- Supporting location-based and badge-based attestations
33
+
34
+
### Who Benefits
35
+
36
+
- **Impact creators** - Record verifiable impact work claims
37
+
- **Funders** - Track funding contributions and receipts
38
+
- **Evaluators** - Provide assessments of impact claims
39
+
- **Projects** - Organize activities into collections with proper attribution
40
+
- **Researchers** - Query standardized impact data via GraphQL
41
+
42
+
### Use Cases
43
+
44
+
1. **Impact certification** - Create hypercert activity records with contributor attribution
45
+
2. **Project organization** - Group activities into collections/projects
46
+
3. **Impact evaluation** - Third-party assessments with scores and measurements
47
+
4. **Funding tracking** - Record funding receipts and attribution
48
+
5. **Badge systems** - Award and display achievement badges
49
+
50
+
### Existing Adoption
51
+
52
+
- Hypercerts protocol in production use
53
+
- Multiple organizations publishing impact claims
54
+
- Active development at [hypercerts-org/hypercerts-lexicon](https://github.com/hypercerts-org/hypercerts-lexicon)
55
+
56
+
---
57
+
58
+
## Lexicon Specification
59
+
60
+
### NSIDs
61
+
62
+
The Hypercerts lexicons span multiple namespaces:
63
+
64
+
| Namespace | Description |
65
+
|-----------|-------------|
66
+
| `org.hypercerts.claim.*` | Core claim records (activities, collections, evaluations, etc.) |
67
+
| `org.hypercerts.funding.*` | Funding-related records |
68
+
| `org.hypercerts.helper.*` | Helper records (work scope tags) |
69
+
| `app.certified.*` | Shared certified lexicons (locations, badges) |
70
+
71
+
### Schema Reference
72
+
73
+
Full schemas available at: https://github.com/hypercerts-org/hypercerts-lexicon
74
+
75
+
NPM package: `@hypercerts-org/lexicon`
76
+
77
+
### Key Record Types
78
+
79
+
#### Claims (`org.hypercerts.claim`)
80
+
81
+
| Lexicon | Type | Description |
82
+
|---------|------|-------------|
83
+
| `claim.activity` | record | A hypercert record tracking impact work |
84
+
| `claim.collection` | record | Collection/group of items (activities and/or other collections) |
85
+
| `claim.attachment` | record | Commentary, context, evidence, or documentary material |
86
+
| `claim.contributorInformation` | record | Contributor identity, display name, and image |
87
+
| `claim.contributionDetails` | record | Contribution role, description, and timeframe |
88
+
| `claim.evaluation` | record | Evaluation of a hypercert record with scores |
89
+
| `claim.measurement` | record | Measurement data related to impact |
90
+
| `claim.rights` | record | Rights definitions (transferability, conditions) |
91
+
92
+
#### Funding (`org.hypercerts.funding`)
93
+
94
+
| Lexicon | Type | Description |
95
+
|---------|------|-------------|
96
+
| `funding.receipt` | record | Funding receipt for a payment between users |
97
+
98
+
#### Helper (`org.hypercerts.helper`)
99
+
100
+
| Lexicon | Type | Description |
101
+
|---------|------|-------------|
102
+
| `helper.workScopeTag` | record | Reusable scope atom for work scope expressions |
103
+
104
+
#### Certified (`app.certified`)
105
+
106
+
| Lexicon | Type | Description |
107
+
|---------|------|-------------|
108
+
| `certified.location` | record | Geographic location reference with SRS |
109
+
| `certified.badge.definition` | record | Badge type definition |
110
+
| `certified.badge.award` | record | Badge awarded to a subject |
111
+
| `certified.badge.response` | record | Response to a badge award |
112
+
113
+
### Example Records
114
+
115
+
#### Activity (Hypercert)
116
+
117
+
```json
118
+
{
119
+
"$type": "org.hypercerts.claim.activity",
120
+
"title": "Reforestation Project Q1 2024",
121
+
"shortDescription": "Planted 10,000 native trees in degraded forest areas",
122
+
"workScope": "Environmental conservation",
123
+
"startDate": "2024-01-01T00:00:00Z",
124
+
"endDate": "2024-03-31T23:59:59Z",
125
+
"contributors": [
126
+
{
127
+
"contributorIdentity": "did:plc:contributor1",
128
+
"contributionWeight": "0.6",
129
+
"contributionDetails": "Project lead and coordination"
130
+
},
131
+
{
132
+
"contributorIdentity": "did:plc:contributor2",
133
+
"contributionWeight": "0.4",
134
+
"contributionDetails": "Field operations"
135
+
}
136
+
],
137
+
"createdAt": "2024-04-01T10:00:00.000Z"
138
+
}
139
+
```
140
+
141
+
#### Collection (Project)
142
+
143
+
```json
144
+
{
145
+
"$type": "org.hypercerts.claim.collection",
146
+
"type": "project",
147
+
"title": "Climate Action Initiative 2024",
148
+
"shortDescription": "A comprehensive climate action program",
149
+
"items": [
150
+
{
151
+
"itemIdentifier": {
152
+
"uri": "at://did:plc:alice/org.hypercerts.claim.activity/abc123",
153
+
"cid": "..."
154
+
},
155
+
"itemWeight": "0.5"
156
+
},
157
+
{
158
+
"itemIdentifier": {
159
+
"uri": "at://did:plc:bob/org.hypercerts.claim.activity/def456",
160
+
"cid": "..."
161
+
},
162
+
"itemWeight": "0.5"
163
+
}
164
+
],
165
+
"createdAt": "2024-04-01T10:00:00.000Z"
166
+
}
167
+
```
168
+
169
+
#### Evaluation
170
+
171
+
```json
172
+
{
173
+
"$type": "org.hypercerts.claim.evaluation",
174
+
"subject": {
175
+
"uri": "at://did:plc:alice/org.hypercerts.claim.activity/abc123",
176
+
"cid": "..."
177
+
},
178
+
"evaluators": ["did:plc:evaluator1"],
179
+
"summary": "Verified impact through satellite imagery and field visits",
180
+
"score": {
181
+
"min": 1,
182
+
"max": 5,
183
+
"value": 4
184
+
},
185
+
"createdAt": "2024-05-01T10:00:00.000Z"
186
+
}
187
+
```
188
+
189
+
#### Funding Receipt
190
+
191
+
```json
192
+
{
193
+
"$type": "org.hypercerts.funding.receipt",
194
+
"from": { "did": "did:plc:funder" },
195
+
"to": "Climate Action Initiative",
196
+
"amount": "10000",
197
+
"currency": "USD",
198
+
"paymentRail": "onchain",
199
+
"paymentNetwork": "ethereum",
200
+
"transactionId": "0x123...",
201
+
"for": "at://did:plc:alice/org.hypercerts.claim.collection/project1",
202
+
"occurredAt": "2024-03-15T14:30:00.000Z",
203
+
"createdAt": "2024-03-15T14:35:00.000Z"
204
+
}
205
+
```
206
+
207
+
---
208
+
209
+
## Hypergoat Changes
210
+
211
+
- [x] Upload all Hypercerts lexicon schemas
212
+
- [x] Configure Jetstream subscription for all collections
213
+
- [x] Trigger backfill for historical data
214
+
- [x] Generate GraphQL types dynamically from schemas
215
+
216
+
### Expected Query Patterns
217
+
218
+
- Activities by contributor (DID)
219
+
- Activities by time range
220
+
- Collections/projects with nested items
221
+
- Evaluations by subject
222
+
- Measurements by metric type
223
+
- Funding receipts by sender/recipient
224
+
- Badges by awardee
225
+
226
+
---
227
+
228
+
## Impact Indexer Changes
229
+
230
+
- [x] Add Hypercerts lexicons to Lexicon Reference at `/lexicon`
231
+
- [x] Display activity records with contributor information
232
+
- [x] Support collection/project hierarchies
233
+
- [x] Show evaluation scores and measurements
234
+
235
+
---
236
+
237
+
## Example Queries
238
+
239
+
### Fetch Activities by Contributor
240
+
241
+
```graphql
242
+
query GetActivitiesByContributor($did: String!) {
243
+
orgHypercertsClaimActivity(
244
+
where: { contributors: { contributorIdentity: { eq: $did } } }
245
+
first: 20
246
+
) {
247
+
edges {
248
+
node {
249
+
uri
250
+
title
251
+
shortDescription
252
+
startDate
253
+
endDate
254
+
contributors {
255
+
contributorIdentity
256
+
contributionWeight
257
+
}
258
+
}
259
+
}
260
+
}
261
+
}
262
+
```
263
+
264
+
### Fetch Collections (Projects)
265
+
266
+
```graphql
267
+
query GetProjects {
268
+
orgHypercertsClaimCollection(
269
+
where: { type: { eq: "project" } }
270
+
first: 20
271
+
) {
272
+
edges {
273
+
node {
274
+
uri
275
+
title
276
+
shortDescription
277
+
items {
278
+
itemIdentifier {
279
+
uri
280
+
}
281
+
itemWeight
282
+
}
283
+
}
284
+
}
285
+
}
286
+
}
287
+
```
288
+
289
+
### Fetch Evaluations for an Activity
290
+
291
+
```graphql
292
+
query GetEvaluations($activityUri: String!) {
293
+
orgHypercertsClaimEvaluation(
294
+
where: { subject: { uri: { eq: $activityUri } } }
295
+
) {
296
+
edges {
297
+
node {
298
+
uri
299
+
did
300
+
summary
301
+
score {
302
+
min
303
+
max
304
+
value
305
+
}
306
+
createdAt
307
+
}
308
+
}
309
+
}
310
+
}
311
+
```
312
+
313
+
### Fetch Funding Receipts
314
+
315
+
```graphql
316
+
query GetFundingReceipts($recipientDid: String!) {
317
+
orgHypercertsFundingReceipt(
318
+
where: { to: { eq: $recipientDid } }
319
+
first: 50
320
+
) {
321
+
edges {
322
+
node {
323
+
uri
324
+
from { did }
325
+
amount
326
+
currency
327
+
paymentRail
328
+
occurredAt
329
+
}
330
+
}
331
+
totalCount
332
+
}
333
+
}
334
+
```
335
+
336
+
### Subscribe to New Activities
337
+
338
+
```graphql
339
+
subscription OnNewActivity {
340
+
recordCreated(collection: "org.hypercerts.claim.activity") {
341
+
uri
342
+
did
343
+
record
344
+
createdAt
345
+
}
346
+
}
347
+
```
348
+
349
+
---
350
+
351
+
## Security Considerations
352
+
353
+
- Activities and contributions are public and attributed
354
+
- Funding receipts may have anonymous senders (from field optional)
355
+
- Evaluations are attributed to evaluator DIDs
356
+
- No PII beyond what users choose to publish
357
+
358
+
---
359
+
360
+
## Backwards Compatibility
361
+
362
+
These are established lexicons with existing data. The Hypercerts team maintains backwards compatibility through semantic versioning of their NPM package.
363
+
364
+
---
365
+
366
+
## References
367
+
368
+
- [Hypercerts Lexicon Repository](https://github.com/hypercerts-org/hypercerts-lexicon)
369
+
- [Hypercerts Protocol](https://hypercerts.org)
370
+
- [NPM Package](https://www.npmjs.com/package/@hypercerts-org/lexicon)
371
+
- [AT Protocol Lexicon Spec](https://atproto.com/specs/lexicon)
372
+
373
+
---
374
+
375
+
## Changelog
376
+
377
+
| Date | Change |
378
+
|------|--------|
379
+
| 2024-01-01 | Initial implementation |
380
+
| 2025-01-29 | Retroactive LIR documentation |
+198
templates/LIR-TEMPLATE.md
+198
templates/LIR-TEMPLATE.md
···
1
+
# LIR-XXXX: [Title]
2
+
3
+
| Field | Value |
4
+
|-------|-------|
5
+
| **LIR Number** | XXXX |
6
+
| **Title** | [Short descriptive title] |
7
+
| **Author** | [Your name / handle / DID] |
8
+
| **Status** | Draft |
9
+
| **Created** | YYYY-MM-DD |
10
+
| **Updated** | YYYY-MM-DD |
11
+
12
+
---
13
+
14
+
## Abstract
15
+
16
+
[A brief (2-3 sentence) summary of the lexicon being proposed and why it should be indexed.]
17
+
18
+
---
19
+
20
+
## Motivation
21
+
22
+
[Explain why this lexicon should be added to Hypersphere. Include:]
23
+
24
+
- What problem does this solve?
25
+
- Who will benefit from this data being indexed?
26
+
- What use cases are enabled?
27
+
- Is there existing adoption of this lexicon?
28
+
29
+
---
30
+
31
+
## Lexicon Specification
32
+
33
+
### NSID
34
+
35
+
```
36
+
[your.namespace.collection.name]
37
+
```
38
+
39
+
### Schema Reference
40
+
41
+
[Link to the lexicon schema if publicly available, or include the full schema below.]
42
+
43
+
### Full Schema
44
+
45
+
```json
46
+
{
47
+
"lexicon": 1,
48
+
"id": "your.namespace.collection.name",
49
+
"defs": {
50
+
"main": {
51
+
"type": "record",
52
+
"description": "[Description of the record type]",
53
+
"key": "tid",
54
+
"record": {
55
+
"type": "object",
56
+
"required": ["field1", "field2"],
57
+
"properties": {
58
+
"field1": {
59
+
"type": "string",
60
+
"description": "[Field description]"
61
+
},
62
+
"field2": {
63
+
"type": "integer",
64
+
"description": "[Field description]"
65
+
}
66
+
}
67
+
}
68
+
}
69
+
}
70
+
}
71
+
```
72
+
73
+
### Example Record
74
+
75
+
```json
76
+
{
77
+
"$type": "your.namespace.collection.name",
78
+
"field1": "example value",
79
+
"field2": 42,
80
+
"createdAt": "2024-01-15T10:30:00.000Z"
81
+
}
82
+
```
83
+
84
+
---
85
+
86
+
## Hypergoat Changes
87
+
88
+
[Describe what needs to happen in Hypergoat:]
89
+
90
+
- [ ] Upload lexicon schema
91
+
- [ ] Configure Jetstream subscription
92
+
- [ ] Trigger backfill (if applicable)
93
+
- [ ] Any custom indexing requirements
94
+
95
+
### Expected Query Patterns
96
+
97
+
[Describe how users will typically query this data:]
98
+
99
+
- By author (DID)
100
+
- By time range
101
+
- By specific fields
102
+
- Aggregations needed?
103
+
104
+
---
105
+
106
+
## Impact Indexer Changes
107
+
108
+
[Describe what documentation or UI changes are needed in Impact Indexer:]
109
+
110
+
- [ ] Add to Lexicon Reference page
111
+
- [ ] Create collection-specific visualization (if applicable)
112
+
- [ ] Update API documentation
113
+
- [ ] Other changes
114
+
115
+
---
116
+
117
+
## Example Queries
118
+
119
+
### Fetch Recent Records
120
+
121
+
```graphql
122
+
query GetRecent {
123
+
yourNamespaceCollectionName(first: 10) {
124
+
edges {
125
+
node {
126
+
uri
127
+
did
128
+
field1
129
+
field2
130
+
createdAt
131
+
}
132
+
}
133
+
}
134
+
}
135
+
```
136
+
137
+
### Fetch by Author
138
+
139
+
```graphql
140
+
query GetByAuthor($did: String!) {
141
+
yourNamespaceCollectionName(did: $did, first: 20) {
142
+
edges {
143
+
node {
144
+
uri
145
+
field1
146
+
field2
147
+
}
148
+
}
149
+
}
150
+
}
151
+
```
152
+
153
+
### Subscribe to New Records
154
+
155
+
```graphql
156
+
subscription OnNewRecord {
157
+
recordCreated(collection: "your.namespace.collection.name") {
158
+
uri
159
+
did
160
+
record
161
+
}
162
+
}
163
+
```
164
+
165
+
---
166
+
167
+
## Security Considerations
168
+
169
+
[Describe any security or privacy considerations:]
170
+
171
+
- Does this data contain PII?
172
+
- Are there any access control requirements?
173
+
- Should certain fields be filtered?
174
+
175
+
---
176
+
177
+
## Backwards Compatibility
178
+
179
+
[Describe any backwards compatibility concerns:]
180
+
181
+
- Is this a new lexicon or an update?
182
+
- Will existing queries continue to work?
183
+
184
+
---
185
+
186
+
## References
187
+
188
+
- [Link to lexicon definition repository]
189
+
- [Link to related documentation]
190
+
- [Link to existing implementations]
191
+
192
+
---
193
+
194
+
## Changelog
195
+
196
+
| Date | Change |
197
+
|------|--------|
198
+
| YYYY-MM-DD | Initial draft |