All engineering notes
Web3, Trading, architecture record

Social Forecasting & DeFi Liquidity dApp

Users submit price predictions and are ranked by how close they were, not merely whether they were right — which means scoring is a continuous distance calculation rather than a binary settlement. That difference drives the architecture: prediction monitoring, resolution, scoring, dashboard aggregation and notification state each run as their own worker module, and reward distribution is a whole separate deployable so a heavy payout run can never block the API.

3.8kTypescript files, backend + packages
4Deployable apps, API, listener, rewards, sockets
11Worker modules, in the listener alone
6+Wallet connectors, including smart accounts

Repository shape

Backend monorepo (API, chain listener, reward engine, socket gateway) plus separate public and admin web clients and a contract repository

How this is presented

Documented as an architecture record. The interesting parts are the worker decomposition and the scoring model, neither of which needs a live deployment to explain.

The life of a prediction

Each stage below is a distinct worker module. Watch how the work moves off the API and into the worker plane as soon as the user is done interacting.

Public appClient surface

Prediction submission, leaderboards, pools and staking, fully internationalised.

Client surfaceExternalServiceRealtimeWorker / jobOn-chainData store
Submitting a forecast

From a user's guess to a recorded, staked position.

Highlights

  • Distance-based scoring: predictions are ranked by proximity to the real outcome, so near-misses are rewarded proportionally instead of being written off.
  • Reward distribution runs as its own deployable, isolating expensive payout batches from user-facing latency.
  • Eleven separate worker modules, each owning one stage of the prediction lifecycle.
  • Notification delivery is modelled as an explicit state machine rather than fire-and-forget sends.
  • Dashboard figures come from pre-computed rollups, so analytics stay fast as history grows.
  • Six wallet connection paths, including smart accounts and exchange-backed wallets, to avoid excluding non-crypto-native users.
  • Fully internationalised client with locale-scoped routing.

One API, three specialised worker planes

The lifecycle of a prediction is long: submitted, monitored, resolved, scored, rewarded, announced. Rather than run that as one cron job, each stage is its own module with its own state, so a failure in scoring does not stall monitoring and a slow payout does not stall anything.

Public client

Prediction submission, leaderboards, pools, staking surfaces and account management.

  • Locale-scoped routing with full internationalisation.
  • Six wallet connection paths behind one unified session model.
  • Charts and dashboards read from pre-aggregated endpoints, not raw history.

Application API

Predictions, pools, staking, rewards, identity, permissions, media and public metadata.

  • Modular NestJS layout with one module per bounded context.
  • Owns validation and eligibility; the chain holds custody and settlement.
  • Emits events for the socket gateway rather than managing connections itself.

Chain listener

Eleven worker modules covering monitoring, resolution, submission updates, pool updates and notification state.

  • Separate modules for detecting an outcome, resolving it and updating submissions.
  • Dashboard rollups are maintained here, off the request path.
  • Notification state machines track what has been delivered rather than assuming success.

Reward engine

Its own deployable, dedicated to computing and distributing winnings.

  • Isolated so a large payout batch cannot degrade the API.
  • Reads scored results and writes allocations as auditable records.

Contracts and liquidity

On-chain custody, liquidity provisioning and treasury operations.

  • Solidity contract suite deployed through a scripted, reproducible pipeline.
  • AMM integration for liquidity provisioning alongside the forecasting game.
  • Treasury actions run through a multisig with explicit nonce management.

Modules across both runtimes

The API owns request-path concerns; the listener owns everything asynchronous. Note that the prediction lifecycle is split into separate worker modules rather than one scheduled job. 42 units across 6 groups.

Forecasting domain

7
prediction-cryptoprediction-distance-recordprediction-winnerpredictorcategorycommentuser-comment

Listener workers

10
prediction-monitorprediction-resolverprediction-submissions-updateprediction-notification-processorprediction-notification-statepool-updatepool-notification-statedashboard-rollupcrypto-contractshealth

Value & liquidity

7
stakingpoolairdroprewardsafecrypto-factorywallet

Identity & access

5
authenticationuserrolepermissionkyc

Messaging

3
notificationnotification-groupnotification-template

Content & platform

10
adminmediamedia-folderpagedefault-seoseo-groupseo-metadataproject-configdashboarddb

Stack by layer

Client

Next.js, React Compiler, Radix UI, React Query, Chart.js, Internationalised routing

Wallets

Injected + mobile connectors, WalletConnect, Smart-account connectors, Exchange-backed wallets

Services

NestJS API, Chain listener, Reward engine, WebSocket gateway

Data

PostgreSQL, Redis, Rollup tables

Chain

L2 network, AMM / liquidity SDK, Multisig treasury, Solidity contracts

Delivered work

Client surfaces

  • Prediction submission, leaderboards, pools and staking flows.
  • Six wallet connection paths unified behind one session model.
  • Internationalised routing with locale-scoped pages.
  • Chart-driven dashboards reading from pre-aggregated endpoints.

Services and workers

  • Modular API covering predictions, pools, staking, rewards, identity and permissions.
  • Chain listener decomposed into eleven single-purpose worker modules.
  • Reward engine split out as an independent deployable.
  • Socket gateway for live leaderboard and notification delivery.

On-chain and treasury

  • Solidity contract suite with a scripted, reproducible deployment pipeline.
  • AMM liquidity provisioning integrated alongside the forecasting mechanics.
  • Multisig treasury operations with explicit nonce handling.
  • Airdrop and allocation records tracked as first-class data.

Key modules

Distance scoring

Ranks forecasts by how close they landed.

  • Continuous scoring rather than binary win/lose.
  • Drives both the leaderboard and the reward split.

Worker decomposition

One module per lifecycle stage.

  • Monitoring, resolution, submission updates, rollups and notification state are all separate.
  • A stall in one stage leaves the others running.

Reward engine

Computes and distributes winnings in isolation.

  • Its own deployable, with allocation records written before transfers.
  • Reconciliation makes partial batches visible.

Notification state machines

Tracks what was actually delivered.

  • Per-entity delivery state instead of fire-and-forget.
  • Makes redelivery safe and duplicate sends detectable.

Presentation approach

How this project is presented

  • Worker decomposition shown as an interactive flow, since that is the real design work.
  • Scoring model explained rather than demonstrated.
  • Verified file and module counts instead of estimates.
  • No public instance — the value is in the architecture.

Documentation and notes

Lifecycle walkthrough

Submission, scoring and reward distribution as three annotated flows.

Worker module map

What each of the eleven listener modules owns.

Scoring model

How distance-based ranking is computed and turned into a reward split.

Contract deployment record

Scripted deployments, address registry and treasury setup.
  • Product and client names are intentionally omitted.
  • Scale figures are counted from the repositories.
  • Reward distribution is deliberately a separate deployable; collapsing it back into the API would reintroduce the latency coupling it was built to remove.
All 21 engineering notes