feat: add subgraph observability scaffold

[boris]

This pull request introduces the initial observability framework for the project by scaffolding a subgraph for The Graph Studio to index key on-chain events and metrics, and by preparing the codebase for serverless metric exposure. It also adds supporting documentation, contract ABIs, and configuration for the subgraph. The main themes are observability infrastructure, schema and indexing logic, and developer documentation.

Observability infrastructure and subgraph setup:

• Added a new subgraph package with all necessary configuration, scripts, and dependencies for indexing contract events using The Graph, including a package.json with build and deploy scripts.
• Introduced contract ABIs for CLPc, ClaimCLPc, and MockZKPassportVerifier to allow the subgraph to decode and process relevant events. [1] [2] [3]
• Created a comprehensive subgraph schema (schema.graphql) modeling accounts, global/hourly/daily metrics, and all relevant event types (verifications, revocations, transfers, mints, burns, claims, gas usage).

Indexing and event processing logic:

• Implemented AssemblyScript handlers for contract events:
  • token.ts indexes token transfers, mints, and burns, updating metrics and storing event data.
  • claim.ts indexes claim events, updating account and metric entities.
  • helpers.ts provides utility functions for entity management, metric bucketing, deduplication of gas accounting, and event ID generation.

Documentation and developer workflow:

• Added detailed documentation on observability setup and subgraph deployment, including metric conventions, event mapping, and integration with serverless workers for Prometheus-style metric exposure. (docs/observability/subgraph-studio.md)
• Updated project documentation to mention observability via subgraph and serverless worker, and clarified the branch workflow to always branch off main. [1] [2]

These changes establish the foundation for on-chain observability, enabling analytics and monitoring through standardized metrics and easy integration with external tools.