Loading documentation...
Preparing Ring content
Концепції, цінність і типові сценарії
Концепції, цінність і типові сценарії
Preparing Ring content
Preparing Ring content
Preparing Ring content
WalletConductor — це фасад оркестрації Ring Platform для грошових шляхів кастодіального native-token web3 і фіатного кредиту. Тонкі адаптери (app/_actions/wallet.ts, /api/wallet/token/*, /api/wallet/desk/*, покупка на NFT-маркетплейсі) викликають conductor; він делегує PSP до PaymentConductor, а обчислення реєстру — до creditBalanceService.
Використовуйте вкладки Founder / Developer на бічній панелі документації, щоб відфільтрувати цю сторінку. Користувацький UI продукту: Wallet. Реєстр HTTP/actions: Wallet API.
Один шар для грошових операцій гаманця: картка → кредитні бали, desk → native token, кастодіальні gasless-відправлення, довільне списання кредиту та покупки на NFT-маркетплейсі. Облік фіатних витрат використовує credit.creditBalanceUnitToMainCurrency (зазвичай 1) — ніколи не oracle desk. Зовнішні EVM POL/USDT через POST /api/wallet/transfer залишаються поза цим conductor.
| Можливість | Метод | Результат |
|---|---|---|
| Картка → кредитні бали | initiateTopUp | PaymentConductor wallet_topup → кредит фіатного реєстру |
| Картка/PayPal → treasury native | initiateNativeOnramp | PaymentConductor native_token_onramp (confidential+) |
| Token Desk | quoteDesk / executeDesk | Кредитні бали ↔ native за oracle desk (subscriber+) |
| Кастодіальне відправлення | transferNative | Gasless-переказ native + рядок у wallet_transactions |
| Native-баланс | getNativeBalance | Кастодіальний баланс native chain платформи |
Не входить до WalletConductor: дебет checkout магазину/членства (PaymentConductor credit_balance / SubscriptionConductor) і зовнішній EVM POST /api/wallet/transfer. Це навмисно окремі шляхи SSOT.
| Ставка | SSOT | Використовують |
|---|---|---|
| Облік фіатного кредиту | ring-config.json → credit.creditBalanceUnitToMainCurrency (зазвичай 1) через getMainCurrencyCreditAccountingRate() | spendCredits, дебетова сторона desk, checkout credit_balance |
| Oracle Token Desk | platform_settings.web3.oracle.nativePerMainCurrency через native-token-oracle.ts | Лише бали ↔ native у quoteDesk / executeDesk |
WalletConductor — грошовий хребет для оператора за продуктом Wallet. Учасники бачать UI поповнення, desk і відправлення; ваш клон залишається узгодженим, бо кожен шлях проходить через один фасад, а не через розрізнені виклики PSP і реєстру.
Будь-який авторизований учасник купує кредитні бали карткою. Бали — це одиниці фіатного реєстру (1:1 з mainCurrency магазину, коли creditBalanceUnitToMainCurrency дорівнює 1).
Учасник із рівнем Subscriber+ конвертує бали ↔ native за oracle desk. Зміна nativePerMainCurrency ніколи не переписує математику checkout магазину чи довільного списання кредиту.
Confidential+ картка/PayPal → treasury native (під керуванням feature flag). Кредитні бали додаються.
WalletConductor — це фасад оркестрації Ring Platform для грошових шляхів кастодіального native-token web3 і фіатного кредиту. Тонкі адаптери (app/_actions/wallet.ts, /api/wallet/token/*, /api/wallet/desk/*, покупка на NFT-маркетплейсі) викликають conductor; він делегує PSP до PaymentConductor, а обчислення реєстру — до creditBalanceService.
Використовуйте вкладки Founder / Developer на бічній панелі документації, щоб відфільтрувати цю сторінку. Користувацький UI продукту: Wallet. Реєстр HTTP/actions: Wallet API.
Один шар для грошових операцій гаманця: картка → кредитні бали, desk → native token, кастодіальні gasless-відправлення, довільне списання кредиту та покупки на NFT-маркетплейсі. Облік фіатних витрат використовує credit.creditBalanceUnitToMainCurrency (зазвичай 1) — ніколи не oracle desk. Зовнішні EVM POL/USDT через POST /api/wallet/transfer залишаються поза цим conductor.
| Можливість | Метод | Результат |
|---|---|---|
| Картка → кредитні бали | initiateTopUp | PaymentConductor wallet_topup → кредит фіатного реєстру |
| Картка/PayPal → treasury native | initiateNativeOnramp | PaymentConductor native_token_onramp (confidential+) |
| Token Desk | quoteDesk / executeDesk | Кредитні бали ↔ native за oracle desk (subscriber+) |
| Кастодіальне відправлення | transferNative | Gasless-переказ native + рядок у wallet_transactions |
| Native-баланс | getNativeBalance | Кастодіальний баланс native chain платформи |
Не входить до WalletConductor: дебет checkout магазину/членства (PaymentConductor credit_balance / SubscriptionConductor) і зовнішній EVM POST /api/wallet/transfer. Це навмисно окремі шляхи SSOT.
| Ставка | SSOT | Використовують |
|---|---|---|
| Облік фіатного кредиту | ring-config.json → credit.creditBalanceUnitToMainCurrency (зазвичай 1) через getMainCurrencyCreditAccountingRate() | spendCredits, дебетова сторона desk, checkout credit_balance |
| Oracle Token Desk | platform_settings.web3.oracle.nativePerMainCurrency через native-token-oracle.ts | Лише бали ↔ native у quoteDesk / executeDesk |
WalletConductor — грошовий хребет для оператора за продуктом Wallet. Учасники бачать UI поповнення, desk і відправлення; ваш клон залишається узгодженим, бо кожен шлях проходить через один фасад, а не через розрізнені виклики PSP і реєстру.
Будь-який авторизований учасник купує кредитні бали карткою. Бали — це одиниці фіатного реєстру (1:1 з mainCurrency магазину, коли creditBalanceUnitToMainCurrency дорівнює 1).
Учасник із рівнем Subscriber+ конвертує бали ↔ native за oracle desk. Зміна nativePerMainCurrency ніколи не переписує математику checkout магазину чи довільного списання кредиту.
Confidential+ картка/PayPal → treasury native (під керуванням feature flag). Кредитні бали додаються.
WalletConductor — це фасад оркестрації Ring Platform для грошових шляхів кастодіального native-token web3 і фіатного кредиту. Тонкі адаптери (app/_actions/wallet.ts, /api/wallet/token/*, /api/wallet/desk/*, покупка на NFT-маркетплейсі) викликають conductor; він делегує PSP до PaymentConductor, а обчислення реєстру — до creditBalanceService.
Використовуйте вкладки Founder / Developer на бічній панелі документації, щоб відфільтрувати цю сторінку. Користувацький UI продукту: Wallet. Реєстр HTTP/actions: Wallet API.
Один шар для грошових операцій гаманця: картка → кредитні бали, desk → native token, кастодіальні gasless-відправлення, довільне списання кредиту та покупки на NFT-маркетплейсі. Облік фіатних витрат використовує credit.creditBalanceUnitToMainCurrency (зазвичай 1) — ніколи не oracle desk. Зовнішні EVM POL/USDT через POST /api/wallet/transfer залишаються поза цим conductor.
| Можливість | Метод | Результат |
|---|---|---|
| Картка → кредитні бали | initiateTopUp | PaymentConductor wallet_topup → кредит фіатного реєстру |
| Картка/PayPal → treasury native | initiateNativeOnramp | PaymentConductor native_token_onramp (confidential+) |
| Token Desk | quoteDesk / executeDesk | Кредитні бали ↔ native за oracle desk (subscriber+) |
| Кастодіальне відправлення | transferNative | Gasless-переказ native + рядок у wallet_transactions |
| Native-баланс | getNativeBalance | Кастодіальний баланс native chain платформи |
Не входить до WalletConductor: дебет checkout магазину/членства (PaymentConductor credit_balance / SubscriptionConductor) і зовнішній EVM POST /api/wallet/transfer. Це навмисно окремі шляхи SSOT.
| Ставка | SSOT | Використовують |
|---|---|---|
| Облік фіатного кредиту | ring-config.json → credit.creditBalanceUnitToMainCurrency (зазвичай 1) через getMainCurrencyCreditAccountingRate() | spendCredits, дебетова сторона desk, checkout credit_balance |
| Oracle Token Desk | platform_settings.web3.oracle.nativePerMainCurrency через native-token-oracle.ts | Лише бали ↔ native у quoteDesk / executeDesk |
WalletConductor — грошовий хребет для оператора за продуктом Wallet. Учасники бачать UI поповнення, desk і відправлення; ваш клон залишається узгодженим, бо кожен шлях проходить через один фасад, а не через розрізнені виклики PSP і реєстру.
Будь-який авторизований учасник купує кредитні бали карткою. Бали — це одиниці фіатного реєстру (1:1 з mainCurrency магазину, коли creditBalanceUnitToMainCurrency дорівнює 1).
Учасник із рівнем Subscriber+ конвертує бали ↔ native за oracle desk. Зміна nativePerMainCurrency ніколи не переписує математику checkout магазину чи довільного списання кредиту.
Confidential+ картка/PayPal → treasury native (під керуванням feature flag). Кредитні бали додаються.
| Довільне списання кредиту | spendCredits | Дебет фіатного реєстру за creditBalanceUnitToMainCurrency |
| Створення гаманця | ensureNativeWallet | Атомарні мультичейн-гаманці (безпечні для OAuth, без сесії) |
| Мінімальний кредитний поріг | ensureFunded | Створення із сесією + мінімальний кредитний залишок |
| Покупка на NFT-маркетплейсі | purchaseNftListing | Ідемпотентна покупка RING через Solana market client |
Підтвердьте SSOT одиниці кредиту
Залишайте credit.creditBalanceUnitToMainCurrency: 1 у ring-config.json, якщо навмисно не масштабуєте бали відносно фіату. Зміни oracle desk не впливають на checkout магазину або POST /api/wallet/credit/spend.
Відокремлюйте oracle desk від фіату
Superadmin налаштовує nativePerMainCurrency лише для конвертації desk. Не очікуйте, що ця ставка буде використана для довільного списання кредиту.
Обережно вмикайте native onramp
Native onramp карткою доступний для confidential+ і керується feature flag (CONFIDENTIAL_TOKEN_ONRAMP / desk nativeTokenOnramp). Не вмикайте його, доки treasury ops і compliance не готові.
Надавайте перевагу Server Actions з UI. Залишайте HTTP wallet routes для MCP і клієнтів без React. Надавайте перевагу /api/wallet/token/* — застарілі aliases /api/wallet/ring/* видалені.
features/wallet/services/ensure-wallet.ts| Кредитний реєстр | features/wallet/services/credit-balance-service.ts |
| Фіатна ставка | lib/ring-config-core.ts → getCreditUnitToMainCurrencyRate / lib/payments/credit-balance.ts → getMainCurrencyCreditAccountingRate |
| Desk | features/wallet/chains/solana/desk-service.ts |
| Oracle desk | features/wallet/services/native-token-oracle.ts |
| Кастодіальне відправлення | features/wallet/chains/native-token-transfer-service.ts |
| Checkout PSP | lib/payments/conductor/payment-conductor.ts |
| Кредитний rail магазину | lib/payments/processors/credit-balance.processor.ts (PaymentConductor — не WC) |
| Actions | app/_actions/wallet.ts |
| Покупка NFT | features/nft-market/services/solana-market-client.ts |
| Метод | Auth / gates | Примітки |
|---|---|---|
ensureNativeWallet | Caller supplies id | Безпечно для OAuth; повертає { ok, native, wallets } |
ensureFunded | Session | Створює + необов’язковий мінімум кредиту |
initiateTopUp | Session | Сума 25–2000; purpose wallet_topup |
initiateNativeOnramp | Session + confidential metadata | Необов’язковий processor paypal/stripe/wayforpay |
quoteDesk / executeDesk | assertTokenDeskSubscriberAccess | SSOT Solana desk |
transferNative | Caller supplies userId | Записує wallet_transactions; працює з контактами |
spendCredits | Caller supplies userId | Типово використовує getMainCurrencyCreditAccountingRate() для usdRate |
purchaseNftListing | Idempotency key | Статуси: pending → submitted → confirmed / failed |
getNativeBalance | Caller supplies userId | Тонка обгортка transfer service |
У вкладці Card processor не передається (SSOT з env). Вкладка PayPal задає processor=paypal. Клієнт: lib/payments/checkout-redirect.ts.
| Key | Роль |
|---|---|
WALLET_ENCRYPTION_KEY | Шифрування кастодіальних ключів |
SOLANA_RPC_URL / SOLANA_TREASURY_PRIVATE_KEY | Кастодіальний Solana + спонсорування gas |
CONFIDENTIAL_TOKEN_ONRAMP / desk nativeTokenOnramp | Gate native onramp карткою |
credit.creditBalanceUnitToMainCurrency | Множник обліку фіатного реєстру |
ORACLE_QUOTE_SECRET / RING_ORACLE_DEFAULT_RATE | HMAC котирування desk + fallback |
PSP rails, які використовують поповнення й onramp.
| Довільне списання кредиту | spendCredits | Дебет фіатного реєстру за creditBalanceUnitToMainCurrency |
| Створення гаманця | ensureNativeWallet | Атомарні мультичейн-гаманці (безпечні для OAuth, без сесії) |
| Мінімальний кредитний поріг | ensureFunded | Створення із сесією + мінімальний кредитний залишок |
| Покупка на NFT-маркетплейсі | purchaseNftListing | Ідемпотентна покупка RING через Solana market client |
Підтвердьте SSOT одиниці кредиту
Залишайте credit.creditBalanceUnitToMainCurrency: 1 у ring-config.json, якщо навмисно не масштабуєте бали відносно фіату. Зміни oracle desk не впливають на checkout магазину або POST /api/wallet/credit/spend.
Відокремлюйте oracle desk від фіату
Superadmin налаштовує nativePerMainCurrency лише для конвертації desk. Не очікуйте, що ця ставка буде використана для довільного списання кредиту.
Обережно вмикайте native onramp
Native onramp карткою доступний для confidential+ і керується feature flag (CONFIDENTIAL_TOKEN_ONRAMP / desk nativeTokenOnramp). Не вмикайте його, доки treasury ops і compliance не готові.
Надавайте перевагу Server Actions з UI. Залишайте HTTP wallet routes для MCP і клієнтів без React. Надавайте перевагу /api/wallet/token/* — застарілі aliases /api/wallet/ring/* видалені.
features/wallet/services/ensure-wallet.ts| Кредитний реєстр | features/wallet/services/credit-balance-service.ts |
| Фіатна ставка | lib/ring-config-core.ts → getCreditUnitToMainCurrencyRate / lib/payments/credit-balance.ts → getMainCurrencyCreditAccountingRate |
| Desk | features/wallet/chains/solana/desk-service.ts |
| Oracle desk | features/wallet/services/native-token-oracle.ts |
| Кастодіальне відправлення | features/wallet/chains/native-token-transfer-service.ts |
| Checkout PSP | lib/payments/conductor/payment-conductor.ts |
| Кредитний rail магазину | lib/payments/processors/credit-balance.processor.ts (PaymentConductor — не WC) |
| Actions | app/_actions/wallet.ts |
| Покупка NFT | features/nft-market/services/solana-market-client.ts |
| Метод | Auth / gates | Примітки |
|---|---|---|
ensureNativeWallet | Caller supplies id | Безпечно для OAuth; повертає { ok, native, wallets } |
ensureFunded | Session | Створює + необов’язковий мінімум кредиту |
initiateTopUp | Session | Сума 25–2000; purpose wallet_topup |
initiateNativeOnramp | Session + confidential metadata | Необов’язковий processor paypal/stripe/wayforpay |
quoteDesk / executeDesk | assertTokenDeskSubscriberAccess | SSOT Solana desk |
transferNative | Caller supplies userId | Записує wallet_transactions; працює з контактами |
spendCredits | Caller supplies userId | Типово використовує getMainCurrencyCreditAccountingRate() для usdRate |
purchaseNftListing | Idempotency key | Статуси: pending → submitted → confirmed / failed |
getNativeBalance | Caller supplies userId | Тонка обгортка transfer service |
У вкладці Card processor не передається (SSOT з env). Вкладка PayPal задає processor=paypal. Клієнт: lib/payments/checkout-redirect.ts.
| Key | Роль |
|---|---|
WALLET_ENCRYPTION_KEY | Шифрування кастодіальних ключів |
SOLANA_RPC_URL / SOLANA_TREASURY_PRIVATE_KEY | Кастодіальний Solana + спонсорування gas |
CONFIDENTIAL_TOKEN_ONRAMP / desk nativeTokenOnramp | Gate native onramp карткою |
credit.creditBalanceUnitToMainCurrency | Множник обліку фіатного реєстру |
ORACLE_QUOTE_SECRET / RING_ORACLE_DEFAULT_RATE | HMAC котирування desk + fallback |
PSP rails, які використовують поповнення й onramp.
| Довільне списання кредиту | spendCredits | Дебет фіатного реєстру за creditBalanceUnitToMainCurrency |
| Створення гаманця | ensureNativeWallet | Атомарні мультичейн-гаманці (безпечні для OAuth, без сесії) |
| Мінімальний кредитний поріг | ensureFunded | Створення із сесією + мінімальний кредитний залишок |
| Покупка на NFT-маркетплейсі | purchaseNftListing | Ідемпотентна покупка RING через Solana market client |
Підтвердьте SSOT одиниці кредиту
Залишайте credit.creditBalanceUnitToMainCurrency: 1 у ring-config.json, якщо навмисно не масштабуєте бали відносно фіату. Зміни oracle desk не впливають на checkout магазину або POST /api/wallet/credit/spend.
Відокремлюйте oracle desk від фіату
Superadmin налаштовує nativePerMainCurrency лише для конвертації desk. Не очікуйте, що ця ставка буде використана для довільного списання кредиту.
Обережно вмикайте native onramp
Native onramp карткою доступний для confidential+ і керується feature flag (CONFIDENTIAL_TOKEN_ONRAMP / desk nativeTokenOnramp). Не вмикайте його, доки treasury ops і compliance не готові.
Надавайте перевагу Server Actions з UI. Залишайте HTTP wallet routes для MCP і клієнтів без React. Надавайте перевагу /api/wallet/token/* — застарілі aliases /api/wallet/ring/* видалені.
features/wallet/services/ensure-wallet.ts| Кредитний реєстр | features/wallet/services/credit-balance-service.ts |
| Фіатна ставка | lib/ring-config-core.ts → getCreditUnitToMainCurrencyRate / lib/payments/credit-balance.ts → getMainCurrencyCreditAccountingRate |
| Desk | features/wallet/chains/solana/desk-service.ts |
| Oracle desk | features/wallet/services/native-token-oracle.ts |
| Кастодіальне відправлення | features/wallet/chains/native-token-transfer-service.ts |
| Checkout PSP | lib/payments/conductor/payment-conductor.ts |
| Кредитний rail магазину | lib/payments/processors/credit-balance.processor.ts (PaymentConductor — не WC) |
| Actions | app/_actions/wallet.ts |
| Покупка NFT | features/nft-market/services/solana-market-client.ts |
| Метод | Auth / gates | Примітки |
|---|---|---|
ensureNativeWallet | Caller supplies id | Безпечно для OAuth; повертає { ok, native, wallets } |
ensureFunded | Session | Створює + необов’язковий мінімум кредиту |
initiateTopUp | Session | Сума 25–2000; purpose wallet_topup |
initiateNativeOnramp | Session + confidential metadata | Необов’язковий processor paypal/stripe/wayforpay |
quoteDesk / executeDesk | assertTokenDeskSubscriberAccess | SSOT Solana desk |
transferNative | Caller supplies userId | Записує wallet_transactions; працює з контактами |
spendCredits | Caller supplies userId | Типово використовує getMainCurrencyCreditAccountingRate() для usdRate |
purchaseNftListing | Idempotency key | Статуси: pending → submitted → confirmed / failed |
getNativeBalance | Caller supplies userId | Тонка обгортка transfer service |
У вкладці Card processor не передається (SSOT з env). Вкладка PayPal задає processor=paypal. Клієнт: lib/payments/checkout-redirect.ts.
| Key | Роль |
|---|---|
WALLET_ENCRYPTION_KEY | Шифрування кастодіальних ключів |
SOLANA_RPC_URL / SOLANA_TREASURY_PRIVATE_KEY | Кастодіальний Solana + спонсорування gas |
CONFIDENTIAL_TOKEN_ONRAMP / desk nativeTokenOnramp | Gate native onramp карткою |
credit.creditBalanceUnitToMainCurrency | Множник обліку фіатного реєстру |
ORACLE_QUOTE_SECRET / RING_ORACLE_DEFAULT_RATE | HMAC котирування desk + fallback |
PSP rails, які використовують поповнення й onramp.