Loading documentation...
Preparing Ring content
Concepts, value, and typical clone scenarios — less code.
Concepts, value, and typical clone scenarios — less code.
Preparing Ring content
Preparing Ring content
Preparing Ring content
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.
PaymentConductor — WayForPay, Stripe, internal credit
Custodial wallets, balances, top-up UX
Attribution, ledger, on-chain mint
Dual-rail ERP commission + token rewards
viem minter, env contract, cron
ring-config.json, locales, feature flags
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() |
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.
| 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+.
| 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 |
| 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 |
POST /api/wallet/credit/topup (admin/ops) or fulfillment after wallet_topup PaymentConductor purpose adds credits via creditBalanceService.addCredits().
POST /api/membership/subscription/create debits 1 RING credit, writes ring_subscriptions, sets credit_balance.subscription_active.
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.
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).
| 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).
Ring ships UUPS upgradeable reference contracts for clones that want treasury-controlled ERC-20 utility on Polygon (chainId 137).
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.
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.
RING reference tokenomics gate platform access. Consult counsel before marketing yield, profit expectations, or exchange listings.
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.
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).
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.
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.
ring-config.jsongetNativeTokenSymbol() 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.
ring-config.json → sidebar.quickLinks includes about.sidebar.tokenEconomy → /token-economy on your clone's marketing site.
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.
Utility token — listings, membership, marketplace fees. No profit promises.
Security tokens and multi-token splits need legal review before launch.
Map fees in constants/store.ts / ERP commission helpers for marketplace cuts.
RingToken.sol / Membership.sol (optional)ring-config.json + constants/web3.ts addressesRING_TOKEN_CONTRACT_ADDRESS + membership env varsPAYMENT_STORE_ALLOW_CREDIT if store should spend creditsReferralRewards when refcodes on-chain rewards are livenpm run smoke:pipelines (see scripts/PIPELINES.md)| 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 |
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).
ring-config.json token symbol + public token economy page004_payment_transactions + 005_refcodes_schemacontracts/testREFERRAL-ONCHAIN-OPS.md)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.
PaymentConductor — WayForPay, Stripe, internal credit
Custodial wallets, balances, top-up UX
Attribution, ledger, on-chain mint
Dual-rail ERP commission + token rewards
viem minter, env contract, cron
ring-config.json, locales, feature flags
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() |
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.
| 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+.
| 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 |
| 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 |
POST /api/wallet/credit/topup (admin/ops) or fulfillment after wallet_topup PaymentConductor purpose adds credits via creditBalanceService.addCredits().
POST /api/membership/subscription/create debits 1 RING credit, writes ring_subscriptions, sets credit_balance.subscription_active.
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.
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).
| 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).
Ring ships UUPS upgradeable reference contracts for clones that want treasury-controlled ERC-20 utility on Polygon (chainId 137).
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.
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.
RING reference tokenomics gate platform access. Consult counsel before marketing yield, profit expectations, or exchange listings.
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.
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).
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.
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.
ring-config.jsongetNativeTokenSymbol() 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.
ring-config.json → sidebar.quickLinks includes about.sidebar.tokenEconomy → /token-economy on your clone's marketing site.
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.
Utility token — listings, membership, marketplace fees. No profit promises.
Security tokens and multi-token splits need legal review before launch.
Map fees in constants/store.ts / ERP commission helpers for marketplace cuts.
RingToken.sol / Membership.sol (optional)ring-config.json + constants/web3.ts addressesRING_TOKEN_CONTRACT_ADDRESS + membership env varsPAYMENT_STORE_ALLOW_CREDIT if store should spend creditsReferralRewards when refcodes on-chain rewards are livenpm run smoke:pipelines (see scripts/PIPELINES.md)| 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 |
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).
ring-config.json token symbol + public token economy page004_payment_transactions + 005_refcodes_schemacontracts/testREFERRAL-ONCHAIN-OPS.md)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.
PaymentConductor — WayForPay, Stripe, internal credit
Custodial wallets, balances, top-up UX
Attribution, ledger, on-chain mint
Dual-rail ERP commission + token rewards
viem minter, env contract, cron
ring-config.json, locales, feature flags
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() |
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.
| 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+.
| 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 |
| 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 |
POST /api/wallet/credit/topup (admin/ops) or fulfillment after wallet_topup PaymentConductor purpose adds credits via creditBalanceService.addCredits().
POST /api/membership/subscription/create debits 1 RING credit, writes ring_subscriptions, sets credit_balance.subscription_active.
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.
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).
| 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).
Ring ships UUPS upgradeable reference contracts for clones that want treasury-controlled ERC-20 utility on Polygon (chainId 137).
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.
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.
RING reference tokenomics gate platform access. Consult counsel before marketing yield, profit expectations, or exchange listings.
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.
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).
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.
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.
ring-config.jsongetNativeTokenSymbol() 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.
ring-config.json → sidebar.quickLinks includes about.sidebar.tokenEconomy → /token-economy on your clone's marketing site.
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.
Utility token — listings, membership, marketplace fees. No profit promises.
Security tokens and multi-token splits need legal review before launch.
Map fees in constants/store.ts / ERP commission helpers for marketplace cuts.
RingToken.sol / Membership.sol (optional)ring-config.json + constants/web3.ts addressesRING_TOKEN_CONTRACT_ADDRESS + membership env varsPAYMENT_STORE_ALLOW_CREDIT if store should spend creditsReferralRewards when refcodes on-chain rewards are livenpm run smoke:pipelines (see scripts/PIPELINES.md)| 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 |
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).
ring-config.json token symbol + public token economy page004_payment_transactions + 005_refcodes_schemacontracts/testREFERRAL-ONCHAIN-OPS.md)/api/membership/subscription/status |
| GET |
| Subscription state |
/api/membership/subscription/cancel | POST | Cancel |
/api/membership/payment/token | POST | Membership payment variants |
/api/membership/subscription/status |
| GET |
| Subscription state |
/api/membership/subscription/cancel | POST | Cancel |
/api/membership/payment/token | POST | Membership payment variants |
/api/membership/subscription/status |
| GET |
| Subscription state |
/api/membership/subscription/cancel | POST | Cancel |
/api/membership/payment/token | POST | Membership payment variants |