{"id":26524962,"url":"https://github.com/hypercerts-org/hypercerts-indexer","last_synced_at":"2025-10-11T04:56:04.190Z","repository":{"id":224059589,"uuid":"757092703","full_name":"hypercerts-org/hypercerts-indexer","owner":"hypercerts-org","description":"Indexing service for hypercerts metadata","archived":false,"fork":false,"pushed_at":"2025-08-06T20:59:57.000Z","size":1328,"stargazers_count":2,"open_issues_count":5,"forks_count":0,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-08-06T22:08:21.679Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hypercerts-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-02-13T19:46:50.000Z","updated_at":"2025-08-06T21:00:01.000Z","dependencies_parsed_at":"2024-03-11T02:30:37.670Z","dependency_job_id":"d8da11a1-7ade-4fed-8de3-815a7d585fe4","html_url":"https://github.com/hypercerts-org/hypercerts-indexer","commit_stats":null,"previous_names":["hypercerts-org/hypercerts-indexer"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hypercerts-org/hypercerts-indexer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypercerts-org%2Fhypercerts-indexer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypercerts-org%2Fhypercerts-indexer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypercerts-org%2Fhypercerts-indexer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypercerts-org%2Fhypercerts-indexer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hypercerts-org","download_url":"https://codeload.github.com/hypercerts-org/hypercerts-indexer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypercerts-org%2Fhypercerts-indexer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279006216,"owners_count":26084063,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-21T14:39:51.356Z","updated_at":"2025-10-11T04:56:04.184Z","avatar_url":"https://github.com/hypercerts-org.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hypercerts Indexer\n\nThe hypercerts indexing service monitors the hypercerts contract and indexes the data into a postgres database for all supported chains on either testnets or production.\n\n## Getting started\n\n### Environment variables\n\n#### Service\n\nDetermines the chains to index and the port to run the service on. Based on the environment, all relevant contract and events are fetched from the database and will be monitored.\n\n#### Indexing\n\nDetermines the batch size and the delay between indexing runs.\n\n#### RPCs\n\nThe API implements a fallback to the first available RPC. You can set the RPC keys in the `.env` file.\n\n#### Databases\n\n##### Local caching\n\nThe indexing service is paired with a local postgres database for caching purposes. When the service needs to do a remote call to an EVM or IPFS, the call and the response are cached in the local database. This reduces load and latency on the RPCs.\n\n\u003e We recommend using [Postgres.app](https://postgresapp.com/) to run the local caching database on MacOS.\n\n#### Kysely\n\nKysely is implemented in favor of SupabaseJS as it allows for more flexibility and complexity in queries. To connect to the database you need to set the `DB_URL` in the `.env` file. By default, the local variables are set to the local Supabase instance.\n\n##### Supabase\n\nThe indexing service is paired with a Postgres database for storing state provided by Supabase. Events for mints, transfers, claims and other relevant events are parsed and the state in the DB is updated. Additionally, the database provides a cache for the metadata of hypercerts and parses attestations.\n\n#### Sentry\n\nSentry is used for monitoring and error reporting. You can read more about it [here](https://docs.sentry.io/platforms/javascript/guides/node/configuration/env-vars/). When Sentry is set to `local` it will be disabled by default.\n\n### Run the Indexer locally\n\n`pnpm dev`\n\n## Deployments\n\nThe indexing services are deployed on Railway and not publicly exposed.\n\n## Scripts\n\n- `dev`: Starts the development server using `nodemon`, which will automatically restart the server whenever you save a file that the server uses.\n- `build`: Compiles the TypeScript code into JavaScript using `swc`. The compiled code is output to the `dist` directory.\n- `start`: Starts the application in production mode. \n- `test`: Runs tests using `vitest`\n- `test:coverage`: Runs tests and generates a coverage report.\n- `test:integration`: Runs integration tests using `vitest`.\n- `supabase:reset`: Resets the Supabase database and generates the TypeScript types for the database.\n- `supabase:seed`: Seeds the Supabase database with test data.\n- `supabase:types`: Generates the TypeScript types for the caching database (indexer).\n- `supabase:types:data`: Generates the TypeScript types for the data database (api).\n- `update:sentry:sourcemaps`: Updates the Sentry source maps.\n\n## Data\n\nThe indexer service monitors supported chains and gathers data from multiple sources based on the observed events.\n\n### Hypercerts minter\n\n\u003e Mints, allowlist claims, splits, merges, transfers, burns, etc.\n\nThe hypercerts minter contract is monitored for minting events. When a minting event is observed, the data is indexed into the local caching database. In addition to minting events, the indexer also monitors the hypercerts contract for allowlist claims, splits, merges and other state changes.\n\n### IPFS\n\n\u003e Metadata, allowlist data, images, etc.\n\nHypercerts created via our stack store the metadata on IPFS. The indexer fetches the metadata from IPFS and stores it in the local caching database and writes it to the caching database for the API.\n\n### EAS - Ethereum Attestation Service\n\n\u003e Schemas and attestations.\n\n[EAS](https://attest.sh/) utilizes schemas to define the structure of the data stored in the attestations. The indexer database is seeded with the schemas from the EAS contract. When an attestation is observed, the indexer fetches the schema from the database and decodes the attestation data. The decoded data is then indexed into the local caching database.\n\n## Architecture\n\n```mermaid\ngraph TB\n    subgraph \"Indexer Service\"\n        Indexer[Indexer Service]\n        Cache[(\"Local Cache DB\\n(Postgres)\\n- RPC Responses\\n- IPFS Responses\")]\n        State[(\"State DB\\n(Supabase)\\n- Events\\n- Metadata\\n- Attestations\")]\n    end\n    \n    subgraph \"Data Sources\"\n        Contract[(\"Hypercerts Contract\\n- Mints\\n- Claims\\n- Splits\\n- Merges\\n- Transfers\\n- Burns\")]\n        IPFS[(\"IPFS\\n- Metadata\\n- Allowlist Data\\n- Images\")]\n        EAS[(\"EAS\\n- Schemas\\n- Attestations\")]\n    end\n    \n    subgraph \"Configuration\"\n        ENV[\"Environment Variables\\n- Chain Selection\\n- RPC Config\\n- Batch Size\\n- Index Delay\"]\n        Sentry[Sentry Monitoring]\n    end\n    \n    Indexer --\u003e Cache\n    Indexer --\u003e State\n    \n    Contract --\u003e Indexer\n    IPFS --\u003e Indexer\n    EAS --\u003e Indexer\n    \n    ENV --\u003e Indexer\n    Indexer --\u003e Sentry\n    \n    class Cache,State database;\n    class Contract,IPFS,EAS external;\n    class ENV config;\n    class Sentry monitoring;\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhypercerts-org%2Fhypercerts-indexer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhypercerts-org%2Fhypercerts-indexer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhypercerts-org%2Fhypercerts-indexer/lists"}