Loading documentation...
Preparing Ring content
Концепції, цінність і типові сценарії
Концепції, цінність і типові сценарії
Preparing Ring content
Preparing Ring content
Preparing Ring content
Ring Oracle — це server-only фасад курсів за адресою @/lib/ring-oracle. Він дає платіжному, wallet-, membership-, public-pool- і store-коду єдину лексику для вартості проєкту замість жорстко заданих символів токенів або фіатних валют.
Використовуйте Founder / Developer на бічній панелі документації, щоб відфільтрувати цю сторінку. Засновники бачать операторський шлях і поведінку checkout; розробники — перевірені модулі, маршрути, payload-и та smoke-команди.
| Номінал | Значення | Налаштована ідентичність |
|---|---|---|
credit_balance | Одиниця ledger, якою володіє проєкт | credit.creditBalanceUnitLabel і credit.creditBalanceUnitToMainCurrency |
native_token | Нативний токен клону | tokens.nativeToken.symbol |
main_currency | Фіат розрахунків проєкту | store.mainCurrency |
ValueDenomination містить рівно ці три значення. Символи валют на кшталт RING, USD або UAH — це значення для display/config, а не ідентифікатори номіналів.
GET і POST /api/prices/conversion приймають лише native_token і main_currency. credit_balance використовує поверхню обліку кредитів, а застарілі псевдоніми запитів RING / USD повертають HTTP 400.
Wallet, checkout, membership і фінансування спільноти визначають вартість проєкту через ту саму модель номіналів.
ProcessConductor оновлює фіатні курси presentment, а ручні перевизначення залишаються доступними в конфігурації клону.
Store відокремлює те, що бачить покупець, від фіатної валюти, яку стягує картковий або PayPal-шлюз.
Задайте основну валюту проєкту, підтримувані фіатні валюти presentment, підтримувані crypto-символи, native token і курс обліку кредитів у ring-config.json. Ring Oracle читає ці ідентичності проєкту; продуктовому коду не потрібен спеціальний випадок .
Залежність: PaymentConductor використовує курси Oracle, коли рейка перетинає номінали.
Той самий процес: display каталогу, presentment checkout і серверне створення charge.
Поглиблення: котирування Token Desk, облік кредитів і баланси native token.
Ring Oracle — це server-only фасад курсів за адресою @/lib/ring-oracle. Він дає платіжному, wallet-, membership-, public-pool- і store-коду єдину лексику для вартості проєкту замість жорстко заданих символів токенів або фіатних валют.
Використовуйте Founder / Developer на бічній панелі документації, щоб відфільтрувати цю сторінку. Засновники бачать операторський шлях і поведінку checkout; розробники — перевірені модулі, маршрути, payload-и та smoke-команди.
| Номінал | Значення | Налаштована ідентичність |
|---|---|---|
credit_balance | Одиниця ledger, якою володіє проєкт | credit.creditBalanceUnitLabel і credit.creditBalanceUnitToMainCurrency |
native_token | Нативний токен клону | tokens.nativeToken.symbol |
main_currency | Фіат розрахунків проєкту | store.mainCurrency |
ValueDenomination містить рівно ці три значення. Символи валют на кшталт RING, USD або UAH — це значення для display/config, а не ідентифікатори номіналів.
GET і POST /api/prices/conversion приймають лише native_token і main_currency. credit_balance використовує поверхню обліку кредитів, а застарілі псевдоніми запитів RING / USD повертають HTTP 400.
Wallet, checkout, membership і фінансування спільноти визначають вартість проєкту через ту саму модель номіналів.
ProcessConductor оновлює фіатні курси presentment, а ручні перевизначення залишаються доступними в конфігурації клону.
Store відокремлює те, що бачить покупець, від фіатної валюти, яку стягує картковий або PayPal-шлюз.
Задайте основну валюту проєкту, підтримувані фіатні валюти presentment, підтримувані crypto-символи, native token і курс обліку кредитів у ring-config.json. Ring Oracle читає ці ідентичності проєкту; продуктовому коду не потрібен спеціальний випадок .
Залежність: PaymentConductor використовує курси Oracle, коли рейка перетинає номінали.
Той самий процес: display каталогу, presentment checkout і серверне створення charge.
Поглиблення: котирування Token Desk, облік кредитів і баланси native token.
Ring Oracle — це server-only фасад курсів за адресою @/lib/ring-oracle. Він дає платіжному, wallet-, membership-, public-pool- і store-коду єдину лексику для вартості проєкту замість жорстко заданих символів токенів або фіатних валют.
Використовуйте Founder / Developer на бічній панелі документації, щоб відфільтрувати цю сторінку. Засновники бачать операторський шлях і поведінку checkout; розробники — перевірені модулі, маршрути, payload-и та smoke-команди.
| Номінал | Значення | Налаштована ідентичність |
|---|---|---|
credit_balance | Одиниця ledger, якою володіє проєкт | credit.creditBalanceUnitLabel і credit.creditBalanceUnitToMainCurrency |
native_token | Нативний токен клону | tokens.nativeToken.symbol |
main_currency | Фіат розрахунків проєкту | store.mainCurrency |
ValueDenomination містить рівно ці три значення. Символи валют на кшталт RING, USD або UAH — це значення для display/config, а не ідентифікатори номіналів.
GET і POST /api/prices/conversion приймають лише native_token і main_currency. credit_balance використовує поверхню обліку кредитів, а застарілі псевдоніми запитів RING / USD повертають HTTP 400.
Wallet, checkout, membership і фінансування спільноти визначають вартість проєкту через ту саму модель номіналів.
ProcessConductor оновлює фіатні курси presentment, а ручні перевизначення залишаються доступними в конфігурації клону.
Store відокремлює те, що бачить покупець, від фіатної валюти, яку стягує картковий або PayPal-шлюз.
Задайте основну валюту проєкту, підтримувані фіатні валюти presentment, підтримувані crypto-символи, native token і курс обліку кредитів у ring-config.json. Ring Oracle читає ці ідентичності проєкту; продуктовому коду не потрібен спеціальний випадок .
Залежність: PaymentConductor використовує курси Oracle, коли рейка перетинає номінали.
Той самий процес: display каталогу, presentment checkout і серверне створення charge.
Поглиблення: котирування Token Desk, облік кредитів і баланси native token.
RING/USDring-config.fx визначає провайдерів у такому порядку:
fx.byMainCurrency[store.mainCurrency]UAHfx.default для інших основних валютПоставлений за замовчуванням конфіг використовує NBU для UAH, а в інших випадках open_er_api. fx.manualOverrides має пріоритет над статичними курсами та live overlay.
Відкрийте /admin/web3/settings як superadmin, щоб оновити desk-курс native token, переглянути визначеного провайдера фіатного FX і час останнього отримання або примусово оновити FX. UI читає GET /api/admin/web3/settings і GET /api/admin/fx; запис відбувається відповідними POST-маршрутами.
Продакшен-планувальники викликають GET /api/cron/fx-feed-refresh. Встановіть CRON_SECRET і надішліть його як Bearer-токен. Маршрут записує запуск через ProcessConductor з ID pipeline fx-feed-refresh; застарілість потоку й надалі визначається налаштованим refreshHours.
Ліва навігаційна панель перемикається лише між main_currency (остання фіатна перевага покупця) і native_token. Droplist checkout дотримується цього режиму: фіат перелічує налаштовані SupportedCurrencies, native — налаштовані SupportedCrypto.
На кроці review рядки продуктів і підсумки конвертуються через convertPrice / displayPrice. Card і PayPal залишаються фіатними платежами: checkout передає фіатний paymentCurrency, а сервер повторно обчислює платіж із підсумку замовлення в основній валюті перед викликом PaymentConductor.
Crypto-сума в review checkout — це presentment, а не доказ того, що картковий шлюз стягне crypto. Платіжна рейка та paymentCurrency визначають settlement.
| Облік кредитів | lib/payments/credit-balance.ts | Хелпери обліку credit unit ↔ main |
| FX pipeline | lib/processes/fx/fx-feed-refresh.ts, lib/processes/registry.ts | Обробник, ID і cron-шлях ProcessConductor |
| API конвертації | app/api/prices/conversion/route.ts | Публічний контракт курсу й конвертації native ↔ main |
| SSR hydrate | app/layout.tsx | AuthenticatedAppShell прогріває й читає курси |
| Client provider | components/providers/app-client-shell.tsx | Передає initialExchangeRates у контекст валюти store |
| Контекст валюти store | features/store/currency-context.tsx | Режим display, конвертація, форматування, переваги |
| Presentment checkout | features/store/components/checkout/prebilling-page.tsx | Droplist fiat/crypto і фіатний paymentCurrency |
| Charge checkout | app/_actions/store-checkout-payment.ts | Серверний перерахунок фіату для card/PayPal |
Серверний код імпортує курси з фасаду, а не з модулів реалізації:
@/lib/ring-oracle імпортує server-only. Клієнтські компоненти отримують серіалізовані дані курсів через AuthenticatedAppShell, AppClientShell або безпечну для клієнта server action getLiveExchangeRates.
ID провайдерів: nbu, open_er_api і frankfurter. Жорстка перевірка замінює NBU на open_er_api, коли основна валюта не UAH.
Перевірка авторизації є умовною щодо CRON_SECRET, тому продакшен-розгортання мають його налаштувати. Відповідь містить runId ProcessConductor і метадані оновлення; вимкнений потік повертає успішний пропущений запуск. Курси зберігаються в platform_settings з id fx_feed (той самий гібридний шаблон JSONB, що й у desk oracle). Для погодинного оновлення кластера додайте k8s/cronjob-fx-feed-refresh.yaml.
GET /api/admin/fx повертає конфігурацію визначеного потоку, перевизначення, час отримання, зразок курсів і визначені курси для адміністраторів платформи. POST /api/admin/fx приймає { "force": true } і оновлює потік. Читання та запис desk-курсу залишаються на доступному лише superadmin маршруті /api/admin/web3/settings.
GET /api/prices/conversion повертає denominations: ["native_token", "main_currency"], обидві пари напрямків, курси та обернені курси, метадані джерела й ліміти від 0.000001 до 1000000.
amount має бути додатним десятковим рядком, а from має відрізнятися від to. Відповідь містить ідентифікатори номіналів, налаштовані display-валюти, вихідну суму, конвертовану суму, обмінний курс, timestamp, confidence, нульову комісію конвертації та метадані джерела.
{ "from": "RING", "to": "USD" } недійсний, навіть якщо це налаштовані символи клону. Надсилайте ідентифікатори номіналів, а не символи.
AuthenticatedAppShell викликає ensureFxFeedFresh(), потім getExchangeRates(). Якщо оновлення не вдається, оболонка залишає initialExchangeRates рівним null, а клієнтський код переходить до статичних курсів ring-config.
AppClientShell передає серіалізовані курси до StorePaymentMethodsProvider. Провайдер починає з цього SSR seed, потім після hydration викликає getLiveExchangeRates(), щоб конвертація в браузері залишалася узгодженою із серверним checkout.
StorePaymentMethodsProvider.displayMode — лише main_currency | native_token. PrebillingPage формує droplist із getSupportedCurrencies() або getSupportedCrypto(), зберігаючи фіатний paymentCurrency для card і PayPal. submitStoreCheckoutPayment перевіряє цей фіат щодо підтримуваного пулу presentment і перераховує суму на сервері.
Запустіть поставлений smoke smk46_ з ring-platform.org:
Smoke перевіряє реєстрацію pipeline, визначення й оновлення провайдера, round-trip сервісу native ↔ main, необов’язкові контракти conversion GET / POST, HTTP 400 для застарілих RING / USD і поведінку cron-відповіді.
RING/USDring-config.fx визначає провайдерів у такому порядку:
fx.byMainCurrency[store.mainCurrency]UAHfx.default для інших основних валютПоставлений за замовчуванням конфіг використовує NBU для UAH, а в інших випадках open_er_api. fx.manualOverrides має пріоритет над статичними курсами та live overlay.
Відкрийте /admin/web3/settings як superadmin, щоб оновити desk-курс native token, переглянути визначеного провайдера фіатного FX і час останнього отримання або примусово оновити FX. UI читає GET /api/admin/web3/settings і GET /api/admin/fx; запис відбувається відповідними POST-маршрутами.
Продакшен-планувальники викликають GET /api/cron/fx-feed-refresh. Встановіть CRON_SECRET і надішліть його як Bearer-токен. Маршрут записує запуск через ProcessConductor з ID pipeline fx-feed-refresh; застарілість потоку й надалі визначається налаштованим refreshHours.
Ліва навігаційна панель перемикається лише між main_currency (остання фіатна перевага покупця) і native_token. Droplist checkout дотримується цього режиму: фіат перелічує налаштовані SupportedCurrencies, native — налаштовані SupportedCrypto.
На кроці review рядки продуктів і підсумки конвертуються через convertPrice / displayPrice. Card і PayPal залишаються фіатними платежами: checkout передає фіатний paymentCurrency, а сервер повторно обчислює платіж із підсумку замовлення в основній валюті перед викликом PaymentConductor.
Crypto-сума в review checkout — це presentment, а не доказ того, що картковий шлюз стягне crypto. Платіжна рейка та paymentCurrency визначають settlement.
| Облік кредитів | lib/payments/credit-balance.ts | Хелпери обліку credit unit ↔ main |
| FX pipeline | lib/processes/fx/fx-feed-refresh.ts, lib/processes/registry.ts | Обробник, ID і cron-шлях ProcessConductor |
| API конвертації | app/api/prices/conversion/route.ts | Публічний контракт курсу й конвертації native ↔ main |
| SSR hydrate | app/layout.tsx | AuthenticatedAppShell прогріває й читає курси |
| Client provider | components/providers/app-client-shell.tsx | Передає initialExchangeRates у контекст валюти store |
| Контекст валюти store | features/store/currency-context.tsx | Режим display, конвертація, форматування, переваги |
| Presentment checkout | features/store/components/checkout/prebilling-page.tsx | Droplist fiat/crypto і фіатний paymentCurrency |
| Charge checkout | app/_actions/store-checkout-payment.ts | Серверний перерахунок фіату для card/PayPal |
Серверний код імпортує курси з фасаду, а не з модулів реалізації:
@/lib/ring-oracle імпортує server-only. Клієнтські компоненти отримують серіалізовані дані курсів через AuthenticatedAppShell, AppClientShell або безпечну для клієнта server action getLiveExchangeRates.
ID провайдерів: nbu, open_er_api і frankfurter. Жорстка перевірка замінює NBU на open_er_api, коли основна валюта не UAH.
Перевірка авторизації є умовною щодо CRON_SECRET, тому продакшен-розгортання мають його налаштувати. Відповідь містить runId ProcessConductor і метадані оновлення; вимкнений потік повертає успішний пропущений запуск. Курси зберігаються в platform_settings з id fx_feed (той самий гібридний шаблон JSONB, що й у desk oracle). Для погодинного оновлення кластера додайте k8s/cronjob-fx-feed-refresh.yaml.
GET /api/admin/fx повертає конфігурацію визначеного потоку, перевизначення, час отримання, зразок курсів і визначені курси для адміністраторів платформи. POST /api/admin/fx приймає { "force": true } і оновлює потік. Читання та запис desk-курсу залишаються на доступному лише superadmin маршруті /api/admin/web3/settings.
GET /api/prices/conversion повертає denominations: ["native_token", "main_currency"], обидві пари напрямків, курси та обернені курси, метадані джерела й ліміти від 0.000001 до 1000000.
amount має бути додатним десятковим рядком, а from має відрізнятися від to. Відповідь містить ідентифікатори номіналів, налаштовані display-валюти, вихідну суму, конвертовану суму, обмінний курс, timestamp, confidence, нульову комісію конвертації та метадані джерела.
{ "from": "RING", "to": "USD" } недійсний, навіть якщо це налаштовані символи клону. Надсилайте ідентифікатори номіналів, а не символи.
AuthenticatedAppShell викликає ensureFxFeedFresh(), потім getExchangeRates(). Якщо оновлення не вдається, оболонка залишає initialExchangeRates рівним null, а клієнтський код переходить до статичних курсів ring-config.
AppClientShell передає серіалізовані курси до StorePaymentMethodsProvider. Провайдер починає з цього SSR seed, потім після hydration викликає getLiveExchangeRates(), щоб конвертація в браузері залишалася узгодженою із серверним checkout.
StorePaymentMethodsProvider.displayMode — лише main_currency | native_token. PrebillingPage формує droplist із getSupportedCurrencies() або getSupportedCrypto(), зберігаючи фіатний paymentCurrency для card і PayPal. submitStoreCheckoutPayment перевіряє цей фіат щодо підтримуваного пулу presentment і перераховує суму на сервері.
Запустіть поставлений smoke smk46_ з ring-platform.org:
Smoke перевіряє реєстрацію pipeline, визначення й оновлення провайдера, round-trip сервісу native ↔ main, необов’язкові контракти conversion GET / POST, HTTP 400 для застарілих RING / USD і поведінку cron-відповіді.
RING/USDring-config.fx визначає провайдерів у такому порядку:
fx.byMainCurrency[store.mainCurrency]UAHfx.default для інших основних валютПоставлений за замовчуванням конфіг використовує NBU для UAH, а в інших випадках open_er_api. fx.manualOverrides має пріоритет над статичними курсами та live overlay.
Відкрийте /admin/web3/settings як superadmin, щоб оновити desk-курс native token, переглянути визначеного провайдера фіатного FX і час останнього отримання або примусово оновити FX. UI читає GET /api/admin/web3/settings і GET /api/admin/fx; запис відбувається відповідними POST-маршрутами.
Продакшен-планувальники викликають GET /api/cron/fx-feed-refresh. Встановіть CRON_SECRET і надішліть його як Bearer-токен. Маршрут записує запуск через ProcessConductor з ID pipeline fx-feed-refresh; застарілість потоку й надалі визначається налаштованим refreshHours.
Ліва навігаційна панель перемикається лише між main_currency (остання фіатна перевага покупця) і native_token. Droplist checkout дотримується цього режиму: фіат перелічує налаштовані SupportedCurrencies, native — налаштовані SupportedCrypto.
На кроці review рядки продуктів і підсумки конвертуються через convertPrice / displayPrice. Card і PayPal залишаються фіатними платежами: checkout передає фіатний paymentCurrency, а сервер повторно обчислює платіж із підсумку замовлення в основній валюті перед викликом PaymentConductor.
Crypto-сума в review checkout — це presentment, а не доказ того, що картковий шлюз стягне crypto. Платіжна рейка та paymentCurrency визначають settlement.
| Облік кредитів | lib/payments/credit-balance.ts | Хелпери обліку credit unit ↔ main |
| FX pipeline | lib/processes/fx/fx-feed-refresh.ts, lib/processes/registry.ts | Обробник, ID і cron-шлях ProcessConductor |
| API конвертації | app/api/prices/conversion/route.ts | Публічний контракт курсу й конвертації native ↔ main |
| SSR hydrate | app/layout.tsx | AuthenticatedAppShell прогріває й читає курси |
| Client provider | components/providers/app-client-shell.tsx | Передає initialExchangeRates у контекст валюти store |
| Контекст валюти store | features/store/currency-context.tsx | Режим display, конвертація, форматування, переваги |
| Presentment checkout | features/store/components/checkout/prebilling-page.tsx | Droplist fiat/crypto і фіатний paymentCurrency |
| Charge checkout | app/_actions/store-checkout-payment.ts | Серверний перерахунок фіату для card/PayPal |
Серверний код імпортує курси з фасаду, а не з модулів реалізації:
@/lib/ring-oracle імпортує server-only. Клієнтські компоненти отримують серіалізовані дані курсів через AuthenticatedAppShell, AppClientShell або безпечну для клієнта server action getLiveExchangeRates.
ID провайдерів: nbu, open_er_api і frankfurter. Жорстка перевірка замінює NBU на open_er_api, коли основна валюта не UAH.
Перевірка авторизації є умовною щодо CRON_SECRET, тому продакшен-розгортання мають його налаштувати. Відповідь містить runId ProcessConductor і метадані оновлення; вимкнений потік повертає успішний пропущений запуск. Курси зберігаються в platform_settings з id fx_feed (той самий гібридний шаблон JSONB, що й у desk oracle). Для погодинного оновлення кластера додайте k8s/cronjob-fx-feed-refresh.yaml.
GET /api/admin/fx повертає конфігурацію визначеного потоку, перевизначення, час отримання, зразок курсів і визначені курси для адміністраторів платформи. POST /api/admin/fx приймає { "force": true } і оновлює потік. Читання та запис desk-курсу залишаються на доступному лише superadmin маршруті /api/admin/web3/settings.
GET /api/prices/conversion повертає denominations: ["native_token", "main_currency"], обидві пари напрямків, курси та обернені курси, метадані джерела й ліміти від 0.000001 до 1000000.
amount має бути додатним десятковим рядком, а from має відрізнятися від to. Відповідь містить ідентифікатори номіналів, налаштовані display-валюти, вихідну суму, конвертовану суму, обмінний курс, timestamp, confidence, нульову комісію конвертації та метадані джерела.
{ "from": "RING", "to": "USD" } недійсний, навіть якщо це налаштовані символи клону. Надсилайте ідентифікатори номіналів, а не символи.
AuthenticatedAppShell викликає ensureFxFeedFresh(), потім getExchangeRates(). Якщо оновлення не вдається, оболонка залишає initialExchangeRates рівним null, а клієнтський код переходить до статичних курсів ring-config.
AppClientShell передає серіалізовані курси до StorePaymentMethodsProvider. Провайдер починає з цього SSR seed, потім після hydration викликає getLiveExchangeRates(), щоб конвертація в браузері залишалася узгодженою із серверним checkout.
StorePaymentMethodsProvider.displayMode — лише main_currency | native_token. PrebillingPage формує droplist із getSupportedCurrencies() або getSupportedCrypto(), зберігаючи фіатний paymentCurrency для card і PayPal. submitStoreCheckoutPayment перевіряє цей фіат щодо підтримуваного пулу presentment і перераховує суму на сервері.
Запустіть поставлений smoke smk46_ з ring-platform.org:
Smoke перевіряє реєстрацію pipeline, визначення й оновлення провайдера, round-trip сервісу native ↔ main, необов’язкові контракти conversion GET / POST, HTTP 400 для застарілих RING / USD і поведінку cron-відповіді.