Add docs for @tetherto/wdk-react-native-core#96
Add docs for @tetherto/wdk-react-native-core#96gatteo wants to merge 5 commits intotetherto:developfrom
Conversation
Adds landing page and API reference for the new React Native Core library that replaces wdk-react-native-provider. Updates the quickstart guide, UI Kit integration example, and SKILL.md to use the new hooks-based API (useWdkApp, useWalletManager, useAccount, useBalance).
gatteo
force-pushed
the
docs/react-native-core
branch
from
79ed077 to
1bcaec2
Compare
- useWdkApp() now returns { state, retry } with WdkAppState discriminated union
- useAccount() always returns object (never null), adds isLoading, error, estimateFee
- useBalance() signature changed to (accountIndex, asset, options?) — network derived from asset
- useWalletManager() updated createTemporaryWallet(walletId, mnemonic?), added crypto methods
- useAddresses() loadAddresses now returns Promise<AddressInfoResult[]>
- Removed AppStatus/InitializationStatus enums (no longer exported)
- WalletInfo no longer has isActive field
- Added requireBiometrics prop to WdkAppProvider
- Custom bundle (.wdk/) now recommended over pre-built bundle
README.md: - Simplify to one-line description, remove old provider reference - Reorder: Quick Start before Bundle Configuration - Add full bundler script from repo README (wdk.config.js example) - Simplify Features section (less technical) - Move Architecture to last section - Replace em dashes with normal dashes API Reference: - Add lightweight table of contents at top - Remove duplicate description line - Simplify hook titles (remove parameter signatures) - Replace em dashes with normal dashes React Native Quickstart: - Remove Step 2 (install dependencies) - handled by npm install - Add wdk-worklet-bundler link in bundle step - Remove currentUserId from provider snippets - Shorten Step 6 hook example to match README style - Convert troubleshooting headings to bold text - Remove checkmark emojis from checklist - Replace em dashes with normal dashes
Quickstart: - Step 4: use Sepolia testnet with free public RPC (no API key needed) - Step 4: add hint for where to get Indexer API keys - Step 4: add hint that config uses testnet, link to mainnet guide - Step 6: add link to full API Reference for hooks - Step 3 (bundle): add hint about which WDK modules to install - Starter template: improve indexer API key hint - Troubleshooting: add biometric prompt on simulator section Configuration (out of topic): - Fix broken middleware section - missing code block closing tags
ihsraham
left a comment
ihsraham
left a comment
There was a problem hiding this comment.
Did a full audit against @tetherto/wdk-react-native-core@1.0.0-beta.3, cross-referencing with the source and running tsc import checks. Overall this is solid, the hooks, BaseAsset, WdkAppState discriminated union, WdkAppProvider props, IAsset, AssetConfig, BalanceFetchResult, BundleConfig, BalanceQueryOptions, WalletInfo, and AccountInfo all match the types exactly. The config fix for configuration.md is a nice bonus too. Left a few comments on the type stuff.
| ### March 7, 2026 | ||
|
|
||
| **What's New** | ||
| - **[React Native Core](../tools/react-native-core/)**: Added documentation for `@tetherto/wdk-react-native-core` (v1.0.0-beta.3), the hooks-based React Native integration layer for WDK. Includes [API Reference](../tools/react-native-core/api-reference.md) covering `WdkAppProvider`, `useWdkApp`, `useWalletManager`, `useAccount`, `useBalance`, and more. Updated [React Native Quickstart](../start-building/react-native-quickstart.md) with step-by-step integration guide. |
There was a problem hiding this comment.
- React Native Core: Added documentation for
@tetherto/wdk-react-native-core(v1.0.0-beta.3), the hooks-based React Native integration layer for WDK. Includes API Reference coveringWdkAppProvider,useWdkApp,useWalletManager,useAccount,useBalance, and more. Updated React Native Quickstart with step-by-step integration guide.
|
|
||
| # API Reference | ||
|
|
||
| | Export | Type | Description | |
There was a problem hiding this comment.
The package also exports these types that aren't listed here: WdkAppProviderProps, WdkAppContextValue, UseAddressesReturn, UseAccountParams, UseAccountReturn, UseWalletManagerResult. Not blocking but worth adding so TS users know they can import them.
|
|
||
| ```typescript | ||
| interface WdkConfigs<TNetwork = Record<string, unknown>, TProtocol = Record<string, unknown>> { | ||
| indexer: { |
There was a problem hiding this comment.
@jonathunne @gatteo the indexer field here doesn't seem to be present in the TypeScript types. WdkConfigs extends WdkWorkletConfig from pear-wrk-wdk, and neither of them include indexer. I installed @tetherto/wdk-react-native-core@1.0.0-beta.3 and ran tsc against a test file with const config: WdkConfigs = { indexer: {...}, networks: {...} } and it gives TS2353: Object literal may only specify known properties, and 'indexer' does not exist in type 'WdkConfigs'. The config does get forwarded to the worklet via JSON.stringify so it probably works at runtime, but users who type their config as WdkConfigs will get a TS error. I haven't tried running an app with this package, if it is needed we should have it in the types, right?
|
|
||
| ```typescript | ||
| interface WdkConfigs<TNetwork = Record<string, unknown>, TProtocol = Record<string, unknown>> { | ||
| indexer: { |
There was a problem hiding this comment.
@jonathunne @gatteo the indexer field here doesn't seem to be present in the TypeScript types. WdkConfigs extends WdkWorkletConfig from pear-wrk-wdk, and neither of them include indexer. I ran tsc against a test file with const config: WdkConfigs = { indexer: {...}, networks: {...} } and it gives TS2353: Object literal may only specify known properties, and 'indexer' does not exist in type 'WdkConfigs'. The config does get forwarded to the worklet via JSON.stringify so it probably works at runtime, but users who type their config as WdkConfigs will get a TS error. I haven't tried running an app with this package, if it is needed we should have it in the types, right?
| Root configuration object passed to `WdkAppProvider`. Defines network and protocol configurations for the WDK worklet. | ||
|
|
||
| ```typescript | ||
| interface WdkConfigs<TNetwork = Record<string, unknown>, TProtocol = Record<string, unknown>> { |
There was a problem hiding this comment.
This type definition inlines the network/protocol shapes instead of using the actual wrapper types from the source. The real type uses WdkNetworkConfig<TNetwork> and WdkProtocolConfig<TProtocol>, and WdkConfigs extends WdkWorkletConfig. If we just show the actual types here and document WdkNetworkConfig and WdkProtocolConfig below (like AddressInfo/AddressInfoResult under useAddresses).
| | Field | Type | Description | | ||
| |-------|------|-------------| | ||
| | `accountIndex` | `number` | Account index | | ||
| | `network` | `string` | Network (required for `'token'` and `'network'` types) | |
There was a problem hiding this comment.
Checked RefreshBalanceParams in the source, all fields except accountIndex are optional (?). The table here shows network, assetId, type, and walletId as plain string without optional markers. Verified with tsc: { accountIndex: 0 } alone compiles fine, confirming the others are optional. The description for walletId says "Optional" but the type column doesn't reflect it. Same inconsistency for type which has a default value mentioned but isn't marked optional.
| | `success` | `boolean` | Whether the transaction succeeded | | ||
| | `hash` | `string` | Transaction hash | | ||
| | `fee` | `string` | Fee paid | | ||
| | `error` | `string` | Error message (only if `success` is `false`) | |
There was a problem hiding this comment.
error is shown as string here but it's actually optional. TransactionResult extends UseAccountResponse where error is declared as error?: string. The UseAccountResponse block right above (line 246) correctly shows error?: string, but the TransactionResult table loses the ?. Small thing but would confuse someone checking types.
| | `state` | [`WdkAppState`](#wdkappstate) | Current app state (discriminated union) | | ||
| | `retry` | `() => void` | Retry initialization after an error | | ||
|
|
||
| ### WdkAppState |
There was a problem hiding this comment.
Two things:
-
WdkAppStateisn't exported fromindex.ts, soimport { WdkAppState } from '@tetherto/wdk-react-native-core'fails. Verified withtsc. Same forTransactionParams,TransactionResult,UseAccountResponse(all inuseAccount.ts),AddressInfo,AddressInfoResult, andBalanceQueryOptions(inuseBalance.ts). They're defined in hook files but not re-exported. Worth a note, or better, adding the exports to the package. -
Some return types are referenced by name but never defined:
UseBalanceResult(line 414),UseBalancesForWalletResult(line 470). The properties are described in tables which is great, but someone reading "ReturnsUseBalanceResult" will look for a definition and not find one. Either show a type definition block or drop the type name from the heading and just say "Returns" with the table.
| ### March 7, 2026 | ||
|
|
||
| **What's New** | ||
| - **[React Native Core](../tools/react-native-core/)**: Added documentation for `@tetherto/wdk-react-native-core` (v1.0.0-beta.3), the hooks-based React Native integration layer for WDK. Includes [API Reference](../tools/react-native-core/api-reference.md) covering `WdkAppProvider`, `useWdkApp`, `useWalletManager`, `useAccount`, `useBalance`, and more. Updated [React Native Quickstart](../start-building/react-native-quickstart.md) with step-by-step integration guide. |
There was a problem hiding this comment.
Small thing: the version mention should be a link per our style guide. Something like ([v1.0.0-beta.3](https://github.com/tetherto/wdk-core-react-native/releases/tag/v1.0.0-beta.3)) instead of just (v1.0.0-beta.3).
2 participants
Summary
Adds full documentation for
@tetherto/wdk-react-native-core(v1.0.0-beta.3), the hooks-based React Native integration layer for WDK. Replaces all references to the deprecatedwdk-react-native-provider.Changes
tools/react-native-core/README.mdtools/react-native-core/api-reference.mdWdkAppProvider,useWdkApp(discriminated unionWdkAppState),useWalletManager,useAccount(withestimateFee,extension),useAddresses,useBalance,useBalancesForWallet,useRefreshBalance,BaseAsset, types, utilitiesstart-building/react-native-quickstart.mdwdk-worklet-bundler, hints for Indexer API keys / module selection / biometrics on simulator, link to API referenceui-kits/react-native-ui-kit/get-started.mduseWdkAppstate pattern +useBalance(accountIndex, asset)signatureskills/wdk/SKILL.mdwdk-react-native-provider→wdk-react-native-corein package tableSUMMARY.mdoverview/changelog.mdsdk/core-module/configuration.mdKey API changes documented (beta.2 → beta.3)
useWdkApp()returns{ state: WdkAppState, retry }with discriminated union (INITIALIZING,NO_WALLET,LOCKED,READY,ERROR)useAccount()always returns an object (never null), addsisLoading,error,estimateFee,UseAccountResponse-based return typesuseBalance()signature changed to(accountIndex, asset, options?)- network derived from assetuseWalletManager()updatedcreateTemporaryWallet(walletId, mnemonic?), added advanced crypto methodsWdkAppProvideraddsrequireBiometricspropAppStatus/InitializationStatusenums (no longer exported)Test plan
wdk-react-native-providerexcept deprecation notessdk/core-module/configuration.mdrenders correctly