Refcodes architecture

System diagram

Core modules

Module	Path	Responsibility
Cookie capture	`proxy.ts`	First-touch `ring_ref` from `?ref=`
Code registry	`refcode-service.ts`	CRUD codes per `(userId, wallet)`
Attribution	`attribution-service.ts`	Self-ref, first-purchase, wallet overlap guards
Reward ledger	`referral-reward-service.ts`	Fiat/credit paths, approval, oracle sizing
On-chain mint	`reward-minter.ts`	viem `simulateContract` + `writeContract`
Server wallet	`lib/web3/server-wallet.ts`	`REFERRAL_MINTER_PRIVATE_KEY` → viem account

Integration points

Store order creation

app/api/store/orders/route.ts resolves attribution before StoreOrdersService.createOrder. Referral fields are stored in the orders JSONB document:

referralCode
referrerUserId
referrerWallet

PaymentConductor (fiat)

lib/payments/conductor/handlers/store-order.ts calls ReferralRewardService.onOrderPaid inside the Approved + isNew branch — after stock deduction and vendor settlement. Failures are logged but do not fail the webhook.

Internal credit (instant)

app/api/store/payments/credit/route.ts marks the order paid, deducts stock, writes settlements via settlement-pipeline.ts, then calls onOrderPaid with rail: 'crypto' (auto-approved mint).

Membership (fiat)

handlers/membership-upgrade.ts → ReferralRewardService.onMembershipPaid when users.data.referredBy is set (first-touch signup attribution).

Cron + visit beacon

Endpoint	Role
`POST /api/refcodes/track`	Increments `refcodes.data.visits`
`GET /api/cron/refcodes-mint`	Batch-mints `approved` rewards (`CRON_SECRET`)

Idempotency

Layer	Key
PostgreSQL	Unique index on `referral_rewards (data->>'orderReference')`
Service	`rewardExistsForOrder` short-circuit
Contract	`paidOrders[orderRef]` mapping — reverts `ReferralRewards__AlreadyPaid`

orderRef on-chain = keccak256(bytes(orderReference)) where orderReference comes from PaymentConductor.

Contract roles

text


initialize(admin, operator, token, mode)
  ├─ DEFAULT_ADMIN_ROLE → admin (upgrade, pause, setRewardToken/Mode)
  └─ OPERATOR_ROLE      → operator (payReferral)

MINT mode: token must authorize proxy to mint
TRANSFER mode: contract must hold token balance (treasury-funded)

i18n

Locale bundle: locales/{en,uk,ru}/modules/refcodes.json
Scope: modRefcodes in lib/i18n/message-scopes.ts (authenticated + admin)
Routes: REFCODES, ADMIN_REFCODES in constants/routes.ts

Database placement

Environment	Database	Notes
ring-platform.org dev	`ring_platform`	`ring-postgres-dev`, init `00-create-ring-platform-db.sh`
ring-platform.org prod	`ring_platform`	`postgres.ring-platform-org.svc.cluster.local`
ring-connect-software	`ring_connect_software_dev` / prod name	Separate clone DB
ring-ringdom-org	`ring_ringdom_org`	Separate clone DB

Migration file: data/migrations/005_refcodes_schema.sql.

Loading Documentation Hub...

Scanning documentation library

Documentation

Refcodes architecture

System diagram

Core modules

Module	Path	Responsibility
Cookie capture	`proxy.ts`	First-touch `ring_ref` from `?ref=`
Code registry	`refcode-service.ts`	CRUD codes per `(userId, wallet)`
Attribution	`attribution-service.ts`	Self-ref, first-purchase, wallet overlap guards
Reward ledger	`referral-reward-service.ts`	Fiat/credit paths, approval, oracle sizing
On-chain mint	`reward-minter.ts`	viem `simulateContract` + `writeContract`
Server wallet	`lib/web3/server-wallet.ts`	`REFERRAL_MINTER_PRIVATE_KEY` → viem account

Integration points

Store order creation

app/api/store/orders/route.ts resolves attribution before StoreOrdersService.createOrder. Referral fields are stored in the orders JSONB document:

referralCode
referrerUserId
referrerWallet

PaymentConductor (fiat)

Internal credit (instant)

app/api/store/payments/credit/route.ts marks the order paid, deducts stock, writes settlements via settlement-pipeline.ts, then calls onOrderPaid with rail: 'crypto' (auto-approved mint).

Membership (fiat)

handlers/membership-upgrade.ts → ReferralRewardService.onMembershipPaid when users.data.referredBy is set (first-touch signup attribution).

Cron + visit beacon

Endpoint	Role
`POST /api/refcodes/track`	Increments `refcodes.data.visits`
`GET /api/cron/refcodes-mint`	Batch-mints `approved` rewards (`CRON_SECRET`)

Idempotency

Layer	Key
PostgreSQL	Unique index on `referral_rewards (data->>'orderReference')`
Service	`rewardExistsForOrder` short-circuit
Contract	`paidOrders[orderRef]` mapping — reverts `ReferralRewards__AlreadyPaid`

orderRef on-chain = keccak256(bytes(orderReference)) where orderReference comes from PaymentConductor.

Contract roles

text


