minterop-consumer

This repository contains the entrypoint (event-dispatcher) for the pub/sub event based architecture fanning out events to different consuming services that will be built over the course of the year.

For now, this is just RPC (single topic) but in the future may include others and more topics along the chain.

Quickstart

You can run all services using docker compose

docker compose up

This runs

• postgres image
• event-dispatcher image
• metadata-resolver image

you need to have the correct envs for each of them, if you dont have them ask someone from the platform team

Simple architecture diagram:

Components

Event dispatcher

The event dispatcher is a small typescript service that leverages the gcp client library to forward payloads received via http to be published.

You can run this locally using in the event-dispatcher root

npm run start

if you want to run tests which run a local subscriber and send http requests to the publishing endpoint and check they are delivered run

npm test

Metadata resolver

To run metadata resolver locally you can use

cargo run

you must have an instance of posgres running

To run the metadata-resolver tests use

metadata-resolver/test.sh

This will send dummy requests acting as what the the subscriber would push and assert that the correct metadata is populating the db.

Config

All config is handled via .env files, which require the following variables:

• POSTGRES: connection string for the used DB
• NEAR_RPC_URL: URL for the NEAR RPC to be used (either mainnet or testnet)
• MINTBASE_ROOT: NEAR account ID of the mintbase factory contract
• RUST_LOG: logging directives for Rust-based components
• IMAGE_CACHE_BASE_URL: URL of the MB image caching service
• PUBSUB_TOPIC: Pubsub topic to which messages are dispatched from the event dispatcher (TODO: deprecate, now derived from NEAR_ENV)
• PUBSUB_DEADLETTER_TOPIC: Dead letter to store unprocessable messages (TODO: deprecate, now derived from NEAR_ENV)
• PUBSUB_SUBSCRIPTION_NAME: Name of the push subscription from pubsub queue to (TODO: deprecate, now derived from NEAR_ENV) metadata resolver
• SUBSCRIPTION_PUSH_ENDPOINT: URL of the metadata resolver
• GOOGLE_APPLICATION_CREDENTIALS: file location for the GCP service account keys, must be placed inside the event-dispatcher directory
• NEAR_ENV: The NEAR protocol network to attach to (TODO: derive NEAR_RPC_URL from that)
• ALERT_SERVICE_URL: URL where the sale checker can send alerts to

GCP resources

• One service account for sale checker and event dispatcher
  • TODO: Scopes
• Pub/Sub topics and subscriptions:
  • $network-indexer-fanout: Populated from event dispatcher
    • minterop-dispatched-$network: Pushes to metadata resolver (6 hours message retention, no expiration, 60 seconds ACK deadline, dead lettering after 5 delivery attempts, expoential backoff 60-600 seconds)
  • $network-sales-topic: Populated from event dispatcher
    • $network-sales-subscription: Pushes to sale checker (6 hours message retention, no expiration, 10 seconds ACK deadline, dead lettering after 5 delivery attempts, expoential backoff 60-600 seconds)
  • $network-deadletter: Dead lettering for other topics
    • $network-deadletter-subscription: Pull subscription for manual inspection
• Three Cloud Run services: metadata resolver, event dispatcher, sale checker
• The database to be populated by the metadata resolver
• A notification system (most likely a Cloud Run endpoint) downstream of the sale checker

Todos

• Move setup into startup, wrap try catch to prevent explosion when topic/subsriptions exist already.
• Debug everywhere logs are cheap and helpful
• Make CD deploy dispatcher
• Move (copy) the RPC service in here
• Update RPC service to handle pubsub push payloads (https://cloud.google.com/pubsub/docs/push#receive_push) as well as fix database connection pooling issues.
• Extract deployment to script with sandbox, testnet, mainnet as arg
• Make CD deploy metadata-resolver to new cloud run instance (soft cutover)
• Implement CI for metadata resolver
• Manually run tests on sandbox to validate RPC service is receiving payloads.
• Create remaining subscriptions for testnet/mainnet on GCP (inside dispatcher)
• Create release workflow that deploys to mainnet
• Include testnet to CD

Later...

• Add docker-compose in root directory, that builds and starts dispatcher service
• Someday, use emulator https://cloud.google.com/pubsub/docs/emulator
• Add RPC to the docker compose
• Add postgress to docker compose, point rpc at local db (see interop for example)
• Create script that does post requests on the dispatcher (automate however)