---
title: "Ring Oracle"
description: "Единый server-only фасад курсов для котировок desk нативного токена, мостов Chainlink, fiat FX, учёта кредитов и презентации цен в магазине"
locale: "ru"
---
# Ring Oracle

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

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

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

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

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

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

### For founders

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

  
- **[Единый денежный язык](/docs/features/payments.md)** — Кошелёк, checkout, membership и финансирование сообщества определяют стоимость проекта через одну модель деноминаций.

  
- **[Операционный FX-фид](/docs/features/payment-conductor.md)** — ProcessConductor обновляет fiat-курсы презентации, а ручные переопределения остаются доступны в конфиге клона.

  
- **[Честный checkout](/docs/features/store.md)** — Магазин разделяет то, что видит покупатель, и fiat-валюту, которую списывает карточный шлюз или PayPal.

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

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

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

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

### For developers

## Архитектура

| Поверхность | Проверенный путь | Ответственность |
|---|---|---|
| Фасад | `lib/ring-oracle/index.ts` | Server-only поверхность экспорта для каждого семейства курсов |
| Деноминации | `lib/value-denomination.ts` | Точная триада `ValueDenomination` и валидация |
| Desk oracle | `features/wallet/services/native-token-oracle.ts` | Курс native ↔ main, подписанные котировки, журнал аудита |
| Мост Chainlink | `features/wallet/services/native-token-chainlink-oracle.ts` | Фиды внешних EVM-токенов из allowlist |
| Fiat FX | `lib/fx/fx-feed-service.ts`, `lib/fx/fx-rates-overlay.ts` | Выбор провайдера, постоянный кеш, live overlay |
| Учёт кредитов | `lib/payments/credit-balance.ts` | Хелперы единица кредита ↔ main |
| FX pipeline | `lib/processes/fx/fx-feed-refresh.ts`, `lib/processes/registry.ts` | Обработчик ProcessConductor, ID и путь cron |
| API конвертации | `app/api/prices/conversion/route.ts` | Публичный контракт курса и конвертации native ↔ main |
| SSR hydrate | `app/layout.tsx` | `AuthenticatedAppShell` прогревает и читает курсы |
| Client provider | `components/providers/app-client-shell.tsx` | Передаёт `initialExchangeRates` в контекст валюты магазина |
| Контекст валюты магазина | `features/store/currency-context.tsx` | Режим отображения, конвертация, форматирование, предпочтения |
| Презентация checkout | `features/store/components/checkout/prebilling-page.tsx` | Выпадающий список fiat/crypto и fiat `paymentCurrency` |
| Списание checkout | `app/_actions/store-checkout-payment.ts` | Серверный пересчёт fiat для карты/PayPal |

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

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

{`import {
  ensureFxFeedFresh,
  getExchangeRates,
  getMainCurrencySymbol,
  getNativeTokenToMainCurrencyRate,
} from '@/lib/ring-oracle'

await ensureFxFeedFresh()
const rates = getExchangeRates()
const desk = await getNativeTokenToMainCurrencyRate()`}

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

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

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

{`{
  "fx": {
    "byMainCurrency": {
      "UAH": {
        "provider": "nbu",
        "enabled": true,
        "refreshHours": 24
      }
    },
    "default": {
      "provider": "open_er_api",
      "enabled": true,
      "refreshHours": 24
    },
    "manualOverrides": {}
  }
}`}

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

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

{`CRON_SECRET=replace-with-a-long-random-secret

curl \
  -H "Authorization: Bearer $CRON_SECRET" \
  https://your-ring.example/api/cron/fx-feed-refresh`}

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

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

`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`.

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

{`curl -X POST https://your-ring.example/api/prices/conversion \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "25",
    "from": "main_currency",
    "to": "native_token"
  }'`}

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

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

## Границы SSR и checkout

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

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

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

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

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

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

## Smoke-проверка

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

{`NODE_OPTIONS="--conditions=react-server" \
DB_BACKEND_MODE=k8s-postgres-fcm \
npx tsx scripts/smoke-ring-oracle-fx.cts

# Include public API and cron probes:
SMOKE_BASE_URL=http://localhost:3000 \
CRON_SECRET=replace-with-the-local-secret \
npx tsx scripts/smoke-ring-oracle-fx.cts`}

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

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

  
- [features/payment-conductor](/docs/features/payment-conductor.md) — Зависимость: PaymentConductor использует курсы Oracle, когда rail пересекает деноминации.

  
- [features/store](/docs/features/store.md) — Тот же процесс: отображение каталога, презентация в checkout и создание списания на сервере.

  
- [features/wallet](/docs/features/wallet.md) — Подробно: котировки Token Desk, учёт кредитов и балансы нативного токена.

  
- [features/rewards](/docs/features/rewards.md) — См. также: награды за активность фиксируют getMainCurrencyCreditAccountingRate; аварийный выключатель credit.rewards.enabled.