initialize(admin, operator, token, mode)
  ├─ DEFAULT_ADMIN_ROLE → admin (upgrade, pause, setRewardToken/Mode)
  └─ OPERATOR_ROLE      → operator (payReferral)

MINT mode: token must authorize proxy to mint
TRANSFER mode: contract must hold token balance (treasury-funded)

i18n

Locale bundle: locales/{en,uk,ru}/modules/refcodes.json
Scope: modRefcodes in lib/i18n/message-scopes.ts (authenticated + admin)
Routes: REFCODES, ADMIN_REFCODES in constants/routes.ts

Database placement

Environment	Database	Notes
ring-platform.org dev	`ring_platform`	`ring-postgres-dev`, init `00-create-ring-platform-db.sh`
ring-platform.org prod	`ring_platform`	`postgres.ring-platform-org.svc.cluster.local`
ring-connect-software	`ring_connect_software_dev` / prod name	Separate clone DB
ring-ringdom-org	`ring_ringdom_org`	Separate clone DB

Migration file: data/migrations/005_refcodes_schema.sql.

Loading Documentation Hub...

Scanning documentation library

Documentation

Welcome — mission & audiences

Welcome to Ring Platform - Gateway Between Humanity and the Quantum World

Library hub

Welcome to Ring Platform - Gateway Between Humanity and the Quantum World

Getting Started

First Success Validation

Troubleshooting

Next Steps

Architecture

Index

Backend modes and databases

Data Model

Authentication Architecture

Email AI-CRM Architecture

PaymentConductor architecture

Refcodes architecture

News Kingdom architecture

Features

Push Notifications with FCM (Ring-Powered)

Web3 Wallet

API

CLI

Ring CLI (enterprise only)

Customization

Deployment

Index

Self-hosted deployment

Vercel

Docker

Environment Configuration

Monitoring & Analytics

Performance Optimization

Backup & Recovery

Development

Generative Images (ImageConductor)

Autonomous Newsroom (Grok)

OSS vs enterprise

Roadmap

Platform Roadmap (Technical)

Examples

Index

Quick Start

Authentication

Email AI-CRM Tutorial

Integrations

Ethereum wallets (Wagmi v3)

Quick entry (CTOs · auditors · agents)

Library hub

Welcome — mission & audiences

Getting started

Architecture & Auth.js

Backend modes & databases (DB_BACKEND_MODE)

Self-hosted

Ring MCP

Deploy (Docker · k8s)

Security & compliance reads

Refcodes architecture

System diagram

Core modules

Module	Path	Responsibility
Cookie capture	`proxy.ts`	First-touch `ring_ref` from `?ref=`
Code registry	`refcode-service.ts`	CRUD codes per `(userId, wallet)`
Attribution	`attribution-service.ts`	Self-ref, first-purchase, wallet overlap guards
Reward ledger	`referral-reward-service.ts`	Fiat/credit paths, approval, oracle sizing
On-chain mint	`reward-minter.ts`	viem `simulateContract` + `writeContract`
Server wallet	`lib/web3/server-wallet.ts`	`REFERRAL_MINTER_PRIVATE_KEY` → viem account

Integration points

Store order creation

app/api/store/orders/route.ts resolves attribution before StoreOrdersService.createOrder. Referral fields are stored in the orders JSONB document:

referralCode
referrerUserId
referrerWallet

PaymentConductor (fiat)

Internal credit (instant)

app/api/store/payments/credit/route.ts marks the order paid, deducts stock, writes settlements via settlement-pipeline.ts, then calls onOrderPaid with rail: 'crypto' (auto-approved mint).

Membership (fiat)

handlers/membership-upgrade.ts → ReferralRewardService.onMembershipPaid when users.data.referredBy is set (first-touch signup attribution).

Cron + visit beacon

Endpoint	Role
`POST /api/refcodes/track`	Increments `refcodes.data.visits`
`GET /api/cron/refcodes-mint`	Batch-mints `approved` rewards (`CRON_SECRET`)

Idempotency

Layer	Key
PostgreSQL	Unique index on `referral_rewards (data->>'orderReference')`
Service	`rewardExistsForOrder` short-circuit
Contract	`paidOrders[orderRef]` mapping — reverts `ReferralRewards__AlreadyPaid`

orderRef on-chain = keccak256(bytes(orderReference)) where orderReference comes from PaymentConductor.

Contract roles

text


initialize(admin, operator, token, mode)
  ├─ DEFAULT_ADMIN_ROLE → admin (upgrade, pause, setRewardToken/Mode)
  └─ OPERATOR_ROLE      → operator (payReferral)

MINT mode: token must authorize proxy to mint
TRANSFER mode: contract must hold token balance (treasury-funded)

i18n

Locale bundle: locales/{en,uk,ru}/modules/refcodes.json
Scope: modRefcodes in lib/i18n/message-scopes.ts (authenticated + admin)
Routes: REFCODES, ADMIN_REFCODES in constants/routes.ts

Database placement

Environment	Database	Notes
ring-platform.org dev	`ring_platform`	`ring-postgres-dev`, init `00-create-ring-platform-db.sh`
ring-platform.org prod	`ring_platform`	`postgres.ring-platform-org.svc.cluster.local`
ring-connect-software	`ring_connect_software_dev` / prod name	Separate clone DB
ring-ringdom-org	`ring_ringdom_org`	Separate clone DB