Loading documentation...
Preparing Ring content
Концепції, цінність і типові сценарії
Концепції, цінність і типові сценарії
Preparing Ring content
Preparing Ring content
Preparing Ring content
WalletConductor — це server-only грошовий фасад Ring Platform для кастодіальних гаманців native token і фіатного кредитного ledger. Тонкі адаптери викликають conductor; PaymentConductor володіє checkout PSP для wallet_topup і native_token_onramp. Передача браузера після top-up — це redirect Conductor + followCheckoutResult — див. Архітектура PaymentConductor.
Гайд для оператора / продукту: WalletConductor · Wallet · PaymentConductor
Використовуйте вкладки Founder / Developer на бічній панелі документації, щоб відфільтрувати цю сторінку. Огляд функції (цінність + чекліст): WalletConductor. Інвентар HTTP/actions: Wallet API.
Можливості, SSOT двох курсів, чекліст оператора
Ledger, webhooks, обробники purpose
Actions і HTTP-поверхня
nativePerMainCurrency) ніколи не переписує математику store checkout або разового витрачання кредитів (credit.creditBalanceUnitToMainCurrency).POST /api/wallet/transfer залишаються поза WalletConductor, щоб клони випадково не змішували рейки.Залежність: після transferNative / ensure conductor розсилає `wallet:list` через publishWalletListUpdate.
Наступний крок: продуктовий гайд для операторів із двома аудиторіями.
Той самий процес: PSP ledger і webhooks для wallet_topup / native_token_onramp.
Див. також: потоки dashboard гаманця для учасника.
WalletConductor — це server-only грошовий фасад Ring Platform для кастодіальних гаманців native token і фіатного кредитного ledger. Тонкі адаптери викликають conductor; PaymentConductor володіє checkout PSP для wallet_topup і native_token_onramp. Передача браузера після top-up — це redirect Conductor + followCheckoutResult — див. Архітектура PaymentConductor.
Гайд для оператора / продукту: WalletConductor · Wallet · PaymentConductor
Використовуйте вкладки Founder / Developer на бічній панелі документації, щоб відфільтрувати цю сторінку. Огляд функції (цінність + чекліст): WalletConductor. Інвентар HTTP/actions: Wallet API.
Можливості, SSOT двох курсів, чекліст оператора
Ledger, webhooks, обробники purpose
Actions і HTTP-поверхня
nativePerMainCurrency) ніколи не переписує математику store checkout або разового витрачання кредитів (credit.creditBalanceUnitToMainCurrency).POST /api/wallet/transfer залишаються поза WalletConductor, щоб клони випадково не змішували рейки.Залежність: після transferNative / ensure conductor розсилає `wallet:list` через publishWalletListUpdate.
Наступний крок: продуктовий гайд для операторів із двома аудиторіями.
Той самий процес: PSP ledger і webhooks для wallet_topup / native_token_onramp.
Див. також: потоки dashboard гаманця для учасника.
WalletConductor — це server-only грошовий фасад Ring Platform для кастодіальних гаманців native token і фіатного кредитного ledger. Тонкі адаптери викликають conductor; PaymentConductor володіє checkout PSP для wallet_topup і native_token_onramp. Передача браузера після top-up — це redirect Conductor + followCheckoutResult — див. Архітектура PaymentConductor.
Гайд для оператора / продукту: WalletConductor · Wallet · PaymentConductor
Використовуйте вкладки Founder / Developer на бічній панелі документації, щоб відфільтрувати цю сторінку. Огляд функції (цінність + чекліст): WalletConductor. Інвентар HTTP/actions: Wallet API.
Можливості, SSOT двох курсів, чекліст оператора
Ledger, webhooks, обробники purpose
Actions і HTTP-поверхня
nativePerMainCurrency) ніколи не переписує математику store checkout або разового витрачання кредитів (credit.creditBalanceUnitToMainCurrency).POST /api/wallet/transfer залишаються поза WalletConductor, щоб клони випадково не змішували рейки.Залежність: після transferNative / ensure conductor розсилає `wallet:list` через publishWalletListUpdate.
Наступний крок: продуктовий гайд для операторів із двома аудиторіями.
Той самий процес: PSP ledger і webhooks для wallet_topup / native_token_onramp.
Див. також: потоки dashboard гаманця для учасника.
lib/payments/credit-balance.tsgetFiatCreditAccountingRateSSOT credit.creditBalanceUnitToMainCurrency |
| Desk | features/wallet/chains/solana/desk-service.ts | Котирування + виконання (subscriber+) |
| Desk oracle | features/wallet/services/native-token-oracle.ts | nativePerMainCurrency лише для desk |
| Custodial send | features/wallet/chains/native-token-transfer-service.ts | Gasless надсилання native |
| PSP checkout | lib/payments/conductor/payment-conductor.ts | wallet_topup, native_token_onramp |
| Onramp gate | lib/payments/confidential-token-onramp.ts | assertNativeTokenOnrampAllowed |
| Actions | app/_actions/wallet.ts | Обгортки для сесії |
| NFT buy | features/nft-market/services/solana-market-client.ts | Розрахунок купівлі на market |
| Метод | Auth / gates | Делегує до |
|---|---|---|
initiateTopUp | Сесія; amount 25–2000 | PaymentConductor wallet_topup; повертає redirect |
initiateNativeOnramp | Сесія + confidential+ + onramp flag | PaymentConductor native_token_onramp |
quoteDesk / executeDesk | assertTokenDeskSubscriberAccess | desk-service + oracle |
getNativeBalance | Caller userId | native-token-transfer-service |
transferNative | Caller userId | transfer service + wallet_transactions + publishWalletListUpdate(userId, 'updated') |
spendCredits | Caller userId | creditBalanceService + fiat rate (+ credit:balance tunnel через service) |
ensureNativeWallet | Caller supplies id (OAuth-safe) | ensure-wallet (+ wallet:list коли wallets змінюються) |
ensureFunded | Сесія | ensure + необов’язковий credit floor |
purchaseNftListing | Idempotency key | SolanaMarketClient |
Також експортується: getWalletConductorNativeChain() → getNativeChain().
| Курс | SSOT | Використовується в |
|---|---|---|
| Облік фіатних кредитів | credit.creditBalanceUnitToMainCurrency через getFiatCreditAccountingRate() | spendCredits, debit side desk, PaymentConductor credit_balance |
| Oracle Token Desk | platform_settings.web3.oracle.nativePerMainCurrency | лише quoteDesk / executeDesk |
Не належить WalletConductor: checkout store/membership (store_order, membership_upgrade, рейки credit_balance / native_token), життєвий цикл membership SubscriptionConductor і зовнішній EVM POST /api/wallet/transfer (Polygon POL / SupportedCrypto). Для кастодіальних надсилань native платформи надавайте перевагу /api/wallet/token/transfer.
app/_actions/wallet.ts)| Дія | Метод Conductor |
|---|---|
ensureUserWallets | ensureNativeWallet |
getNativeTokenBalanceAction | getNativeBalance |
spendCredits | spendCredits |
transferNativeTokens | transferNative |
executeDeskQuote | executeDesk |
initiateCreditTopupPayment | initiateTopUp |
initiateNativeTokenOnrampPayment | initiateNativeOnramp |
createPinAccessTokenAction | ensureNativeWallet |
Desk quote не має action-обгортки — лише HTTP (POST /api/wallet/desk/quote). Купівля NFT: app/_actions/nft-market.ts → purchaseNftListing. OAuth: auth.ts → ensureNativeWallet.
| Метод | Path | Метод Conductor |
|---|---|---|
POST | /api/wallet/desk/quote | quoteDesk |
POST | /api/wallet/desk/execute | executeDesk |
POST | /api/wallet/ensure | ensureNativeWallet |
GET | /api/wallet/token/balance | getNativeBalance |
POST | /api/wallet/token/transfer | transferNative |
POST | /api/wallet/credit/spend | spendCredits (fiat rate SSOT) |
| Шлях / поверхня | Чому |
|---|---|
POST /api/wallet/transfer | Шлях EVM SupportedCrypto — не Solana custodial SSOT |
POST /api/wallet/credit/topup | Chain-proof додавання кредитів через creditBalanceService (не card top-up) |
GET /api/wallet/credit/spend | 410 deprecated — використовуйте getSpendSummary / GET /api/wallet/credit/history |
| Store / membership purposes PaymentConductor | Checkout-рейки, а не фасад wallet |
Див. Архітектура PaymentConductor щодо CheckoutRedirect і WayForPay щодо HPP POST.
| Ключ | Роль |
|---|---|
WALLET_ENCRYPTION_KEY | Шифрування кастодіальних ключів |
SOLANA_RPC_URL / SOLANA_TREASURY_PRIVATE_KEY | Кастодіальний Solana + спонсорування gas |
CONFIDENTIAL_TOKEN_ONRAMP / NEXT_PUBLIC_CONFIDENTIAL_TOKEN_ONRAMP / desk nativeTokenOnramp | Gate native card onramp (isNativeTokenOnrampEnabled) |
credit.creditBalanceUnitToMainCurrency | Множник обліку фіатного ledger |
ORACLE_QUOTE_SECRET / RING_ORACLE_DEFAULT_RATE | HMAC котирування desk + fallback |
Server SSOT для onramp: lib/ring-config-chain.ts → isNativeTokenOnrampEnabled(). Runtime role gate: assertNativeTokenOnrampAllowed (confidential/admin/superadmin + flag).
getFiatCreditAccountingRate() — ніколи не передавайте desk nativePerMainCurrency у дебети кредитного ledger/api/wallet/token/* — застарілі псевдоніми /api/wallet/ring/* видаленоПоглиблення: Server Actions та інвентар HTTP.
lib/payments/credit-balance.tsgetFiatCreditAccountingRateSSOT credit.creditBalanceUnitToMainCurrency |
| Desk | features/wallet/chains/solana/desk-service.ts | Котирування + виконання (subscriber+) |
| Desk oracle | features/wallet/services/native-token-oracle.ts | nativePerMainCurrency лише для desk |
| Custodial send | features/wallet/chains/native-token-transfer-service.ts | Gasless надсилання native |
| PSP checkout | lib/payments/conductor/payment-conductor.ts | wallet_topup, native_token_onramp |
| Onramp gate | lib/payments/confidential-token-onramp.ts | assertNativeTokenOnrampAllowed |
| Actions | app/_actions/wallet.ts | Обгортки для сесії |
| NFT buy | features/nft-market/services/solana-market-client.ts | Розрахунок купівлі на market |
| Метод | Auth / gates | Делегує до |
|---|---|---|
initiateTopUp | Сесія; amount 25–2000 | PaymentConductor wallet_topup; повертає redirect |
initiateNativeOnramp | Сесія + confidential+ + onramp flag | PaymentConductor native_token_onramp |
quoteDesk / executeDesk | assertTokenDeskSubscriberAccess | desk-service + oracle |
getNativeBalance | Caller userId | native-token-transfer-service |
transferNative | Caller userId | transfer service + wallet_transactions + publishWalletListUpdate(userId, 'updated') |
spendCredits | Caller userId | creditBalanceService + fiat rate (+ credit:balance tunnel через service) |
ensureNativeWallet | Caller supplies id (OAuth-safe) | ensure-wallet (+ wallet:list коли wallets змінюються) |
ensureFunded | Сесія | ensure + необов’язковий credit floor |
purchaseNftListing | Idempotency key | SolanaMarketClient |
Також експортується: getWalletConductorNativeChain() → getNativeChain().
| Курс | SSOT | Використовується в |
|---|---|---|
| Облік фіатних кредитів | credit.creditBalanceUnitToMainCurrency через getFiatCreditAccountingRate() | spendCredits, debit side desk, PaymentConductor credit_balance |
| Oracle Token Desk | platform_settings.web3.oracle.nativePerMainCurrency | лише quoteDesk / executeDesk |
Не належить WalletConductor: checkout store/membership (store_order, membership_upgrade, рейки credit_balance / native_token), життєвий цикл membership SubscriptionConductor і зовнішній EVM POST /api/wallet/transfer (Polygon POL / SupportedCrypto). Для кастодіальних надсилань native платформи надавайте перевагу /api/wallet/token/transfer.
app/_actions/wallet.ts)| Дія | Метод Conductor |
|---|---|
ensureUserWallets | ensureNativeWallet |
getNativeTokenBalanceAction | getNativeBalance |
spendCredits | spendCredits |
transferNativeTokens | transferNative |
executeDeskQuote | executeDesk |
initiateCreditTopupPayment | initiateTopUp |
initiateNativeTokenOnrampPayment | initiateNativeOnramp |
createPinAccessTokenAction | ensureNativeWallet |
Desk quote не має action-обгортки — лише HTTP (POST /api/wallet/desk/quote). Купівля NFT: app/_actions/nft-market.ts → purchaseNftListing. OAuth: auth.ts → ensureNativeWallet.
| Метод | Path | Метод Conductor |
|---|---|---|
POST | /api/wallet/desk/quote | quoteDesk |
POST | /api/wallet/desk/execute | executeDesk |
POST | /api/wallet/ensure | ensureNativeWallet |
GET | /api/wallet/token/balance | getNativeBalance |
POST | /api/wallet/token/transfer | transferNative |
POST | /api/wallet/credit/spend | spendCredits (fiat rate SSOT) |
| Шлях / поверхня | Чому |
|---|---|
POST /api/wallet/transfer | Шлях EVM SupportedCrypto — не Solana custodial SSOT |
POST /api/wallet/credit/topup | Chain-proof додавання кредитів через creditBalanceService (не card top-up) |
GET /api/wallet/credit/spend | 410 deprecated — використовуйте getSpendSummary / GET /api/wallet/credit/history |
| Store / membership purposes PaymentConductor | Checkout-рейки, а не фасад wallet |
Див. Архітектура PaymentConductor щодо CheckoutRedirect і WayForPay щодо HPP POST.
| Ключ | Роль |
|---|---|
WALLET_ENCRYPTION_KEY | Шифрування кастодіальних ключів |
SOLANA_RPC_URL / SOLANA_TREASURY_PRIVATE_KEY | Кастодіальний Solana + спонсорування gas |
CONFIDENTIAL_TOKEN_ONRAMP / NEXT_PUBLIC_CONFIDENTIAL_TOKEN_ONRAMP / desk nativeTokenOnramp | Gate native card onramp (isNativeTokenOnrampEnabled) |
credit.creditBalanceUnitToMainCurrency | Множник обліку фіатного ledger |
ORACLE_QUOTE_SECRET / RING_ORACLE_DEFAULT_RATE | HMAC котирування desk + fallback |
Server SSOT для onramp: lib/ring-config-chain.ts → isNativeTokenOnrampEnabled(). Runtime role gate: assertNativeTokenOnrampAllowed (confidential/admin/superadmin + flag).
getFiatCreditAccountingRate() — ніколи не передавайте desk nativePerMainCurrency у дебети кредитного ledger/api/wallet/token/* — застарілі псевдоніми /api/wallet/ring/* видаленоПоглиблення: Server Actions та інвентар HTTP.
lib/payments/credit-balance.tsgetFiatCreditAccountingRateSSOT credit.creditBalanceUnitToMainCurrency |
| Desk | features/wallet/chains/solana/desk-service.ts | Котирування + виконання (subscriber+) |
| Desk oracle | features/wallet/services/native-token-oracle.ts | nativePerMainCurrency лише для desk |
| Custodial send | features/wallet/chains/native-token-transfer-service.ts | Gasless надсилання native |
| PSP checkout | lib/payments/conductor/payment-conductor.ts | wallet_topup, native_token_onramp |
| Onramp gate | lib/payments/confidential-token-onramp.ts | assertNativeTokenOnrampAllowed |
| Actions | app/_actions/wallet.ts | Обгортки для сесії |
| NFT buy | features/nft-market/services/solana-market-client.ts | Розрахунок купівлі на market |
| Метод | Auth / gates | Делегує до |
|---|---|---|
initiateTopUp | Сесія; amount 25–2000 | PaymentConductor wallet_topup; повертає redirect |
initiateNativeOnramp | Сесія + confidential+ + onramp flag | PaymentConductor native_token_onramp |
quoteDesk / executeDesk | assertTokenDeskSubscriberAccess | desk-service + oracle |
getNativeBalance | Caller userId | native-token-transfer-service |
transferNative | Caller userId | transfer service + wallet_transactions + publishWalletListUpdate(userId, 'updated') |
spendCredits | Caller userId | creditBalanceService + fiat rate (+ credit:balance tunnel через service) |
ensureNativeWallet | Caller supplies id (OAuth-safe) | ensure-wallet (+ wallet:list коли wallets змінюються) |
ensureFunded | Сесія | ensure + необов’язковий credit floor |
purchaseNftListing | Idempotency key | SolanaMarketClient |
Також експортується: getWalletConductorNativeChain() → getNativeChain().
| Курс | SSOT | Використовується в |
|---|---|---|
| Облік фіатних кредитів | credit.creditBalanceUnitToMainCurrency через getFiatCreditAccountingRate() | spendCredits, debit side desk, PaymentConductor credit_balance |
| Oracle Token Desk | platform_settings.web3.oracle.nativePerMainCurrency | лише quoteDesk / executeDesk |
Не належить WalletConductor: checkout store/membership (store_order, membership_upgrade, рейки credit_balance / native_token), життєвий цикл membership SubscriptionConductor і зовнішній EVM POST /api/wallet/transfer (Polygon POL / SupportedCrypto). Для кастодіальних надсилань native платформи надавайте перевагу /api/wallet/token/transfer.
app/_actions/wallet.ts)| Дія | Метод Conductor |
|---|---|
ensureUserWallets | ensureNativeWallet |
getNativeTokenBalanceAction | getNativeBalance |
spendCredits | spendCredits |
transferNativeTokens | transferNative |
executeDeskQuote | executeDesk |
initiateCreditTopupPayment | initiateTopUp |
initiateNativeTokenOnrampPayment | initiateNativeOnramp |
createPinAccessTokenAction | ensureNativeWallet |
Desk quote не має action-обгортки — лише HTTP (POST /api/wallet/desk/quote). Купівля NFT: app/_actions/nft-market.ts → purchaseNftListing. OAuth: auth.ts → ensureNativeWallet.
| Метод | Path | Метод Conductor |
|---|---|---|
POST | /api/wallet/desk/quote | quoteDesk |
POST | /api/wallet/desk/execute | executeDesk |
POST | /api/wallet/ensure | ensureNativeWallet |
GET | /api/wallet/token/balance | getNativeBalance |
POST | /api/wallet/token/transfer | transferNative |
POST | /api/wallet/credit/spend | spendCredits (fiat rate SSOT) |
| Шлях / поверхня | Чому |
|---|---|
POST /api/wallet/transfer | Шлях EVM SupportedCrypto — не Solana custodial SSOT |
POST /api/wallet/credit/topup | Chain-proof додавання кредитів через creditBalanceService (не card top-up) |
GET /api/wallet/credit/spend | 410 deprecated — використовуйте getSpendSummary / GET /api/wallet/credit/history |
| Store / membership purposes PaymentConductor | Checkout-рейки, а не фасад wallet |
Див. Архітектура PaymentConductor щодо CheckoutRedirect і WayForPay щодо HPP POST.
| Ключ | Роль |
|---|---|
WALLET_ENCRYPTION_KEY | Шифрування кастодіальних ключів |
SOLANA_RPC_URL / SOLANA_TREASURY_PRIVATE_KEY | Кастодіальний Solana + спонсорування gas |
CONFIDENTIAL_TOKEN_ONRAMP / NEXT_PUBLIC_CONFIDENTIAL_TOKEN_ONRAMP / desk nativeTokenOnramp | Gate native card onramp (isNativeTokenOnrampEnabled) |
credit.creditBalanceUnitToMainCurrency | Множник обліку фіатного ledger |
ORACLE_QUOTE_SECRET / RING_ORACLE_DEFAULT_RATE | HMAC котирування desk + fallback |
Server SSOT для onramp: lib/ring-config-chain.ts → isNativeTokenOnrampEnabled(). Runtime role gate: assertNativeTokenOnrampAllowed (confidential/admin/superadmin + flag).
getFiatCreditAccountingRate() — ніколи не передавайте desk nativePerMainCurrency у дебети кредитного ledger/api/wallet/token/* — застарілі псевдоніми /api/wallet/ring/* видаленоПоглиблення: Server Actions та інвентар HTTP.