{"id":44192947,"url":"https://github.com/tetherto/wdk-react-native-core","last_synced_at":"2026-04-02T00:55:34.514Z","repository":{"id":331590031,"uuid":"1122355423","full_name":"tetherto/wdk-react-native-core","owner":"tetherto","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-10T10:09:14.000Z","size":563,"stargazers_count":1,"open_issues_count":3,"forks_count":7,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-11T02:12:54.189Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tetherto.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-24T14:59:02.000Z","updated_at":"2026-01-10T10:09:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tetherto/wdk-react-native-core","commit_stats":null,"previous_names":["tetherto/wdk-react-native-core"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/tetherto/wdk-react-native-core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tetherto%2Fwdk-react-native-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tetherto%2Fwdk-react-native-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tetherto%2Fwdk-react-native-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tetherto%2Fwdk-react-native-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tetherto","download_url":"https://codeload.github.com/tetherto/wdk-react-native-core/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tetherto%2Fwdk-react-native-core/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29274727,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-09T17:15:22.002Z","status":"ssl_error","status_checked_at":"2026-02-09T17:14:42.395Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-09T18:00:32.463Z","updated_at":"2026-04-02T00:55:34.506Z","avatar_url":"https://github.com/tetherto.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @tetherto/wdk-react-native-core\n\nCore functionality for React Native wallets, providing wallet management, balance fetching, and more.\n\nThis library uses a unique **worklet bundle** to run intensive cryptographic operations on a separate thread, ensuring your app's UI remains fast and responsive.\n\n## Features\n\n- **⛓️ Multi-Chain Support:** Manage wallets across different EVM-based networks.\n- **🧩 Extensible Architecture:** Add support for new blockchains and account types via worklets.\n- **🔐 Secure Storage:** Automatic encryption and secure keychain storage for sensitive data.\n- **⚛️ Modern React Hooks:** A simple, powerful API for integrating wallet features into your React Native app.\n- **📦 Lightweight \u0026 Modular:** Generate optimized bundles with only the chains you need.\n\n## Table of Contents\n\n- [Features](#features)\n- [Installation](#installation)\n- [Bundle Configuration](#bundle-configuration)\n- [Quick Start](#quick-start)\n- [Guide to Hooks](#guide-to-hooks)\n- [Best Practices](#best-practices)\n- [Architecture](#architecture)\n- [Security](#security)\n- [Troubleshooting](#troubleshooting)\n- [Development](#development)\n- [License](#license)\n\n## Installation\n\n### 1. Install the Core Library\n```bash\nnpm install @tetherto/wdk-react-native-core\n```\n\n### 2. Install the Worklet Bundler\nYou need the bundler to generate the bundle file. You can install it globally or as a dev dependency in your project.\n\n**Global Install (Recommended for easy access):**\n```bash\nnpm install -g @tetherto/wdk-worklet-bundler\n```\n\n**Or, as a Dev Dependency:**\n```bash\nnpm install --save-dev @tetherto/wdk-worklet-bundler\n```\n\n## Bundle Configuration\n\nA key part of this library's architecture is the **Worklet Bundle**.\n\n**What is the Worklet Bundle?**\nThe bundle is a separate JavaScript file (`bundle.js`) that contains all the core cryptographic and blockchain logic. This code runs on a dedicated, high-performance thread, completely separate from the React Native UI thread.\n\n**Why is it necessary?**\nRunning wallet operations in a separate thread is crucial for performance. It ensures that intensive tasks like signing transactions or deriving keys do not slow down or freeze your app's user interface, resulting in a smooth and responsive experience. The bundling step also allows you to create a small, optimized bundle with only the blockchain modules you actually need.\n\nTo get the bundle, use the `@tetherto/wdk-worklet-bundler` CLI to generate one with only the blockchain modules you need:\n\n```bash\n# 1. Initialize configuration in your React Native project\nwdk-worklet-bundler init\n\n# 2. Edit wdk.config.js to configure your networks (see example below)\n\n# 3. Generate the bundle\nwdk-worklet-bundler generate\n```\n\nExample `wdk.config.js`:\n```javascript\n// wdk.config.js\nmodule.exports = {\n  // Define the networks you want to support and their corresponding packages.\n  networks: {\n    ethereum: {\n      package: '@tetherto/wdk-wallet-evm-erc-4337'\n    },\n    bitcoin: {\n      package: '@tetherto/wdk-wallet-btc'\n    }\n  }\n};\n```\n\nAfter running `wdk-worklet-bundler generate`, you will see the bundle in the directory `.wdk`.\n\nFor the full bundler documentation, see [wdk-worklet-bundler](https://github.com/tetherto/wdk-worklet-bundler).\n\n## Quick Start\n\nGetting started involves three main steps:\n\n1.  **Configuration:** Define your networks and generate the worklet bundle.\n2.  **Provider Setup:** Wrap your application in `WdkAppProvider` and pass it your configuration.\n3.  **Use the Hooks:** Use hooks like `useWalletManager` and `useAddresses` to manage the wallet and access its data.\n\n➡️ **For a complete example, see the [Full Quick Start Guide](docs/quick-start.md).**\n\n## Guide to Hooks\n\nThe library's functionality is exposed through a set of React hooks. They are designed to separate concerns, giving you specific tools for managing the app state, wallet lifecycle, and account interactions.\n\n### `useWdkApp`\n*   **Design Rationale:** Provides a global, top-level view of the library's state. It's the single source of truth for whether the underlying engine is ready, allowing your app to react safely.\n*   **Standard Use Case:** Displaying a loading screen while the WDK initializes.\n*   **Snippet:**\n    ```typescript\n    import { useWdkApp } from '@tetherto/wdk-react-native-core';\n\n    const { isReady, error } = useWdkApp();\n    if (!isReady) {\n      // Show a loading or splash screen while the worklet starts\n    }\n    ```\n\n### `useWalletManager`\n*   **Design Rationale:** Exclusively handles \"heavy\" lifecycle actions that affect the entire wallet (create, load, import). Separating these ensures they are used deliberately, typically during app startup or in a settings screen.\n*   **Standard Use Case:** Checking if a wallet exists on startup, creating or loading a wallet.\n*   **Snippet:**\n    ```typescript\n    import { useWdkApp, useWalletManager } from '@tetherto/wdk-react-native-core';\n\n    const { isReady } = useWdkApp();\n    const { createWallet, loadWallet } = useWalletManager();\n    \n    useEffect(() =\u003e {\n      if (isReady) {\n        const setup = async () =\u003e {\n          await createWallet();\n        };\n        setup();\n      }\n    }, [isReady, hasWallet, createWallet, loadWallet]);\n    ```\n\n### `useAddresses`\n*   **Design Rationale:** Decouples the loading and management of addresses from other account operations. This provides a focused way to get a list of addresses for the active wallet.\n*   **Standard Use Case:** Loading the addresses for the active wallet to display them.\n*   **Snippet:**\n    ```typescript\n    import { useAddresses } from '@tetherto/wdk-react-native-core';\n\n    const { addresses, loadAddresses } = useAddresses();\n\n    // After a wallet is loaded (e.g. in another useEffect), load addresses.\n    useEffect(() =\u003e {\n      if (walletIsActive) { // Replace with your app's state logic\n        loadAddresses([0, 1]); // Load addresses for account 0 and 1\n      }\n    }, [walletIsActive, loadAddresses]);\n    ```\n\n### `useAccount`\n*   **Design Rationale:** Provides the actual \"actor\" for a specific account (e.g., account #0 on Ethereum). This is where you find methods for *doing things* like signing transactions or messages.\n*   **Standard Use Case:** Getting the `account` object to call `signMessage` when a user clicks a button.\n*   **Snippet:**\n    ```typescript\n    import { useAccount } from '@tetherto/wdk-react-native-core';\n\n    const { account } = useAccount({ network: 'ethereum', accountIndex: 0 });\n\n    const handleSignPress = async () =\u003e {\n      const signature = await account?.signMessage('Hello WDK');\n      console.log(signature);\n    };\n    ```\n\n### `useBalance`\n*   **Design Rationale:** Isolates the logic for fetching balances. It uses TanStack Query internally to automatically handle caching, refetching, and loading states, saving you from writing boilerplate.\n*   **Standard Use Case:** Getting the balance for a native asset (like ETH). You must define your assets first.\n*   **Snippet:**\n    ```typescript\n    import { useBalance } from '@tetherto/wdk-react-native-core';\n    \n    // Assume 'ethAsset' is an asset object you've defined elsewhere\n    const { data } = useBalance({ \n      accountIndex: 0, \n      asset: ethAsset \n    });\n\n    const balanceString = data?.balance; // e.g., '1000000000000000000'\n    ```\n\n## Best Practices\n\nSee [Best Practices](docs/best-practices.md) for important patterns and recommendations for building robust apps.\n\n## Architecture\n\nSee [Architecture](docs/architecture.md) for details on the internal design.\n\n## Security\n\nSee [Security](docs/security.md) for details on security features and best practices.\n\n## Troubleshooting\n\nSee [Troubleshooting](docs/troubleshooting.md) for common issues and solutions.\n\n## Development\n\nSee the [Contributing Guide](CONTRIBUTING.md) for details on how to build, test, and contribute to this project.\n\n## License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftetherto%2Fwdk-react-native-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftetherto%2Fwdk-react-native-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftetherto%2Fwdk-react-native-core/lists"}