Token Economics Setup

Executive summary

Ring clones ship a three-layer economy: (1) an off-chain credit ledger in PostgreSQL for membership and store checkout, (2) optional on-chain RING reference contracts for treasury-grade utility tokenomics, and (3) a referral token rail (ReferralRewards + refcodes) for platform-funded growth payouts. ring-platform.org brands the utility token as RING; agricultural clones (e.g. GreenFood) may fork symbols to DAAR / DAARION via ring-config.json.

Payment integration

PaymentConductor — WayForPay, Stripe, internal credit

Web3 wallet feature

Custodial wallets, balances, top-up UX

Referral codes (refcodes)

Attribution, ledger, on-chain mint

Affiliate enablement

Dual-rail ERP commission + token rewards

Refcodes architecture

viem minter, env contract, cron

Customization guide

ring-config.json, locales, feature flags

Philosophy

Traditional platforms capture value in opaque ledgers. Ring-powered clones expose fee flows you control: membership utility, marketplace settlement, referral growth, and optional on-chain treasury — all configurable per white-label instance.

Principle	Ring implementation
Utility-first	Tokens gate features and settle platform fees — not investment promises
Postgres-primary	Credit balances and subscriptions live in `users.data` + `ring_subscriptions` when `DB_BACKEND_MODE=k8s-postgres-fcm`
Fiat + credit coexist	WayForPay/Stripe for card rails; `credit_balance` spends the same ledger
Per-clone branding	`ring-config.json` → `tokens.native.symbol` drives UI copy via `getNativeTokenSymbol()`

Three economic layers

Layer 1 — Off-chain credit ledger (production path today)

Most membership and store flows debit an application credit balance — denominated in fiat USD (default), not the token symbol. On ring-platform.org, credits are always fiat USD. RING is a separate native token on Solana for optional on-chain operations. The Desk widget converts credits ↔ native tokens at the oracle rate.

Data model

Store	Location	Contents
Balance	`users.data.credit_balance`	`amount`, `main_currency_equivalent`, `subscription_active`, `subscription_next_payment`
History	`users.data.credit_transactions`	Typed ledger entries with optional `tx_hash`, `order_id`
Subscriptions	`ring_subscriptions` collection	Status, `next_payment_due`, `failed_attempts`, `auto_renew`

Schema comment: users.data JSONB in data/schema.sql v4+.

Core services

Service	Path	Role
creditBalanceService	`features/wallet/services/credit-balance-service.ts`	Balance read/write, spend, top-up, membership fee debit, tunnel publish on change
SubscriptionService	`services/membership/subscription-service.ts`	Create/cancel/renew; 1 RING/month; upgrades `membership.tier` → `member`
PriceOracleService	`features/wallet/services/native-token-price-oracle.ts`	RING/USD via viem + Chainlink/CoinGecko/CMC/Binance fallbacks
Internal credit checkout	`lib/payments/processors/credit-balance.processor.ts`	PaymentConductor rail for store + membership spend

Membership economics (reference)

Parameter	Value	Where enforced
Monthly fee	1 utility token	`subscription-service.ts` (`membershipFee = '1.0'`)
Billing period	30 days	`next_payment_due` timestamp math
Recommended buffer	12 tokens (1 year)	`RingToken.MIN_SUBSCRIPTION_BALANCE` on-chain; UI warnings via credit limits
Role gate	SUBSCRIBER+ to subscribe	`POST /api/membership/subscription/create`

User tops up or receives airdrop
POST /api/wallet/credit/topup (admin/ops) or fulfillment after wallet_topup PaymentConductor purpose adds credits via creditBalanceService.addCredits().
User creates subscription
POST /api/membership/subscription/create debits 1 RING credit, writes ring_subscriptions, sets credit_balance.subscription_active.
Contract env gate
This route returns 503 until RING_TOKEN_CONTRACT_ADDRESS and RING_MEMBERSHIP_CONTRACT_ADDRESS are set — even though the debit is ledger-based. Set deployed addresses (or placeholder addresses in dev) to unlock the API.
Store checkout with credit
When PAYMENT_STORE_ALLOW_CREDIT=true, PaymentConductor credit_balance rail spends credits for orders in currencies allowed by PAYMENT_CREDIT_BALANCE_ACCEPTED_ORDER_CURRENCIES (defaults to PAYMENT_FIAT_CURRENCY).

