ВозможностиОрганизации
Документация
    Ring Platform

    Децентрализованное самостроящееся будущее

    Войти
    Организации
    Возможности
    Магазин
    Документация
    Концепции платформы
    RING ЭкономикаSonoratek LLCГлобальное влияниеAI встречает Web3
    Начать
    Быстрый стартКалькуляторДорожная карта
    Конфиденциальность|Контакты
    v1.106.29|Sonoratek LLC

    Documentation

    Концепции, ценность и типичные сценарии клонирования — меньше кода.

    Добро пожаловать в Ring
    Краткий справочник
    С чего начать
    Предварительные требования
    Установка
    Первый успех
    Следующие шаги
    Функции
    Store
    Склад и остатки
    Управление вендорами
    Комиссии и расчёты
    Членство и кредиты
    SubscriptionConductor
    PaymentConductor
    Ring Oracle
    Интеграция платежей
    Интеграция WayForPay
    Web3 Кошелек
    WalletConductor
    Реферальные коды (Refcodes)
    Шторка страницы
    NFT Exhibition Marketplace
    Система Стейкинга Токенов
    Организации
    Возможности
    AI Matcher
    Messaging
    Peer Games
    News
    Блоги участников
    Система Резервирования Имён Пользователей
    Научный редактор
    Уведомления
    Push-уведомления через FCM (Ring)
    Email AI-CRM
    Ring Mailer и RingdomX Mail
    Протокол Tunnel
    Authentication
    Безопасность и соответствие
    Система локалей
    Мобильный Опыт
    Паттерны Оптимизации Производительности
    Примеры
    Quick Start
    Базовая настройка
    White Label
    Custom Branding
    Интеграция Web3
    Реальные Проекты
    Advanced Features
    Кастомизация
    Быстрый старт — ваш первый клон Ring
    Руководство по кастомизации
    Vertical Presets (SSOT)
    Руководство по Ringization
    Branding
    Темы оформления
    Features
    Localization
    Настройка токеномики
    Интеграция платёжного шлюза
    Референсные деплои Ring
    Конфигурация проекта
    Публичные переменные окружения
    Секреты Order Lab
    Project ID WalletConnect (Reown Cloud)
    Поддерживаемые сервисы
    Вики NODUS (знания проекта)
    Плейбук конфигурации
    Web3
    Token launch jurisdictions
    Кошелёк
    Советы по безопасности кошелька
    Интеграции
    Ethereum-кошельки (Wagmi v3)
    Развёртывание
    Развёртывание на собственном сервере
    Vercel
    Docker
    Конфигурация Окружения
    Мониторинг и аналитика
    Оптимизация производительности
    Резервное копирование и восстановление
    Архитектура
    Data Model
    Security
    Real Time
    Discovery Mutation Sync
    Архитектура PaymentConductor
    Wallet Conductor
    Архитектура News Kingdom
    Бекенд Сервисы
    Интеграция Firebase
    Разработка
    Ring MCP Server
    OSS и enterprise

    Быстрый вход (CTO · аудиторы · агенты)

    Приветствие — миссия и аудитории
    Краткий справочник
    С чего начать
    Архитектура и Auth.js
    Режимы бэкенда и базы данных (DB_BACKEND_MODE)
    Self-hosted
    Ring MCP Tools
    Ring MCP Server
    Token economics
    Token launch jurisdictions
    Деплой (Docker · k8s)
    Безопасность и соответствие требованиям
    ringdom.org — база LegioX
    Исходный код — лицензия MIT (GitHub)

    Documentation

    Концепции, ценность и типичные сценарии клонирования — меньше кода.

    Добро пожаловать в Ring
    Краткий справочник
    С чего начать
    Предварительные требования
    Установка
    Первый успех
    Следующие шаги
    Функции
    Store
    Склад и остатки
    Управление вендорами
    Комиссии и расчёты
    Членство и кредиты
    SubscriptionConductor
    PaymentConductor
    Ring Oracle
    Интеграция платежей
    Интеграция WayForPay
    Web3 Кошелек
    WalletConductor
    Реферальные коды (Refcodes)
    Шторка страницы
    NFT Exhibition Marketplace
    Система Стейкинга Токенов
    Организации
    Возможности
    AI Matcher
    Messaging
    Peer Games
    News
    Блоги участников
    Система Резервирования Имён Пользователей
    Научный редактор
    Уведомления
    Push-уведомления через FCM (Ring)
    Email AI-CRM
    Ring Mailer и RingdomX Mail
    Протокол Tunnel
    Authentication
    Безопасность и соответствие
    Система локалей
    Мобильный Опыт
    Паттерны Оптимизации Производительности
    Примеры
    Quick Start
    Базовая настройка
    White Label
    Custom Branding
    Интеграция Web3
    Реальные Проекты
    Advanced Features
    Кастомизация
    Быстрый старт — ваш первый клон Ring
    Руководство по кастомизации
    Vertical Presets (SSOT)
    Руководство по Ringization
    Branding
    Темы оформления
    Features
    Localization
    Настройка токеномики
    Интеграция платёжного шлюза
    Референсные деплои Ring
    Конфигурация проекта
    Публичные переменные окружения
    Секреты Order Lab
    Project ID WalletConnect (Reown Cloud)
    Поддерживаемые сервисы
    Вики NODUS (знания проекта)
    Плейбук конфигурации
    Web3
    Token launch jurisdictions
    Кошелёк
    Советы по безопасности кошелька
    Интеграции
    Ethereum-кошельки (Wagmi v3)
    Развёртывание
    Развёртывание на собственном сервере
    Vercel
    Docker
    Конфигурация Окружения
    Мониторинг и аналитика
    Оптимизация производительности
    Резервное копирование и восстановление
    Архитектура
    Data Model
    Security
    Real Time
    Discovery Mutation Sync
    Архитектура PaymentConductor
    Wallet Conductor
    Архитектура News Kingdom
    Бекенд Сервисы
    Интеграция Firebase
    Разработка
    Ring MCP Server
    OSS и enterprise

    Быстрый вход (CTO · аудиторы · агенты)

    Приветствие — миссия и аудитории
    Краткий справочник
    С чего начать
    Архитектура и Auth.js
    Режимы бэкенда и базы данных (DB_BACKEND_MODE)
    Self-hosted
    Ring MCP Tools
    Ring MCP Server
    Token economics
    Token launch jurisdictions
    Деплой (Docker · k8s)
    Безопасность и соответствие требованиям
    ringdom.org — база LegioX
    Исходный код — лицензия MIT (GitHub)

    Documentation

    Концепции, ценность и типичные сценарии клонирования — меньше кода.

    Добро пожаловать в Ring
    Краткий справочник
    С чего начать
    Предварительные требования
    Установка
    Первый успех
    Следующие шаги
    Функции
    Store
    Склад и остатки
    Управление вендорами
    Комиссии и расчёты
    Членство и кредиты
    SubscriptionConductor
    PaymentConductor
    Ring Oracle
    Интеграция платежей
    Интеграция WayForPay
    Web3 Кошелек
    WalletConductor
    Реферальные коды (Refcodes)
    Шторка страницы
    NFT Exhibition Marketplace
    Система Стейкинга Токенов
    Организации
    Возможности
    AI Matcher
    Messaging
    Peer Games
    News
    Блоги участников
    Система Резервирования Имён Пользователей
    Научный редактор
    Уведомления
    Push-уведомления через FCM (Ring)
    Email AI-CRM
    Ring Mailer и RingdomX Mail
    Протокол Tunnel
    Authentication
    Безопасность и соответствие
    Система локалей
    Мобильный Опыт
    Паттерны Оптимизации Производительности
    Примеры
    Quick Start
    Базовая настройка
    White Label
    Custom Branding
    Интеграция Web3
    Реальные Проекты
    Advanced Features
    Кастомизация
    Быстрый старт — ваш первый клон Ring
    Руководство по кастомизации
    Vertical Presets (SSOT)
    Руководство по Ringization
    Branding
    Темы оформления
    Features
    Localization
    Настройка токеномики
    Интеграция платёжного шлюза
    Референсные деплои Ring
    Конфигурация проекта
    Публичные переменные окружения
    Секреты Order Lab
    Project ID WalletConnect (Reown Cloud)
    Поддерживаемые сервисы
    Вики NODUS (знания проекта)
    Плейбук конфигурации
    Web3
    Token launch jurisdictions
    Кошелёк
    Советы по безопасности кошелька
    Интеграции
    Ethereum-кошельки (Wagmi v3)
    Развёртывание
    Развёртывание на собственном сервере
    Vercel
    Docker
    Конфигурация Окружения
    Мониторинг и аналитика
    Оптимизация производительности
    Резервное копирование и восстановление
    Архитектура
    Data Model
    Security
    Real Time
    Discovery Mutation Sync
    Архитектура PaymentConductor
    Wallet Conductor
    Архитектура News Kingdom
    Бекенд Сервисы
    Интеграция Firebase
    Разработка
    Ring MCP Server
    OSS и enterprise

    Быстрый вход (CTO · аудиторы · агенты)

    Приветствие — миссия и аудитории
    Краткий справочник
    С чего начать
    Архитектура и Auth.js
    Режимы бэкенда и базы данных (DB_BACKEND_MODE)
    Self-hosted
    Ring MCP Tools
    Ring MCP Server
    Token economics
    Token launch jurisdictions
    Деплой (Docker · k8s)
    Безопасность и соответствие требованиям
    ringdom.org — база LegioX
    Исходный код — лицензия MIT (GitHub)
    Ring Logo

    Loading documentation...

    Preparing Ring content

    Ring Logo

    Loading documentation...

    Preparing Ring content

    Ring Logo

    Loading documentation...

    Preparing Ring content

    Ring Oracle

    Ring Oracle — server-only фасад курсов в @/lib/ring-oracle. Он даёт коду платежей, кошелька, membership, public pools и магазина единый словарь стоимости проекта вместо жёстко прописанных символов токенов или fiat.

    Используйте Основатель / Разработчик в боковой панели документации для фильтрации этой страницы. Основатели видят путь оператора и поведение checkout; разработчики видят проверенные модули, маршруты, payloads и smoke-команды.

    Три деноминации, без алиасов символов

    ДеноминацияЗначениеНастроенная идентичность
    credit_balanceЕдиница ledger, принадлежащая проектуcredit.creditBalanceUnitLabel и credit.creditBalanceUnitToMainCurrency
    native_tokenНативный токен клонаtokens.nativeToken.symbol
    main_currencyFiat расчётов проектаstore.mainCurrency

    ValueDenomination содержит ровно эти три значения. Символы валют, такие как RING, USD или UAH, это значения отображения/конфига, а не ID деноминаций.

    API конвертации намеренно уже

    GET и POST /api/prices/conversion принимают только native_token и main_currency. credit_balance использует поверхность учёта кредитов, а устаревшие алиасы запроса RING / USD возвращают HTTP 400.

    Почему это важно для вашего клона

    Единый денежный язык

    Кошелёк, checkout, membership и финансирование сообщества определяют стоимость проекта через одну модель деноминаций.

    Операционный FX-фид

    ProcessConductor обновляет fiat-курсы презентации, а ручные переопределения остаются доступны в конфиге клона.

    Честный checkout

    Магазин разделяет то, что видит покупатель, и fiat-валюту, которую списывает карточный шлюз или PayPal.

    Путь оператора

    1. Выберите денежные идентичности клона

    Задайте в ring-config.json основную валюту проекта, поддерживаемые fiat-валюты презентации, поддерживаемые крипто-символы, нативный токен и курс учёта кредитов. Ring Oracle читает эти идентичности проекта; продуктовому коду не нужен особый случай .

    Архитектура

    ПоверхностьПроверенный путьОтветственность
    Фасадlib/ring-oracle/index.tsServer-only поверхность экспорта для каждого семейства курсов
    Деноминацииlib/value-denomination.tsТочная триада ValueDenomination и валидация
    Desk oraclefeatures/wallet/services/native-token-oracle.tsКурс native ↔ main, подписанные котировки, журнал аудита
    Мост Chainlinkfeatures/wallet/services/native-token-chainlink-oracle.tsФиды внешних EVM-токенов из allowlist
    Fiat FXlib/fx/fx-feed-service.ts, lib/fx/fx-rates-overlay.tsВыбор провайдера, постоянный кеш, live overlay

    Связанная документация

    Related documentation

    PaymentConductor

    Зависимость: PaymentConductor использует курсы Oracle, когда rail пересекает деноминации.

    Multi-Vendor Store

    Тот же процесс: отображение каталога, презентация в checkout и создание списания на сервере.

    Wallet & Credit System

    Подробно: котировки Token Desk, учёт кредитов и балансы нативного токена.

    Credit Rewards

    См. также: награды за активность фиксируют getMainCurrencyCreditAccountingRate; аварийный выключатель credit.rewards.enabled.

    1. Документация
    2. /Функции
    3. /Ring Oracle

    Обновлено 9 сент. 2026 г.6 мин прослушивания

    Ring Oracle

    Ring Oracle — server-only фасад курсов в @/lib/ring-oracle. Он даёт коду платежей, кошелька, membership, public pools и магазина единый словарь стоимости проекта вместо жёстко прописанных символов токенов или fiat.

    Используйте Основатель / Разработчик в боковой панели документации для фильтрации этой страницы. Основатели видят путь оператора и поведение checkout; разработчики видят проверенные модули, маршруты, payloads и smoke-команды.

    Три деноминации, без алиасов символов

    ДеноминацияЗначениеНастроенная идентичность
    credit_balanceЕдиница ledger, принадлежащая проектуcredit.creditBalanceUnitLabel и credit.creditBalanceUnitToMainCurrency
    native_tokenНативный токен клонаtokens.nativeToken.symbol
    main_currencyFiat расчётов проектаstore.mainCurrency

    ValueDenomination содержит ровно эти три значения. Символы валют, такие как RING, USD или UAH, это значения отображения/конфига, а не ID деноминаций.

    API конвертации намеренно уже

    GET и POST /api/prices/conversion принимают только native_token и main_currency. credit_balance использует поверхность учёта кредитов, а устаревшие алиасы запроса RING / USD возвращают HTTP 400.

    Почему это важно для вашего клона

    Единый денежный язык

    Кошелёк, checkout, membership и финансирование сообщества определяют стоимость проекта через одну модель деноминаций.

    Операционный FX-фид

    ProcessConductor обновляет fiat-курсы презентации, а ручные переопределения остаются доступны в конфиге клона.

    Честный checkout

    Магазин разделяет то, что видит покупатель, и fiat-валюту, которую списывает карточный шлюз или PayPal.

    Путь оператора

    1. Выберите денежные идентичности клона

    Задайте в ring-config.json основную валюту проекта, поддерживаемые fiat-валюты презентации, поддерживаемые крипто-символы, нативный токен и курс учёта кредитов. Ring Oracle читает эти идентичности проекта; продуктовому коду не нужен особый случай .

    Архитектура

    ПоверхностьПроверенный путьОтветственность
    Фасадlib/ring-oracle/index.tsServer-only поверхность экспорта для каждого семейства курсов
    Деноминацииlib/value-denomination.tsТочная триада ValueDenomination и валидация
    Desk oraclefeatures/wallet/services/native-token-oracle.tsКурс native ↔ main, подписанные котировки, журнал аудита
    Мост Chainlinkfeatures/wallet/services/native-token-chainlink-oracle.tsФиды внешних EVM-токенов из allowlist
    Fiat FXlib/fx/fx-feed-service.ts, lib/fx/fx-rates-overlay.tsВыбор провайдера, постоянный кеш, live overlay

    Связанная документация

    Related documentation

    PaymentConductor

    Зависимость: PaymentConductor использует курсы Oracle, когда rail пересекает деноминации.

    Multi-Vendor Store

    Тот же процесс: отображение каталога, презентация в checkout и создание списания на сервере.

    Wallet & Credit System

    Подробно: котировки Token Desk, учёт кредитов и балансы нативного токена.

    Credit Rewards

    См. также: награды за активность фиксируют getMainCurrencyCreditAccountingRate; аварийный выключатель credit.rewards.enabled.

    1. Документация
    2. /Функции
    3. /Ring Oracle

    Обновлено 9 сент. 2026 г.6 мин прослушивания

    Ring Oracle

    Ring Oracle — server-only фасад курсов в @/lib/ring-oracle. Он даёт коду платежей, кошелька, membership, public pools и магазина единый словарь стоимости проекта вместо жёстко прописанных символов токенов или fiat.

    Используйте Основатель / Разработчик в боковой панели документации для фильтрации этой страницы. Основатели видят путь оператора и поведение checkout; разработчики видят проверенные модули, маршруты, payloads и smoke-команды.

    Три деноминации, без алиасов символов

    ДеноминацияЗначениеНастроенная идентичность
    credit_balanceЕдиница ledger, принадлежащая проектуcredit.creditBalanceUnitLabel и credit.creditBalanceUnitToMainCurrency
    native_tokenНативный токен клонаtokens.nativeToken.symbol
    main_currencyFiat расчётов проектаstore.mainCurrency

    ValueDenomination содержит ровно эти три значения. Символы валют, такие как RING, USD или UAH, это значения отображения/конфига, а не ID деноминаций.

    API конвертации намеренно уже

    GET и POST /api/prices/conversion принимают только native_token и main_currency. credit_balance использует поверхность учёта кредитов, а устаревшие алиасы запроса RING / USD возвращают HTTP 400.

    Почему это важно для вашего клона

    Единый денежный язык

    Кошелёк, checkout, membership и финансирование сообщества определяют стоимость проекта через одну модель деноминаций.

    Операционный FX-фид

    ProcessConductor обновляет fiat-курсы презентации, а ручные переопределения остаются доступны в конфиге клона.

    Честный checkout

    Магазин разделяет то, что видит покупатель, и fiat-валюту, которую списывает карточный шлюз или PayPal.

    Путь оператора

    1. Выберите денежные идентичности клона

    Задайте в ring-config.json основную валюту проекта, поддерживаемые fiat-валюты презентации, поддерживаемые крипто-символы, нативный токен и курс учёта кредитов. Ring Oracle читает эти идентичности проекта; продуктовому коду не нужен особый случай .

    Архитектура

    ПоверхностьПроверенный путьОтветственность
    Фасадlib/ring-oracle/index.tsServer-only поверхность экспорта для каждого семейства курсов
    Деноминацииlib/value-denomination.tsТочная триада ValueDenomination и валидация
    Desk oraclefeatures/wallet/services/native-token-oracle.tsКурс native ↔ main, подписанные котировки, журнал аудита
    Мост Chainlinkfeatures/wallet/services/native-token-chainlink-oracle.tsФиды внешних EVM-токенов из allowlist
    Fiat FXlib/fx/fx-feed-service.ts, lib/fx/fx-rates-overlay.tsВыбор провайдера, постоянный кеш, live overlay

    Связанная документация

    Related documentation

    PaymentConductor

    Зависимость: PaymentConductor использует курсы Oracle, когда rail пересекает деноминации.

    Multi-Vendor Store

    Тот же процесс: отображение каталога, презентация в checkout и создание списания на сервере.

    Wallet & Credit System

    Подробно: котировки Token Desk, учёт кредитов и балансы нативного токена.

    Credit Rewards

    См. также: награды за активность фиксируют getMainCurrencyCreditAccountingRate; аварийный выключатель credit.rewards.enabled.

    1. Документация
    2. /Функции
    3. /Ring Oracle

    Обновлено 9 сент. 2026 г.6 мин прослушивания

    RING/USD

    2. Выберите FX-фид

    ring-config.fx определяет провайдеров в таком порядке:

    1. fx.byMainCurrency[store.mainCurrency]
    2. NBU, когда основная валюта UAH
    3. fx.default для остальных основных валют

    Поставляемый default использует NBU для UAH и open_er_api в остальных случаях. fx.manualOverrides имеет приоритет и над статическими курсами, и над live overlay.

    3. Управляйте курсами desk и FX

    Откройте /admin/web3/settings как superadmin, чтобы обновить курс desk нативного токена, посмотреть определённого fiat FX-провайдера и время последней загрузки или принудительно обновить FX. UI читает GET /api/admin/web3/settings и GET /api/admin/fx; запись идёт через соответствующие POST-маршруты.

    4. Запланируйте маршрут фида

    Production-планировщики вызывают GET /api/cron/fx-feed-refresh. Задайте CRON_SECRET и передавайте его как Bearer token. Маршрут записывает запуск через ProcessConductor под pipeline ID fx-feed-refresh; устаревание фида по-прежнему следует настроенному refreshHours.

    5. Поймите презентацию для покупателя

    Левая навигационная панель переключает только между main_currency (последний fiat-выбор покупателя) и native_token. Выпадающий список checkout следует этому режиму: fiat показывает настроенные SupportedCurrencies; native показывает настроенные SupportedCrypto.

    Шаг проверки конвертирует строки товаров и итоги через convertPrice / displayPrice. Карта и PayPal остаются fiat-списаниями: checkout передаёт fiat paymentCurrency, а сервер пересчитывает сумму списания из итога заказа в основной валюте перед вызовом PaymentConductor.

    Крипто-сумма на шаге проверки checkout это презентация, а не доказательство того, что карточный шлюз спишет крипту. Расчёт определяют платёжный rail и paymentCurrency.

    Учёт кредитовlib/payments/credit-balance.tsХелперы единица кредита ↔ main
    FX pipelinelib/processes/fx/fx-feed-refresh.ts, lib/processes/registry.tsОбработчик ProcessConductor, ID и путь cron
    API конвертацииapp/api/prices/conversion/route.tsПубличный контракт курса и конвертации native ↔ main
    SSR hydrateapp/layout.tsxAuthenticatedAppShell прогревает и читает курсы
    Client providercomponents/providers/app-client-shell.tsxПередаёт initialExchangeRates в контекст валюты магазина
    Контекст валюты магазинаfeatures/store/currency-context.tsxРежим отображения, конвертация, форматирование, предпочтения
    Презентация checkoutfeatures/store/components/checkout/prebilling-page.tsxВыпадающий список fiat/crypto и fiat paymentCurrency
    Списание checkoutapp/_actions/store-checkout-payment.tsСерверный пересчёт fiat для карты/PayPal

    Правило фасада

    Серверный код импортирует курсы из фасада, а не из модулей реализации:

    @/lib/ring-oracle импортирует server-only. Клиентские компоненты получают сериализуемые данные курсов через AuthenticatedAppShell, AppClientShell или client-safe server action getLiveExchangeRates.

    Поток обновления FX

    1. 1

      Настройте выбор провайдера

      ID провайдеров: nbu, open_er_api и frankfurter. Жёсткий guard заменяет NBU на open_er_api, если основная валюта не UAH.

    2. 2

      Защитите и вызовите cron-маршрут

      Проверка авторизации зависит от наличия CRON_SECRET, поэтому production-деплои обязаны его настроить. Ответ включает runId ProcessConductor и метаданные обновления; отключённый фид сообщает об успешном пропущенном запуске. Курсы сохраняются в platform_settings с id fx_feed (тот же гибридный JSONB-паттерн, что и у desk oracle). Поставляйте k8s/cronjob-fx-feed-refresh.yaml для ежечасного обновления в кластере.

    3. 3

      Просмотр или принудительное обновление админом

      GET /api/admin/fx возвращает для platform admins определённую конфигурацию фида, переопределения, время загрузки, выборку курсов и определённые курсы. POST /api/admin/fx принимает { "force": true } и обновляет фид. Чтение и запись курса desk остаются на маршруте /api/admin/web3/settings только для superadmin.

    Контракт API конвертации

    Чтение поддерживаемых пар

    GET /api/prices/conversion возвращает denominations: ["native_token", "main_currency"], обе пары направлений, курсы и обратные курсы, метаданные источника и лимиты от 0.000001 до 1000000.

    Конвертация суммы

    amount должен быть положительной десятичной строкой, а from должен отличаться от to. Ответ включает ID деноминаций, настроенные валюты отображения, исходную сумму, сконвертированную сумму, курс, timestamp, confidence, нулевую комиссию конвертации и метаданные источника.

    Без алиасов обратной совместимости

    { "from": "RING", "to": "USD" } недопустимо, даже если это настроенные символы клона. Отправляйте ID деноминаций, а не символы.

    Границы SSR и checkout

    1. 1

      Гидрация курсов на сервере

      AuthenticatedAppShell вызывает ensureFxFeedFresh(), затем getExchangeRates(). Если обновление не удалось, shell оставляет initialExchangeRates равным null, и клиентский код откатывается к статическим курсам ring-config.

    2. 2

      Seed и обновление client provider

      AppClientShell передаёт сериализуемые курсы в StorePaymentMethodsProvider. Провайдер стартует с этого SSR seed, затем после гидрации вызывает getLiveExchangeRates(), чтобы конвертация в браузере совпадала с серверным checkout.

    3. 3

      Разделяйте валюты отображения и списания

      StorePaymentMethodsProvider.displayMode принимает только main_currency | native_token. PrebillingPage строит выпадающий список из getSupportedCurrencies() или getSupportedCrypto(), сохраняя fiat paymentCurrency для карты и PayPal. submitStoreCheckoutPayment проверяет этот fiat по поддерживаемому пулу презентации и пересчитывает сумму на сервере.

    Smoke-проверка

    Запустите поставляемый smoke smk46_ из ring-platform.org:

    Smoke проверяет регистрацию pipeline, выбор и обновление провайдера, round-trip сервиса native ↔ main, опциональные контракты GET / POST конвертации, HTTP 400 для устаревших RING / USD и поведение ответа cron.

    RING/USD

    2. Выберите FX-фид

    ring-config.fx определяет провайдеров в таком порядке:

    1. fx.byMainCurrency[store.mainCurrency]
    2. NBU, когда основная валюта UAH
    3. fx.default для остальных основных валют

    Поставляемый default использует NBU для UAH и open_er_api в остальных случаях. fx.manualOverrides имеет приоритет и над статическими курсами, и над live overlay.

    3. Управляйте курсами desk и FX

    Откройте /admin/web3/settings как superadmin, чтобы обновить курс desk нативного токена, посмотреть определённого fiat FX-провайдера и время последней загрузки или принудительно обновить FX. UI читает GET /api/admin/web3/settings и GET /api/admin/fx; запись идёт через соответствующие POST-маршруты.

    4. Запланируйте маршрут фида

    Production-планировщики вызывают GET /api/cron/fx-feed-refresh. Задайте CRON_SECRET и передавайте его как Bearer token. Маршрут записывает запуск через ProcessConductor под pipeline ID fx-feed-refresh; устаревание фида по-прежнему следует настроенному refreshHours.

    5. Поймите презентацию для покупателя

    Левая навигационная панель переключает только между main_currency (последний fiat-выбор покупателя) и native_token. Выпадающий список checkout следует этому режиму: fiat показывает настроенные SupportedCurrencies; native показывает настроенные SupportedCrypto.

    Шаг проверки конвертирует строки товаров и итоги через convertPrice / displayPrice. Карта и PayPal остаются fiat-списаниями: checkout передаёт fiat paymentCurrency, а сервер пересчитывает сумму списания из итога заказа в основной валюте перед вызовом PaymentConductor.

    Крипто-сумма на шаге проверки checkout это презентация, а не доказательство того, что карточный шлюз спишет крипту. Расчёт определяют платёжный rail и paymentCurrency.

    Учёт кредитовlib/payments/credit-balance.tsХелперы единица кредита ↔ main
    FX pipelinelib/processes/fx/fx-feed-refresh.ts, lib/processes/registry.tsОбработчик ProcessConductor, ID и путь cron
    API конвертацииapp/api/prices/conversion/route.tsПубличный контракт курса и конвертации native ↔ main
    SSR hydrateapp/layout.tsxAuthenticatedAppShell прогревает и читает курсы
    Client providercomponents/providers/app-client-shell.tsxПередаёт initialExchangeRates в контекст валюты магазина
    Контекст валюты магазинаfeatures/store/currency-context.tsxРежим отображения, конвертация, форматирование, предпочтения
    Презентация checkoutfeatures/store/components/checkout/prebilling-page.tsxВыпадающий список fiat/crypto и fiat paymentCurrency
    Списание checkoutapp/_actions/store-checkout-payment.tsСерверный пересчёт fiat для карты/PayPal

    Правило фасада

    Серверный код импортирует курсы из фасада, а не из модулей реализации:

    @/lib/ring-oracle импортирует server-only. Клиентские компоненты получают сериализуемые данные курсов через AuthenticatedAppShell, AppClientShell или client-safe server action getLiveExchangeRates.

    Поток обновления FX

    1. 1

      Настройте выбор провайдера

      ID провайдеров: nbu, open_er_api и frankfurter. Жёсткий guard заменяет NBU на open_er_api, если основная валюта не UAH.

    2. 2

      Защитите и вызовите cron-маршрут

      Проверка авторизации зависит от наличия CRON_SECRET, поэтому production-деплои обязаны его настроить. Ответ включает runId ProcessConductor и метаданные обновления; отключённый фид сообщает об успешном пропущенном запуске. Курсы сохраняются в platform_settings с id fx_feed (тот же гибридный JSONB-паттерн, что и у desk oracle). Поставляйте k8s/cronjob-fx-feed-refresh.yaml для ежечасного обновления в кластере.

    3. 3

      Просмотр или принудительное обновление админом

      GET /api/admin/fx возвращает для platform admins определённую конфигурацию фида, переопределения, время загрузки, выборку курсов и определённые курсы. POST /api/admin/fx принимает { "force": true } и обновляет фид. Чтение и запись курса desk остаются на маршруте /api/admin/web3/settings только для superadmin.

    Контракт API конвертации

    Чтение поддерживаемых пар

    GET /api/prices/conversion возвращает denominations: ["native_token", "main_currency"], обе пары направлений, курсы и обратные курсы, метаданные источника и лимиты от 0.000001 до 1000000.

    Конвертация суммы

    amount должен быть положительной десятичной строкой, а from должен отличаться от to. Ответ включает ID деноминаций, настроенные валюты отображения, исходную сумму, сконвертированную сумму, курс, timestamp, confidence, нулевую комиссию конвертации и метаданные источника.

    Без алиасов обратной совместимости

    { "from": "RING", "to": "USD" } недопустимо, даже если это настроенные символы клона. Отправляйте ID деноминаций, а не символы.

    Границы SSR и checkout

    1. 1

      Гидрация курсов на сервере

      AuthenticatedAppShell вызывает ensureFxFeedFresh(), затем getExchangeRates(). Если обновление не удалось, shell оставляет initialExchangeRates равным null, и клиентский код откатывается к статическим курсам ring-config.

    2. 2

      Seed и обновление client provider

      AppClientShell передаёт сериализуемые курсы в StorePaymentMethodsProvider. Провайдер стартует с этого SSR seed, затем после гидрации вызывает getLiveExchangeRates(), чтобы конвертация в браузере совпадала с серверным checkout.

    3. 3

      Разделяйте валюты отображения и списания

      StorePaymentMethodsProvider.displayMode принимает только main_currency | native_token. PrebillingPage строит выпадающий список из getSupportedCurrencies() или getSupportedCrypto(), сохраняя fiat paymentCurrency для карты и PayPal. submitStoreCheckoutPayment проверяет этот fiat по поддерживаемому пулу презентации и пересчитывает сумму на сервере.

    Smoke-проверка

    Запустите поставляемый smoke smk46_ из ring-platform.org:

    Smoke проверяет регистрацию pipeline, выбор и обновление провайдера, round-trip сервиса native ↔ main, опциональные контракты GET / POST конвертации, HTTP 400 для устаревших RING / USD и поведение ответа cron.

    RING/USD

    2. Выберите FX-фид

    ring-config.fx определяет провайдеров в таком порядке:

    1. fx.byMainCurrency[store.mainCurrency]
    2. NBU, когда основная валюта UAH
    3. fx.default для остальных основных валют

    Поставляемый default использует NBU для UAH и open_er_api в остальных случаях. fx.manualOverrides имеет приоритет и над статическими курсами, и над live overlay.

    3. Управляйте курсами desk и FX

    Откройте /admin/web3/settings как superadmin, чтобы обновить курс desk нативного токена, посмотреть определённого fiat FX-провайдера и время последней загрузки или принудительно обновить FX. UI читает GET /api/admin/web3/settings и GET /api/admin/fx; запись идёт через соответствующие POST-маршруты.

    4. Запланируйте маршрут фида

    Production-планировщики вызывают GET /api/cron/fx-feed-refresh. Задайте CRON_SECRET и передавайте его как Bearer token. Маршрут записывает запуск через ProcessConductor под pipeline ID fx-feed-refresh; устаревание фида по-прежнему следует настроенному refreshHours.

    5. Поймите презентацию для покупателя

    Левая навигационная панель переключает только между main_currency (последний fiat-выбор покупателя) и native_token. Выпадающий список checkout следует этому режиму: fiat показывает настроенные SupportedCurrencies; native показывает настроенные SupportedCrypto.

    Шаг проверки конвертирует строки товаров и итоги через convertPrice / displayPrice. Карта и PayPal остаются fiat-списаниями: checkout передаёт fiat paymentCurrency, а сервер пересчитывает сумму списания из итога заказа в основной валюте перед вызовом PaymentConductor.

    Крипто-сумма на шаге проверки checkout это презентация, а не доказательство того, что карточный шлюз спишет крипту. Расчёт определяют платёжный rail и paymentCurrency.

    Учёт кредитовlib/payments/credit-balance.tsХелперы единица кредита ↔ main
    FX pipelinelib/processes/fx/fx-feed-refresh.ts, lib/processes/registry.tsОбработчик ProcessConductor, ID и путь cron
    API конвертацииapp/api/prices/conversion/route.tsПубличный контракт курса и конвертации native ↔ main
    SSR hydrateapp/layout.tsxAuthenticatedAppShell прогревает и читает курсы
    Client providercomponents/providers/app-client-shell.tsxПередаёт initialExchangeRates в контекст валюты магазина
    Контекст валюты магазинаfeatures/store/currency-context.tsxРежим отображения, конвертация, форматирование, предпочтения
    Презентация checkoutfeatures/store/components/checkout/prebilling-page.tsxВыпадающий список fiat/crypto и fiat paymentCurrency
    Списание checkoutapp/_actions/store-checkout-payment.tsСерверный пересчёт fiat для карты/PayPal

    Правило фасада

    Серверный код импортирует курсы из фасада, а не из модулей реализации:

    @/lib/ring-oracle импортирует server-only. Клиентские компоненты получают сериализуемые данные курсов через AuthenticatedAppShell, AppClientShell или client-safe server action getLiveExchangeRates.

    Поток обновления FX

    1. 1

      Настройте выбор провайдера

      ID провайдеров: nbu, open_er_api и frankfurter. Жёсткий guard заменяет NBU на open_er_api, если основная валюта не UAH.

    2. 2

      Защитите и вызовите cron-маршрут

      Проверка авторизации зависит от наличия CRON_SECRET, поэтому production-деплои обязаны его настроить. Ответ включает runId ProcessConductor и метаданные обновления; отключённый фид сообщает об успешном пропущенном запуске. Курсы сохраняются в platform_settings с id fx_feed (тот же гибридный JSONB-паттерн, что и у desk oracle). Поставляйте k8s/cronjob-fx-feed-refresh.yaml для ежечасного обновления в кластере.

    3. 3

      Просмотр или принудительное обновление админом

      GET /api/admin/fx возвращает для platform admins определённую конфигурацию фида, переопределения, время загрузки, выборку курсов и определённые курсы. POST /api/admin/fx принимает { "force": true } и обновляет фид. Чтение и запись курса desk остаются на маршруте /api/admin/web3/settings только для superadmin.

    Контракт API конвертации

    Чтение поддерживаемых пар

    GET /api/prices/conversion возвращает denominations: ["native_token", "main_currency"], обе пары направлений, курсы и обратные курсы, метаданные источника и лимиты от 0.000001 до 1000000.

    Конвертация суммы

    amount должен быть положительной десятичной строкой, а from должен отличаться от to. Ответ включает ID деноминаций, настроенные валюты отображения, исходную сумму, сконвертированную сумму, курс, timestamp, confidence, нулевую комиссию конвертации и метаданные источника.

    Без алиасов обратной совместимости

    { "from": "RING", "to": "USD" } недопустимо, даже если это настроенные символы клона. Отправляйте ID деноминаций, а не символы.

    Границы SSR и checkout

    1. 1

      Гидрация курсов на сервере

      AuthenticatedAppShell вызывает ensureFxFeedFresh(), затем getExchangeRates(). Если обновление не удалось, shell оставляет initialExchangeRates равным null, и клиентский код откатывается к статическим курсам ring-config.

    2. 2

      Seed и обновление client provider

      AppClientShell передаёт сериализуемые курсы в StorePaymentMethodsProvider. Провайдер стартует с этого SSR seed, затем после гидрации вызывает getLiveExchangeRates(), чтобы конвертация в браузере совпадала с серверным checkout.

    3. 3

      Разделяйте валюты отображения и списания

      StorePaymentMethodsProvider.displayMode принимает только main_currency | native_token. PrebillingPage строит выпадающий список из getSupportedCurrencies() или getSupportedCrypto(), сохраняя fiat paymentCurrency для карты и PayPal. submitStoreCheckoutPayment проверяет этот fiat по поддерживаемому пулу презентации и пересчитывает сумму на сервере.

    Smoke-проверка

    Запустите поставляемый smoke smk46_ из ring-platform.org:

    Smoke проверяет регистрацию pipeline, выбор и обновление провайдера, round-trip сервиса native ↔ main, опциональные контракты GET / POST конвертации, HTTP 400 для устаревших RING / USD и поведение ответа cron.