This document describes the structure of the Gitcoin grants/funding platform indexer that tracks projects, rounds, applications, donations, and related entities across multiple blockchain networks.
Purpose: Stores information about funding projects/grants
| Column | Type | Nullable | Description |
|---|---|---|---|
id |
text | NO | Primary key - project identifier |
chain_id |
integer | NO | Primary key - blockchain network ID |
name |
text | YES | Project name |
nonce |
numeric(78,0) | YES | Nonce value |
anchor_address |
text | YES | Smart contract anchor address |
project_number |
integer | YES | Sequential project number |
registry_address |
text | YES | Registry contract address |
metadata_cid |
text | YES | IPFS CID for metadata |
metadata |
jsonb | YES | Project metadata in JSON format |
created_by_address |
text | YES | Address of project creator |
created_at_block |
numeric(78,0) | YES | Block number when created |
updated_at_block |
numeric(78,0) | YES | Block number when last updated |
tags |
jsonb | YES | Project tags |
project_type |
USER-DEFINED | YES | Type of project (enum) |
timestamp |
timestamp with time zone | YES | Creation timestamp |
Primary Key: (chain_id, id)
Purpose: Funding rounds where projects can apply for grants
| Column | Type | Nullable | Description |
|---|---|---|---|
id |
text | NO | Primary key - round identifier |
chain_id |
integer | NO | Primary key - blockchain network ID |
tags |
jsonb | YES | Round tags |
match_amount |
numeric(78,0) | YES | Matching funds amount |
match_token_address |
text | YES | Token address for matching funds |
match_amount_in_usd |
numeric(18,5) | YES | Matching amount in USD |
funded_amount |
numeric(78,0) | YES | Total funded amount (default: 0) |
funded_amount_in_usd |
numeric(18,5) | YES | Total funded amount in USD (default: 0) |
application_metadata_cid |
text | YES | IPFS CID for application metadata |
application_metadata |
jsonb | YES | Application metadata |
round_metadata_cid |
text | YES | IPFS CID for round metadata |
round_metadata |
jsonb | YES | Round metadata |
applications_start_time |
timestamp with time zone | YES | When applications open |
applications_end_time |
timestamp with time zone | YES | When applications close |
donations_start_time |
timestamp with time zone | YES | When donations/voting opens |
donations_end_time |
timestamp with time zone | YES | When donations/voting closes |
created_by_address |
text | YES | Address of round creator |
created_at_block |
numeric(78,0) | YES | Block number when created |
updated_at_block |
numeric(78,0) | YES | Block number when last updated |
manager_role |
text | YES | Manager role identifier |
admin_role |
text | YES | Admin role identifier |
strategy_address |
text | YES | Voting strategy contract address |
strategy_id |
text | YES | Strategy identifier |
strategy_name |
text | YES | Strategy name |
matching_distribution |
jsonb | YES | Distribution configuration |
ready_for_payout_transaction |
text | YES | Payout transaction hash |
project_id |
text | YES | Associated project ID |
timestamp |
timestamp with time zone | YES | Creation timestamp |
total_amount_donated_in_usd |
numeric(18,5) | YES | Total donations in USD |
total_donations_count |
integer | YES | Number of donations |
unique_donors_count |
integer | YES | Number of unique donors |
total_distributed |
numeric(78,0) | YES | Total amount distributed (default: 0) |
Primary Key: (chain_id, id)
Foreign Key: (chain_id, project_id) → projects(chain_id, id)
Purpose: Project applications to funding rounds
| Column | Type | Nullable | Description |
|---|---|---|---|
id |
text | NO | Primary key - application identifier |
chain_id |
integer | NO | Primary key - blockchain network ID |
round_id |
text | NO | Primary key - round identifier |
project_id |
text | YES | Associated project ID |
anchor_address |
text | YES | Anchor contract address |
status |
USER-DEFINED | YES | Application status (enum) |
status_snapshots |
jsonb | YES | History of status changes |
distribution_transaction |
text | YES | Distribution transaction hash |
metadata_cid |
text | YES | IPFS CID for metadata |
metadata |
jsonb | YES | Application metadata |
created_by_address |
text | YES | Address of applicant |
created_at_block |
numeric(78,0) | YES | Block number when created |
status_updated_at_block |
numeric(78,0) | YES | Block number when status updated |
total_donations_count |
integer | YES | Number of donations received |
total_amount_donated_in_usd |
numeric(18,5) | YES | Total donations in USD |
unique_donors_count |
integer | YES | Number of unique donors |
tags |
jsonb | YES | Application tags |
timestamp |
timestamp with time zone | YES | Creation timestamp |
Primary Key: (chain_id, round_id, id)
Foreign Keys:
(chain_id, project_id)→projects(chain_id, id)(round_id, chain_id)→rounds(id, chain_id)
Purpose: Individual donations/votes to applications
| Column | Type | Nullable | Description |
|---|---|---|---|
id |
text | NO | Primary key - donation identifier |
chain_id |
integer | YES | Blockchain network ID |
round_id |
text | YES | Round identifier |
application_id |
text | YES | Application identifier |
donor_address |
text | YES | Address of donor |
recipient_address |
text | YES | Address of recipient |
project_id |
text | YES | Project identifier |
transaction_hash |
text | YES | Transaction hash |
block_number |
numeric(78,0) | YES | Block number |
token_address |
text | YES | Token contract address |
timestamp |
timestamp with time zone | YES | Donation timestamp |
amount |
numeric(78,0) | YES | Donation amount in wei |
amount_in_usd |
numeric(18,5) | YES | Donation amount in USD |
amount_in_round_match_token |
numeric(78,0) | YES | Amount in round's matching token |
Primary Key: (id)
Foreign Keys:
(application_id, round_id, chain_id)→applications(id, round_id, chain_id)(round_id, chain_id)→rounds(id, chain_id)
Purpose: Track payouts to applications from rounds
| Column | Type | Nullable | Description |
|---|---|---|---|
id |
integer | NO | Primary key (auto-increment) |
chain_id |
integer | YES | Blockchain network ID |
application_id |
text | YES | Application identifier |
round_id |
text | YES | Round identifier |
amount |
numeric(78,0) | YES | Payout amount |
token_address |
text | YES | Token address |
amount_in_usd |
numeric(18,5) | YES | Amount in USD |
amount_in_round_match_token |
numeric(78,0) | YES | Amount in round token |
transaction_hash |
text | YES | Transaction hash |
timestamp |
timestamp with time zone | YES | Payout timestamp |
sender |
text | YES | Sender address |
Foreign Key: (chain_id, round_id, application_id) → applications(chain_id, round_id, id)
Purpose: EAS (Ethereum Attestation Service) attestations
| Column | Type | Nullable | Description |
|---|---|---|---|
uid |
text | NO | Primary key - attestation UID |
chain_id |
integer | NO | Primary key - blockchain network ID |
fee |
numeric(78,0) | YES | Attestation fee |
recipient |
text | YES | Recipient address |
ref_uid |
text | YES | Reference attestation UID |
projects_contributed |
numeric(78,0) | YES | Number of projects contributed to |
rounds_contributed |
numeric(78,0) | YES | Number of rounds contributed to |
chain_ids_contributed |
numeric(78,0) | YES | Number of chains contributed to |
total_usdamount |
numeric(78,0) | YES | Total USD amount |
timestamp |
timestamp with time zone | YES | Attestation timestamp |
metadata_cid |
text | YES | IPFS CID for metadata |
metadata |
jsonb | YES | Attestation metadata |
Primary Key: (chain_id, uid)
Purpose: Link attestations to blockchain transactions
| Column | Type | Nullable | Description |
|---|---|---|---|
txn_hash |
text | YES | Transaction hash |
chain_id |
integer | YES | Blockchain network ID |
attestation_uid |
text | YES | Attestation UID |
attestation_chain_id |
integer | YES | Attestation chain ID |
Foreign Key: (attestation_chain_id, attestation_uid) → attestations(chain_id, uid)
Unique Constraints: (attestation_uid, txn_hash, chain_id)
Purpose: Manage access roles for projects
| Column | Type | Nullable | Description |
|---|---|---|---|
chain_id |
integer | NO | Primary key - blockchain network ID |
project_id |
text | NO | Primary key - project identifier |
address |
text | NO | Primary key - user address |
role |
USER-DEFINED | NO | Primary key - role type (enum) |
created_at_block |
numeric(78,0) | YES | Block number when created |
Primary Key: (chain_id, project_id, address, role)
Foreign Key: (chain_id, project_id) → projects(chain_id, id)
Purpose: Manage access roles for rounds
| Column | Type | Nullable | Description |
|---|---|---|---|
chain_id |
integer | NO | Primary key - blockchain network ID |
round_id |
text | NO | Primary key - round identifier |
address |
text | NO | Primary key - user address |
role |
USER-DEFINED | NO | Primary key - role type (enum) |
created_at_block |
numeric(78,0) | YES | Block number when created |
Primary Key: (chain_id, round_id, address, role)
Foreign Key: (chain_id, round_id) → rounds(chain_id, id)
Purpose: Track pending role assignments for projects
| Column | Type | Nullable | Description |
|---|---|---|---|
id |
integer | NO | Primary key (auto-increment) |
chain_id |
integer | YES | Blockchain network ID |
role |
text | YES | Role type |
address |
text | YES | User address |
created_at_block |
numeric(78,0) | YES | Block number when created |
Purpose: Track pending role assignments for rounds
| Column | Type | Nullable | Description |
|---|---|---|---|
id |
integer | NO | Primary key (auto-increment) |
chain_id |
integer | YES | Blockchain network ID |
role |
text | YES | Role type |
address |
text | YES | User address |
created_at_block |
numeric(78,0) | YES | Block number when created |
Purpose: Raw blockchain event logs
| Column | Type | Nullable | Description |
|---|---|---|---|
chain_id |
integer | NO | Primary key - blockchain network ID |
block_number |
integer | YES | Block number |
block_timestamp |
bigint | YES | Block timestamp |
log_index |
integer | YES | Log index in block |
raw_event |
jsonb | YES | Raw event data |
Purpose: Track voting/allocation strategies
| Column | Type | Nullable | Description |
|---|---|---|---|
address |
text | NO | Primary key - strategy contract address |
chain_id |
integer | NO | Primary key - blockchain network ID |
id |
text | YES | Strategy identifier |
handled |
boolean | YES | Whether strategy is processed |
Purpose: Track processing progress for strategies
| Column | Type | Nullable | Description |
|---|---|---|---|
chain_id |
integer | NO | Primary key - blockchain network ID |
strategy_id |
text | NO | Primary key - strategy identifier |
last_processed_block_number |
integer | YES | Last processed block |
last_processed_log_index |
integer | YES | Last processed log index |
created_at |
timestamp with time zone | YES | Creation time (default: now()) |
updated_at |
timestamp with time zone | YES | Update time (default: now()) |
Purpose: Performance metrics for strategy processing
| Column | Type | Nullable | Description |
|---|---|---|---|
strategy_id |
text | NO | Primary key - strategy identifier |
address |
text | NO | Primary key - strategy address |
timings |
jsonb | YES | Timing data |
created_at |
timestamp with time zone | YES | Creation time (default: now()) |
Purpose: Cache for IPFS metadata
| Column | Type | Nullable | Description |
|---|---|---|---|
id |
text | NO | Primary key - content identifier |
metadata |
jsonb | YES | Cached metadata |
created_at |
timestamp with time zone | YES | Cache time (default: now()) |
Purpose: Cache for token price data
| Column | Type | Nullable | Description |
|---|---|---|---|
token_code |
text | NO | Primary key - token identifier |
timestamp_ms |
bigint | NO | Primary key - timestamp in milliseconds |
price_usd |
numeric(36,18) | NO | Price in USD |
created_at |
timestamp with time zone | YES | Cache time (default: now()) |
Purpose: Mapping between v1 and v2 project identifiers
| Column | Type | Nullable | Description |
|---|---|---|---|
id |
integer | NO | Primary key (auto-increment) |
v1_chain_id |
integer | YES | V1 chain ID |
v1_project_id |
text | YES | V1 project identifier |
v2_project_id |
text | YES | V2 project identifier |
Unique Constraints: v1_project_id, v2_project_id
Purpose: Database migration management and locking
external_services_cache_migrations&external_services_cache_migrations_lockprocessing_cache_migrations&processing_cache_migrations_lockprocessing_migrations&processing_migrations_lock
Each has:
name(varchar 255) - migration nametimestamp(varchar 255) - migration timestampid(varchar 255) - lock identifieris_locked(integer) - lock status (default: 0)
projects (1) ←→ (N) applications ←→ (N) donations
↓ ↓
rounds (1) ←→ (N) applications → applications_payouts
↓
round_roles
projects → project_roles
attestations ← attestation_txns
- Multi-chain Support: Most tables include
chain_idto support multiple blockchain networks - JSONB Usage: Extensive use of JSONB for metadata storage provides flexibility
- Numeric Precision: Large numeric types (78,0) used for blockchain amounts to handle wei values
- Timestamping: Comprehensive timestamping at both database and blockchain levels
- Role-based Access: Separate role management for projects and rounds
- Event Sourcing: Raw event storage enables reconstruction of state
- Caching: Multiple cache layers for performance optimization