Credit API surface

Endpoint	Method	Purpose
`/api/wallet/credit/balance`	GET	Balance + subscription snapshot
`/api/wallet/credit/history`	GET	Paginated transaction history
`/api/wallet/credit/topup`	POST	Add credits
`/api/wallet/credit/spend`	POST	Spend credits
`/api/prices/ring-usd`	GET	Oracle price for UI and receipts
`/api/membership/subscription/create`	POST	Start membership

Client hook: hooks/use-credit-balance.ts — initial REST fetch + tunnel push updates (no polling).

Layer 2 — On-chain RING reference contracts

Ring ships UUPS upgradeable reference contracts for clones that want treasury-controlled ERC-20 utility on Polygon (chainId 137).

RingToken (`contracts/RingToken.sol`)

Constant	Value
`INITIAL_SUPPLY`	1,000,000,000 RING → minted to treasury at `initialize`
`MEMBERSHIP_FEE`	1 RING / month
`MIN_SUBSCRIPTION_BALANCE`	12 RING
Decimals	18

Owner functions: setMembershipContract, setTreasury, creditTokens (treasury airdrops), pause / unpause.

Membership-only: deductMembershipFee(member) — callable only by linked Membership.

Membership (`contracts/Membership.sol`)

Constant	Value
`SUBSCRIPTION_PERIOD`	30 days
`GRACE_PERIOD`	7 days
`MAX_FAILED_ATTEMPTS`	3 → `EXPIRED`

Statuses: INACTIVE, ACTIVE, EXPIRED, CANCELLED, SUSPENDED.

On-chain lifecycle: createSubscription() → processBatchPayments(batchSize) (operator/cron) → cancelSubscription() / admin suspend.

Utility token — not a security pitch

RING reference tokenomics gate platform access. Consult counsel before marketing yield, profit expectations, or exchange listings.

On-chain ↔ ledger sync

App subscriptions today run on the credit ledger. On-chain Membership is the reference for treasury policy and future sync; wire batch renewal cron to subscriptionService.processBatchPayments() when you bridge both layers.

Deploy reference contracts

Hardhat project: contracts/. ReferralRewards compiles from contracts/contracts-src/; RingToken / Membership live at contracts/*.sol — align hardhat.config.js paths.sources or copy sources before compile if factories fail.

Install and compile
Testnet deploy (script references Polygon Mumbai — migrate to Amoy or fork script for current testnets)
Deploy order: RingToken → Membership → ringToken.setMembershipContract(...). Output: contracts/deployments/mumbai-deployment.json.
Mainnet — scripts/deploy-mainnet.js after audit + multisig treasury. Fund deployer with POL; use Alchemy/Infura RPC (not anonymous polygon-rpc.com).
Wire env and redeploy app
Client metadata: constants/web3.ts — TOKEN_CONFIGS, staking scaffold (RING_STAKING_ADDRESS, 20% APR placeholder).

Layer 3 — Referral token rewards (refcodes)

Growth economics are separate from membership fees. When a referred user completes a qualifying purchase, the platform mints or transfers reward tokens via ReferralRewards (UUPS).

Piece	Path / contract
Contract	`contracts/contracts-src/ReferralRewards.sol`
Deploy	`npx hardhat run scripts/deploy-referral-rewards.js --network polygon`
Minter	`features/refcodes/services/reward-minter.ts` (viem)
Ops runbook	`REFERRAL-ONCHAIN-OPS.md` (repo root)

Clone install helper: scripts/install-refcodes-module.sh.

Payment rails — fiat, credit, native token

Token economics intersect PaymentConductor — one ledger (payment_transactions), multiple rails.

Rail	Env	Use
`merchant_redirect`	WayForPay / Stripe / PayPal	Card checkout, membership upgrade fiat, public_pool_contribution jar chip-ins
`credit_balance`	`PAYMENT_STORE_ALLOW_CREDIT=true`	Spend `credit_balance` at store
`native_token`	`PAYMENT_STORE_ALLOW_TOKEN=true`	On-chain token checkout (advanced)

Desk oracle (shared): Token Desk credit↔native conversion and public-pool card settle both use getNativeTokenPerMainCurrencyRate() (nativeUi = fiatMajor / nativePerMainCurrency). Do not confuse with wallet_topup (fiat credit points, 1:1 ledger). Full jar SSOT: Public Pools & DAO Jars.

Apply data/migrations/004_payment_transactions.sql before production payments. Full operator guide: Payment integration.

White-label token branding

`ring-config.json`

getNativeTokenSymbol() and getNativeTokenConfig() read this for checkout labels, wallet UI, and payment copy. Fork the symbol/name for vertical clones (e.g. GFT, DAAR) without renaming Solidity unless you deploy a new ERC-20.

Sidebar and public pages

ring-config.json → sidebar.quickLinks includes about.sidebar.tokenEconomy → /token-economy on your clone's marketing site.

Staking and vendor gates

constants/web3.ts defines a RING staking pool scaffold (20% APR, 100 RING minimum) — configure addresses per clone or disable in UI.

components/vendor/staking-card.tsx supports per-product vendor stake requirements (tokenSymbol, requiredStake) — use for agent/vendor activation flows, not global protocol rules.

Design your clone economy

Classify the token
Recommended
Utility token — listings, membership, marketplace fees. No profit promises.
Security tokens and multi-token splits need legal review before launch.
Set parameters
Map fees in constants/store.ts / ERP commission helpers for marketplace cuts.
3
Integrate with Ring services
1. Deploy or fork RingToken.sol / Membership.sol (optional)
2. Update ring-config.json + constants/web3.ts addresses
3. Set RING_TOKEN_CONTRACT_ADDRESS + membership env vars
4. Enable PAYMENT_STORE_ALLOW_CREDIT if store should spend credits
5. Deploy ReferralRewards when refcodes on-chain rewards are live
6. Smoke: npm run smoke:pipelines (see scripts/PIPELINES.md)

Health metrics

Metric	Signal
Active subscriptions / failed payment rate	`ring_subscriptions` + credit history
Credit ledger vs treasury	Reconcile `users.data.credit_balance` with on-chain treasury movements
Referral mint queue	`referral_rewards` status + `/admin/refcodes`
Oracle freshness	`PriceOracleService` cache TTL and fallback usage
Payment ledger	`payment_transactions` by `rail` and `processor`

Legal and launch checklist

Jurisdiction

Token launches have jurisdiction-specific consequences. Engage counsel before public sale, exchange listing, or yield marketing. See the dedicated guide: Token launch jurisdictions (EU MiCA, US SEC/CFTC, UK FCA, Ukraine, FATF, official sources).

Immediate

Choose: RING reference vs branded ERC-20 fork
Set ring-config.json token symbol + public token economy page
Multisig treasury and contract owner keys
Tokenomics paper (utility, fees, treasury — no investment claims)

Development

Postgres migrations through 004_payment_transactions + 005_refcodes_schema
Wire credit + PaymentConductor env vars
Deploy testnet contracts; run contracts/test
Smoke membership create + store credit checkout

Launch

Mainnet deploy after audit
Verify contracts on Polygonscan
Enable refcodes minter (REFERRAL-ONCHAIN-OPS.md)
Monitor subscription metrics and treasury alerts

Payment integration

Webhooks, WayForPay, Stripe setup

Database migrations

refcodes, payment_transactions, schema order

Ring customization opportunities

Web3 specialists on the platform

Token Economics Setup

Executive summary

Payment integration

PaymentConductor — WayForPay, Stripe, internal credit

Web3 wallet feature

Custodial wallets, balances, top-up UX

Referral codes (refcodes)

Attribution, ledger, on-chain mint

Affiliate enablement

Dual-rail ERP commission + token rewards

Refcodes architecture

viem minter, env contract, cron

Customization guide

ring-config.json, locales, feature flags

Philosophy

Principle	Ring implementation
Utility-first	Tokens gate features and settle platform fees — not investment promises
Postgres-primary	Credit balances and subscriptions live in `users.data` + `ring_subscriptions` when `DB_BACKEND_MODE=k8s-postgres-fcm`
Fiat + credit coexist	WayForPay/Stripe for card rails; `credit_balance` spends the same ledger
Per-clone branding	`ring-config.json` → `tokens.native.symbol` drives UI copy via `getNativeTokenSymbol()`

Three economic layers

Layer 1 — Off-chain credit ledger (production path today)

Data model

Store	Location	Contents
Balance	`users.data.credit_balance`	`amount`, `main_currency_equivalent`, `subscription_active`, `subscription_next_payment`
History	`users.data.credit_transactions`	Typed ledger entries with optional `tx_hash`, `order_id`
Subscriptions	`ring_subscriptions` collection	Status, `next_payment_due`, `failed_attempts`, `auto_renew`

Schema comment: users.data JSONB in data/schema.sql v4+.

Core services

Service	Path	Role
creditBalanceService	`features/wallet/services/credit-balance-service.ts`	Balance read/write, spend, top-up, membership fee debit, tunnel publish on change
SubscriptionService	`services/membership/subscription-service.ts`	Create/cancel/renew; 1 RING/month; upgrades `membership.tier` → `member`
PriceOracleService	`features/wallet/services/native-token-price-oracle.ts`	RING/USD via viem + Chainlink/CoinGecko/CMC/Binance fallbacks
Internal credit checkout	`lib/payments/processors/credit-balance.processor.ts`	PaymentConductor rail for store + membership spend

Membership economics (reference)

Parameter	Value	Where enforced
Monthly fee	1 utility token	`subscription-service.ts` (`membershipFee = '1.0'`)
Billing period	30 days	`next_payment_due` timestamp math
Recommended buffer	12 tokens (1 year)	`RingToken.MIN_SUBSCRIPTION_BALANCE` on-chain; UI warnings via credit limits
Role gate	SUBSCRIBER+ to subscribe	`POST /api/membership/subscription/create`

User tops up or receives airdrop
POST /api/wallet/credit/topup (admin/ops) or fulfillment after wallet_topup PaymentConductor purpose adds credits via creditBalanceService.addCredits().
User creates subscription
POST /api/membership/subscription/create debits 1 RING credit, writes ring_subscriptions, sets credit_balance.subscription_active.
Contract env gate
This route returns 503 until RING_TOKEN_CONTRACT_ADDRESS and RING_MEMBERSHIP_CONTRACT_ADDRESS are set — even though the debit is ledger-based. Set deployed addresses (or placeholder addresses in dev) to unlock the API.
Store checkout with credit
When PAYMENT_STORE_ALLOW_CREDIT=true, PaymentConductor credit_balance rail spends credits for orders in currencies allowed by PAYMENT_CREDIT_BALANCE_ACCEPTED_ORDER_CURRENCIES (defaults to PAYMENT_FIAT_CURRENCY).

Credit API surface

Endpoint	Method	Purpose
`/api/wallet/credit/balance`	GET	Balance + subscription snapshot
`/api/wallet/credit/history`	GET	Paginated transaction history
`/api/wallet/credit/topup`	POST	Add credits
`/api/wallet/credit/spend`	POST	Spend credits
`/api/prices/ring-usd`	GET	Oracle price for UI and receipts
`/api/membership/subscription/create`	POST	Start membership

Client hook: hooks/use-credit-balance.ts — initial REST fetch + tunnel push updates (no polling).

Layer 2 — On-chain RING reference contracts

Ring ships UUPS upgradeable reference contracts for clones that want treasury-controlled ERC-20 utility on Polygon (chainId 137).

RingToken (`contracts/RingToken.sol`)

Constant	Value
`INITIAL_SUPPLY`	1,000,000,000 RING → minted to treasury at `initialize`
`MEMBERSHIP_FEE`	1 RING / month
`MIN_SUBSCRIPTION_BALANCE`	12 RING
Decimals	18

Owner functions: setMembershipContract, setTreasury, creditTokens (treasury airdrops), pause / unpause.

Membership-only: deductMembershipFee(member) — callable only by linked Membership.

Membership (`contracts/Membership.sol`)

Constant	Value
`SUBSCRIPTION_PERIOD`	30 days
`GRACE_PERIOD`	7 days
`MAX_FAILED_ATTEMPTS`	3 → `EXPIRED`

Statuses: INACTIVE, ACTIVE, EXPIRED, CANCELLED, SUSPENDED.

On-chain lifecycle: createSubscription() → processBatchPayments(batchSize) (operator/cron) → cancelSubscription() / admin suspend.

Utility token — not a security pitch

RING reference tokenomics gate platform access. Consult counsel before marketing yield, profit expectations, or exchange listings.

On-chain ↔ ledger sync

Deploy reference contracts

Install and compile
Testnet deploy (script references Polygon Mumbai — migrate to Amoy or fork script for current testnets)
Deploy order: RingToken → Membership → ringToken.setMembershipContract(...). Output: contracts/deployments/mumbai-deployment.json.
Mainnet — scripts/deploy-mainnet.js after audit + multisig treasury. Fund deployer with POL; use Alchemy/Infura RPC (not anonymous polygon-rpc.com).
Wire env and redeploy app
Client metadata: constants/web3.ts — TOKEN_CONFIGS, staking scaffold (RING_STAKING_ADDRESS, 20% APR placeholder).

Layer 3 — Referral token rewards (refcodes)

Growth economics are separate from membership fees. When a referred user completes a qualifying purchase, the platform mints or transfers reward tokens via ReferralRewards (UUPS).

Piece	Path / contract
Contract	`contracts/contracts-src/ReferralRewards.sol`
Deploy	`npx hardhat run scripts/deploy-referral-rewards.js --network polygon`
Minter	`features/refcodes/services/reward-minter.ts` (viem)
Ops runbook	`REFERRAL-ONCHAIN-OPS.md` (repo root)

Clone install helper: scripts/install-refcodes-module.sh.

Payment rails — fiat, credit, native token

Token economics intersect PaymentConductor — one ledger (payment_transactions), multiple rails.

Rail	Env	Use
`merchant_redirect`	WayForPay / Stripe / PayPal	Card checkout, membership upgrade fiat, public_pool_contribution jar chip-ins
`credit_balance`	`PAYMENT_STORE_ALLOW_CREDIT=true`	Spend `credit_balance` at store
`native_token`	`PAYMENT_STORE_ALLOW_TOKEN=true`	On-chain token checkout (advanced)

Apply data/migrations/004_payment_transactions.sql before production payments. Full operator guide: Payment integration.

White-label token branding

`ring-config.json`

Sidebar and public pages

ring-config.json → sidebar.quickLinks includes about.sidebar.tokenEconomy → /token-economy on your clone's marketing site.

Staking and vendor gates

constants/web3.ts defines a RING staking pool scaffold (20% APR, 100 RING minimum) — configure addresses per clone or disable in UI.

components/vendor/staking-card.tsx supports per-product vendor stake requirements (tokenSymbol, requiredStake) — use for agent/vendor activation flows, not global protocol rules.

Design your clone economy

Classify the token
Recommended
Utility token — listings, membership, marketplace fees. No profit promises.
Security tokens and multi-token splits need legal review before launch.
Set parameters
Map fees in constants/store.ts / ERP commission helpers for marketplace cuts.
3
Integrate with Ring services
1. Deploy or fork RingToken.sol / Membership.sol (optional)
2. Update ring-config.json + constants/web3.ts addresses
3. Set RING_TOKEN_CONTRACT_ADDRESS + membership env vars
4. Enable PAYMENT_STORE_ALLOW_CREDIT if store should spend credits
5. Deploy ReferralRewards when refcodes on-chain rewards are live
6. Smoke: npm run smoke:pipelines (see scripts/PIPELINES.md)

Health metrics

Metric	Signal
Active subscriptions / failed payment rate	`ring_subscriptions` + credit history
Credit ledger vs treasury	Reconcile `users.data.credit_balance` with on-chain treasury movements
Referral mint queue	`referral_rewards` status + `/admin/refcodes`
Oracle freshness	`PriceOracleService` cache TTL and fallback usage
Payment ledger	`payment_transactions` by `rail` and `processor`

Legal and launch checklist

Jurisdiction

Immediate

Choose: RING reference vs branded ERC-20 fork
Set ring-config.json token symbol + public token economy page
Multisig treasury and contract owner keys
Tokenomics paper (utility, fees, treasury — no investment claims)

Development

Postgres migrations through 004_payment_transactions + 005_refcodes_schema
Wire credit + PaymentConductor env vars
Deploy testnet contracts; run contracts/test
Smoke membership create + store credit checkout

Launch

Mainnet deploy after audit
Verify contracts on Polygonscan
Enable refcodes minter (REFERRAL-ONCHAIN-OPS.md)
Monitor subscription metrics and treasury alerts

Payment integration

Webhooks, WayForPay, Stripe setup

Database migrations

refcodes, payment_transactions, schema order

Ring customization opportunities

Web3 specialists on the platform

Token Economics Setup

Executive summary

Payment integration

PaymentConductor — WayForPay, Stripe, internal credit

Web3 wallet feature

Custodial wallets, balances, top-up UX

Referral codes (refcodes)

Attribution, ledger, on-chain mint

Affiliate enablement

Dual-rail ERP commission + token rewards

Refcodes architecture

viem minter, env contract, cron

Customization guide

ring-config.json, locales, feature flags

Philosophy

Principle	Ring implementation
Utility-first	Tokens gate features and settle platform fees — not investment promises
Postgres-primary	Credit balances and subscriptions live in `users.data` + `ring_subscriptions` when `DB_BACKEND_MODE=k8s-postgres-fcm`
Fiat + credit coexist	WayForPay/Stripe for card rails; `credit_balance` spends the same ledger
Per-clone branding	`ring-config.json` → `tokens.native.symbol` drives UI copy via `getNativeTokenSymbol()`

Three economic layers

Layer 1 — Off-chain credit ledger (production path today)

Data model

Store	Location	Contents
Balance	`users.data.credit_balance`	`amount`, `main_currency_equivalent`, `subscription_active`, `subscription_next_payment`
History	`users.data.credit_transactions`	Typed ledger entries with optional `tx_hash`, `order_id`
Subscriptions	`ring_subscriptions` collection	Status, `next_payment_due`, `failed_attempts`, `auto_renew`

Schema comment: users.data JSONB in data/schema.sql v4+.

Core services

Service	Path	Role
creditBalanceService	`features/wallet/services/credit-balance-service.ts`	Balance read/write, spend, top-up, membership fee debit, tunnel publish on change
SubscriptionService	`services/membership/subscription-service.ts`	Create/cancel/renew; 1 RING/month; upgrades `membership.tier` → `member`
PriceOracleService	`features/wallet/services/native-token-price-oracle.ts`	RING/USD via viem + Chainlink/CoinGecko/CMC/Binance fallbacks
Internal credit checkout	`lib/payments/processors/credit-balance.processor.ts`	PaymentConductor rail for store + membership spend

Membership economics (reference)

Parameter	Value	Where enforced
Monthly fee	1 utility token	`subscription-service.ts` (`membershipFee = '1.0'`)
Billing period	30 days	`next_payment_due` timestamp math
Recommended buffer	12 tokens (1 year)	`RingToken.MIN_SUBSCRIPTION_BALANCE` on-chain; UI warnings via credit limits
Role gate	SUBSCRIBER+ to subscribe	`POST /api/membership/subscription/create`

User tops up or receives airdrop
POST /api/wallet/credit/topup (admin/ops) or fulfillment after wallet_topup PaymentConductor purpose adds credits via creditBalanceService.addCredits().
User creates subscription
POST /api/membership/subscription/create debits 1 RING credit, writes ring_subscriptions, sets credit_balance.subscription_active.
Contract env gate
This route returns 503 until RING_TOKEN_CONTRACT_ADDRESS and RING_MEMBERSHIP_CONTRACT_ADDRESS are set — even though the debit is ledger-based. Set deployed addresses (or placeholder addresses in dev) to unlock the API.
Store checkout with credit
When PAYMENT_STORE_ALLOW_CREDIT=true, PaymentConductor credit_balance rail spends credits for orders in currencies allowed by PAYMENT_CREDIT_BALANCE_ACCEPTED_ORDER_CURRENCIES (defaults to PAYMENT_FIAT_CURRENCY).

Credit API surface

Endpoint	Method	Purpose
`/api/wallet/credit/balance`	GET	Balance + subscription snapshot
`/api/wallet/credit/history`	GET	Paginated transaction history
`/api/wallet/credit/topup`	POST	Add credits
`/api/wallet/credit/spend`	POST	Spend credits
`/api/prices/ring-usd`	GET	Oracle price for UI and receipts
`/api/membership/subscription/create`	POST	Start membership

Client hook: hooks/use-credit-balance.ts — initial REST fetch + tunnel push updates (no polling).

Layer 2 — On-chain RING reference contracts

Ring ships UUPS upgradeable reference contracts for clones that want treasury-controlled ERC-20 utility on Polygon (chainId 137).

RingToken (`contracts/RingToken.sol`)

Constant	Value
`INITIAL_SUPPLY`	1,000,000,000 RING → minted to treasury at `initialize`
`MEMBERSHIP_FEE`	1 RING / month
`MIN_SUBSCRIPTION_BALANCE`	12 RING
Decimals	18

Owner functions: setMembershipContract, setTreasury, creditTokens (treasury airdrops), pause / unpause.

Membership-only: deductMembershipFee(member) — callable only by linked Membership.

Membership (`contracts/Membership.sol`)

Constant	Value
`SUBSCRIPTION_PERIOD`	30 days
`GRACE_PERIOD`	7 days
`MAX_FAILED_ATTEMPTS`	3 → `EXPIRED`

Statuses: INACTIVE, ACTIVE, EXPIRED, CANCELLED, SUSPENDED.

On-chain lifecycle: createSubscription() → processBatchPayments(batchSize) (operator/cron) → cancelSubscription() / admin suspend.

Utility token — not a security pitch

RING reference tokenomics gate platform access. Consult counsel before marketing yield, profit expectations, or exchange listings.

On-chain ↔ ledger sync

Deploy reference contracts

Install and compile
Testnet deploy (script references Polygon Mumbai — migrate to Amoy or fork script for current testnets)
Deploy order: RingToken → Membership → ringToken.setMembershipContract(...). Output: contracts/deployments/mumbai-deployment.json.
Mainnet — scripts/deploy-mainnet.js after audit + multisig treasury. Fund deployer with POL; use Alchemy/Infura RPC (not anonymous polygon-rpc.com).
Wire env and redeploy app
Client metadata: constants/web3.ts — TOKEN_CONFIGS, staking scaffold (RING_STAKING_ADDRESS, 20% APR placeholder).

Layer 3 — Referral token rewards (refcodes)

Growth economics are separate from membership fees. When a referred user completes a qualifying purchase, the platform mints or transfers reward tokens via ReferralRewards (UUPS).

Piece	Path / contract
Contract	`contracts/contracts-src/ReferralRewards.sol`
Deploy	`npx hardhat run scripts/deploy-referral-rewards.js --network polygon`
Minter	`features/refcodes/services/reward-minter.ts` (viem)
Ops runbook	`REFERRAL-ONCHAIN-OPS.md` (repo root)

Clone install helper: scripts/install-refcodes-module.sh.

Payment rails — fiat, credit, native token

Token economics intersect PaymentConductor — one ledger (payment_transactions), multiple rails.

Rail	Env	Use
`merchant_redirect`	WayForPay / Stripe / PayPal	Card checkout, membership upgrade fiat, public_pool_contribution jar chip-ins
`credit_balance`	`PAYMENT_STORE_ALLOW_CREDIT=true`	Spend `credit_balance` at store
`native_token`	`PAYMENT_STORE_ALLOW_TOKEN=true`	On-chain token checkout (advanced)

Apply data/migrations/004_payment_transactions.sql before production payments. Full operator guide: Payment integration.

White-label token branding

`ring-config.json`

Sidebar and public pages

ring-config.json → sidebar.quickLinks includes about.sidebar.tokenEconomy → /token-economy on your clone's marketing site.

Staking and vendor gates

constants/web3.ts defines a RING staking pool scaffold (20% APR, 100 RING minimum) — configure addresses per clone or disable in UI.

components/vendor/staking-card.tsx supports per-product vendor stake requirements (tokenSymbol, requiredStake) — use for agent/vendor activation flows, not global protocol rules.

Design your clone economy

Classify the token
Recommended
Utility token — listings, membership, marketplace fees. No profit promises.
Security tokens and multi-token splits need legal review before launch.
Set parameters
Map fees in constants/store.ts / ERP commission helpers for marketplace cuts.
3
Integrate with Ring services
1. Deploy or fork RingToken.sol / Membership.sol (optional)
2. Update ring-config.json + constants/web3.ts addresses
3. Set RING_TOKEN_CONTRACT_ADDRESS + membership env vars
4. Enable PAYMENT_STORE_ALLOW_CREDIT if store should spend credits
5. Deploy ReferralRewards when refcodes on-chain rewards are live
6. Smoke: npm run smoke:pipelines (see scripts/PIPELINES.md)

Health metrics

Metric	Signal
Active subscriptions / failed payment rate	`ring_subscriptions` + credit history
Credit ledger vs treasury	Reconcile `users.data.credit_balance` with on-chain treasury movements
Referral mint queue	`referral_rewards` status + `/admin/refcodes`
Oracle freshness	`PriceOracleService` cache TTL and fallback usage
Payment ledger	`payment_transactions` by `rail` and `processor`

Legal and launch checklist

Jurisdiction

Immediate

Choose: RING reference vs branded ERC-20 fork
Set ring-config.json token symbol + public token economy page
Multisig treasury and contract owner keys
Tokenomics paper (utility, fees, treasury — no investment claims)

Development

Postgres migrations through 004_payment_transactions + 005_refcodes_schema
Wire credit + PaymentConductor env vars
Deploy testnet contracts; run contracts/test
Smoke membership create + store credit checkout

Launch

Mainnet deploy after audit
Verify contracts on Polygonscan
Enable refcodes minter (REFERRAL-ONCHAIN-OPS.md)
Monitor subscription metrics and treasury alerts

Payment integration

Webhooks, WayForPay, Stripe setup

Database migrations

refcodes, payment_transactions, schema order

Ring customization opportunities

Web3 specialists on the platform

Documentation

Quick entry (CTOs · auditors · agents)

Documentation

Quick entry (CTOs · auditors · agents)

Documentation

Quick entry (CTOs · auditors · agents)

Loading documentation...

Documentation

Quick entry (CTOs · auditors · agents)

Loading documentation...

Documentation

Quick entry (CTOs · auditors · agents)

Loading documentation...

Documentation

Quick entry (CTOs · auditors · agents)

Loading documentation...

Loading documentation...

Loading documentation...

Token Economics Setup

Payment integration

Web3 wallet feature

Referral codes (refcodes)

Affiliate enablement

Refcodes architecture

Customization guide

Philosophy

Layer 1 — Off-chain credit ledger (production path today)

Data model

Core services

Membership economics (reference)

User tops up or receives airdrop

User creates subscription

Store checkout with credit

Credit API surface

Layer 2 — On-chain RING reference contracts

RingToken (contracts/RingToken.sol)

Membership (contracts/Membership.sol)

Deploy reference contracts

Layer 3 — Referral token rewards (refcodes)

Payment rails — fiat, credit, native token

White-label token branding

ring-config.json

Sidebar and public pages

Staking and vendor gates

Design your clone economy

Classify the token

Set parameters

Integrate with Ring services

Health metrics

Legal and launch checklist

Immediate

Development

Launch

Payment integration

Database migrations

Ring customization opportunities

Token Economics Setup

Payment integration

Web3 wallet feature

Referral codes (refcodes)

Affiliate enablement

Refcodes architecture

Customization guide

Philosophy

Layer 1 — Off-chain credit ledger (production path today)

Data model

Core services

Membership economics (reference)

User tops up or receives airdrop

User creates subscription

Store checkout with credit

Credit API surface

Layer 2 — On-chain RING reference contracts

RingToken (contracts/RingToken.sol)

Membership (contracts/Membership.sol)

Deploy reference contracts

Layer 3 — Referral token rewards (refcodes)

Payment rails — fiat, credit, native token

White-label token branding

ring-config.json

RingToken (`contracts/RingToken.sol`)

Membership (`contracts/Membership.sol`)

`ring-config.json`

RingToken (`contracts/RingToken.sol`)

Membership (`contracts/Membership.sol`)

`ring-config.json`

RingToken (`contracts/RingToken.sol`)

Membership (`contracts/Membership.sol`)

`ring-config.json`