@tuwaio/evm-sdk 0.1.13 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,251 +1,89 @@
1
1
  # @tuwaio/evm-sdk
2
2
 
3
3
  [![NPM Version](https://img.shields.io/npm/v/@tuwaio/evm-sdk.svg)](https://www.npmjs.com/package/@tuwaio/evm-sdk)
4
- [![License](https://img.shields.io/npm/l/@tuwaio/evm-sdk.svg)](./LICENSE)
4
+ [![License](https://img.shields.io/npm/l/@tuwaio/evm-sdk.svg)](https://github.com/TuwaIO/sdk/blob/main/packages/evm-sdk/LICENSE)
5
5
 
6
- The **Layer 9 (L9)** EVM Network Adapter SDK for the TUWA Ecosystem. Packages all Ethereum-compatible logic (`OrbitEVM`, `PulsarEVM`, `SatelliteEVM`, `EVMConnectorsWatcher`) into clean subpath entry points.
6
+ `@tuwaio/evm-sdk` is the EVM add-on (Layer 9, L9) of [`@tuwaio/sdk`](https://sdk.docs.tuwa.io/packages/sdk). It re-exports the EVM packages of the TUWA projects under subpaths — Orbit Utils, Satellite Connect, Pulsar, SIWX and Nova Connect — built on [`viem`](https://viem.sh) and [`@wagmi/core`](https://wagmi.sh/core). An app with EVM wallets installs `@tuwaio/sdk` and this package; nothing of it is loaded in a Solana-only app.
7
7
 
8
8
  ---
9
9
 
10
- ## 🏛️ What is `@tuwaio/evm-sdk`?
10
+ ## 🏛️ Core Capabilities
11
11
 
12
- `@tuwaio/evm-sdk` is **Layer 9 (L9)** of the TUWA ecosystem architecture — a **headless**, purely logical adapter SDK designed to teach the core `@tuwaio/sdk` (L8) how to interact with EVM-compatible blockchains.
13
-
14
- It securely wraps `viem` and `@wagmi/core`, providing standardized adapters for Wallet Connection (Satellite) and Transaction Tracking (Pulsar). This modular subpath approach ensures your app only ships EVM dependencies when you actually need them.
15
-
16
- ---
17
-
18
- ## ✨ Key Features
19
-
20
- - **⛓️ EVM Native**: Full support for Wagmi config creation, Viem transports, and injected connectors.
21
- - **🌐 Ecosystem Adapters**: Packages OrbitEVM, PulsarEVM, SatelliteEVM, and EVMConnectorsWatcher under unified subpaths.
22
- - **⚡ Subpath Architecture**: Clean subpath imports (`@tuwaio/evm-sdk/satellite`, `@tuwaio/evm-sdk/pulsar`, `@tuwaio/evm-sdk/orbit`, `@tuwaio/evm-sdk/nova-connect`, `@tuwaio/evm-sdk/siwx`).
23
- - **🧩 Zero UI Bloat**: Focuses strictly on connection logic and transaction processing adapters.
24
- - **🔄 State Sync & Watchers**: Includes background watchers (`EVMConnectorsWatcher`) that automatically sync Wagmi state with Satellite's unified store.
25
- - **🔐 Headless SIWX Auth**: Provides the EVM-native message signer (`createEvmSiwxSigner`) for seamless CAIP-122 authentication (`@tuwaio/evm-sdk/siwx`).
26
-
27
- > [!WARNING]
28
- > **SIWX Migration Notice**: Legacy SIWE authorization flows in Satellite are **deprecated**. Migrate to `@tuwaio/evm-sdk/siwx` (`createEvmSiwxSigner`) and `@tuwaio/sdk/siwx/server` for multi-chain CAIP-122 authentication.
12
+ - **Chain packages in one install:** `@tuwaio/orbit-evm`, `@tuwaio/satellite-evm`, `@tuwaio/pulsar-evm` and `@tuwaio/siwx-evm` are dependencies, pinned to versions that work with the same release of `@tuwaio/sdk`.
13
+ - **Nova Connect for EVM:** importing `@tuwaio/evm-sdk/nova-connect` registers the EVM chain helpers of `@tuwaio/orbit-evm` for the chain lists of Nova Connect, types `appChains` of `NovaConnectProvider` as your viem chains and adds the EVM connection types to Satellite Connect. It goes through `@tuwaio/sdk/nova-connect/evm`, so this applies to the `NovaConnectProvider` and `SatelliteConnectProvider` that `@tuwaio/sdk` exports.
14
+ - **Subpaths:** every subpath re-exports one package, unchanged. Its reference is on the site of that package.
29
15
 
30
16
  ---
31
17
 
32
18
  ## 💾 Installation
33
19
 
34
- Install this package alongside the core SDK and the required Web3 singletons:
35
-
36
20
  ```bash
37
- pnpm add @tuwaio/sdk @tuwaio/evm-sdk viem @wagmi/core
38
- ```
39
-
40
- ---
41
-
42
- ## 🚀 Quick Start (EVM Integration)
43
-
44
- To cleanly integrate EVM wallets and transaction tracking with TUWA, you should adopt a modular architecture. Below is the recommended implementation pattern using subpath imports.
45
-
46
- > **Note:** This example uses standard client-side state. For Quasar Cloud syncing and server-side tracking, see the full-stack guide in the core `@tuwaio/sdk` documentation.
47
-
48
- ### 1. Define Transaction Types (`types.ts`)
49
-
50
- ```ts
51
- // src/types.ts
52
- import type { Transaction } from '@tuwaio/sdk/pulsar';
53
-
54
- export enum AppTxType {
55
- SWAP = 'SWAP',
56
- }
57
-
58
- export type SwapTx = Transaction & {
59
- type: AppTxType.SWAP;
60
- payload: { tokenIn: string; tokenOut: string; amount: number };
61
- };
62
-
63
- export type TransactionUnion = SwapTx;
64
- ```
65
-
66
- ### 2. Tracking Store (`usePulsarStore.ts`)
67
-
68
- Create a headless tracking store specifically for EVM transactions.
69
-
70
- ```ts
71
- // src/hooks/usePulsarStore.ts
72
- 'use client';
73
-
74
- import { createPulsarStore, createBoundedUseStore } from '@tuwaio/sdk/pulsar';
75
- import { pulsarEvmAdapter } from '@tuwaio/evm-sdk/pulsar';
76
- import { wagmiConfig, appEVMChains } from '@/configs/appConfig';
77
- import { TransactionUnion } from '@/types';
78
-
79
- const initialStore = createPulsarStore<TransactionUnion>({
80
- name: 'tuwa-transactions-evm',
81
- adapter: [pulsarEvmAdapter(wagmiConfig, appEVMChains)],
82
- });
83
-
84
- export const usePulsarStore = createBoundedUseStore(initialStore);
21
+ pnpm add @tuwaio/sdk @tuwaio/evm-sdk @wagmi/core viem react react-dom
85
22
  ```
86
23
 
87
- ### 3. Nova Transactions Provider (`NovaTransactionsProvider.tsx`)
88
-
89
- Binds the React UI elements to the headless transaction state.
90
-
91
- ```tsx
92
- // src/providers/NovaTransactionsProvider.tsx
93
- 'use client';
94
-
95
- import { useSatelliteConnectStore } from '@tuwaio/sdk/satellite';
96
- import { useInitializeTransactionsPool } from '@tuwaio/sdk/pulsar';
97
- import { getAdapterFromConnectorType } from '@tuwaio/sdk/orbit';
98
- import { NovaTransactionsProvider as NTP } from '@tuwaio/sdk/nova-transactions/providers';
99
- import { usePulsarStore } from '@/hooks/usePulsarStore';
100
-
101
- export function NovaTransactionsProvider() {
102
- const initialTx = usePulsarStore((s) => s.initialTx);
103
- const closeTxTrackedModal = usePulsarStore((s) => s.closeTxTrackedModal);
104
- const executeTxAction = usePulsarStore((s) => s.executeTxAction);
105
- const initializeTransactionsPool = usePulsarStore((s) => s.initializeTransactionsPool);
106
- const getAdapter = usePulsarStore((s) => s.getAdapter);
107
- const transactionsPool = usePulsarStore((s) => s.transactionsPool);
108
-
109
- const activeConnection = useSatelliteConnectStore((s) => s.activeConnection);
24
+ Peer dependencies: `@tuwaio/sdk` (the same release line), `@wagmi/core` (3.x), `viem` (2.x) and `@tuwaio/satellite-core` (>=0.6, a dependency of `@tuwaio/sdk`).
110
25
 
111
- useInitializeTransactionsPool({ initializeTransactionsPool });
112
-
113
- return (
114
- <NTP
115
- transactionsPool={transactionsPool}
116
- initialTx={initialTx}
117
- closeTxTrackedModal={closeTxTrackedModal}
118
- executeTxAction={executeTxAction}
119
- connectedWalletAddress={activeConnection?.isConnected ? activeConnection.address : undefined}
120
- connectedAdapterType={getAdapterFromConnectorType(activeConnection?.connectorType ?? 'evm:')}
121
- adapter={getAdapter()}
122
- />
123
- );
124
- }
125
- ```
26
+ | Import path | Re-exports | Reference |
27
+ | ------------------------------ | -------------------------------------------------- | ----------------------------------------------------------------------------------------- |
28
+ | `@tuwaio/evm-sdk/orbit` | `@tuwaio/orbit-evm` | [orbit.docs.tuwa.io](https://orbit.docs.tuwa.io/packages/orbit-evm) |
29
+ | `@tuwaio/evm-sdk/satellite` | `@tuwaio/satellite-evm` | [satellite.docs.tuwa.io](https://satellite.docs.tuwa.io/packages/satellite-evm) |
30
+ | `@tuwaio/evm-sdk/pulsar` | `@tuwaio/pulsar-evm` | [pulsar.docs.tuwa.io](https://pulsar.docs.tuwa.io/packages/pulsar-evm) |
31
+ | `@tuwaio/evm-sdk/siwx` | `@tuwaio/siwx-evm` | [siwx.docs.tuwa.io](https://siwx.docs.tuwa.io/packages/siwx-evm) |
32
+ | `@tuwaio/evm-sdk/nova-connect` | `@tuwaio/nova-connect/evm` (through `@tuwaio/sdk`) | [Storybook](https://stories.tuwa.io/?path=/docs/packages-nova-connect-evm-overview--docs) |
126
33
 
127
- ### 4. App Providers Layout (`AppProviders.tsx`)
34
+ ---
128
35
 
129
- Assembling the complete EVM layout. The `EVMConnectorsWatcher` runs invisibly in the background to sync Wagmi's state with the unified `SatelliteConnectProvider` store.
36
+ ## 🚀 Usage
130
37
 
131
38
  ```tsx
132
- // src/providers/AppProviders.tsx
133
39
  'use client';
134
40
 
135
- import { SatelliteConnectProvider } from '@tuwaio/sdk/satellite';
136
- import { NovaConnectProvider } from '@tuwaio/sdk/nova-connect';
137
- import { satelliteEVMAdapter } from '@tuwaio/evm-sdk/satellite';
138
41
  import { EVMConnectorsWatcher } from '@tuwaio/evm-sdk/nova-connect';
139
- import { useSiwxSession } from '@tuwaio/sdk/siwx';
140
-
141
- import { appEVMChains, wagmiConfig } from '@/configs/appConfig';
142
- import { usePulsarStore } from '@/hooks/usePulsarStore';
143
- import { NovaTransactionsProvider } from '@/providers/NovaTransactionsProvider';
42
+ import { pulsarEvmAdapter } from '@tuwaio/evm-sdk/pulsar';
43
+ import { createDefaultTransports, satelliteEVMAdapter } from '@tuwaio/evm-sdk/satellite';
44
+ import { NovaConnectProvider } from '@tuwaio/sdk/nova-connect';
45
+ import { createPulsarStore } from '@tuwaio/sdk/pulsar';
46
+ import { SatelliteConnectProvider } from '@tuwaio/sdk/satellite';
47
+ import { createConfig, injected } from '@wagmi/core';
48
+ import type { ReactNode } from 'react';
49
+ import { base, mainnet } from 'viem/chains';
50
+
51
+ const appChains = [mainnet, base] as const;
52
+ const wagmiConfig = createConfig({
53
+ chains: appChains,
54
+ connectors: [injected()],
55
+ transports: createDefaultTransports(appChains),
56
+ });
144
57
 
145
- export function AppProviders({ children }: { children: React.ReactNode }) {
146
- const getAdapter = usePulsarStore((s) => s.getAdapter);
147
- const transactionsPool = usePulsarStore((s) => s.transactionsPool);
148
- const siwxSession = useSiwxSession();
58
+ export const pulsarStore = createPulsarStore({
59
+ name: 'my-app-transactions',
60
+ adapter: [pulsarEvmAdapter(wagmiConfig, appChains)],
61
+ });
149
62
 
63
+ export function Providers({ children }: { children: ReactNode }) {
150
64
  return (
151
- <SatelliteConnectProvider adapter={[satelliteEVMAdapter(wagmiConfig, appEVMChains)]} autoConnect={true}>
152
- <EVMConnectorsWatcher wagmiConfig={wagmiConfig} siwx={siwxSession} />
153
-
154
- <NovaTransactionsProvider />
155
-
156
- <NovaConnectProvider
157
- appChains={appEVMChains}
158
- transactionPool={transactionsPool}
159
- pulsarAdapter={getAdapter()}
160
- withImpersonated
161
- withBalance
162
- withChain
163
- siwx={{
164
- verifier: async (payload) => {
165
- const res = await fetch('/api/siwx/verify', {
166
- method: 'POST',
167
- headers: { 'Content-Type': 'application/json' },
168
- body: JSON.stringify(payload),
169
- });
170
- return res.ok ? res.json() : null;
171
- },
172
- }}
173
- >
174
- {children}
175
- </NovaConnectProvider>
65
+ <SatelliteConnectProvider adapter={satelliteEVMAdapter(wagmiConfig, appChains)} autoConnect>
66
+ <EVMConnectorsWatcher wagmiConfig={wagmiConfig} />
67
+ <NovaConnectProvider appChains={appChains}>{children}</NovaConnectProvider>
176
68
  </SatelliteConnectProvider>
177
69
  );
178
70
  }
179
71
  ```
180
72
 
181
- ### 5. Creating an EVM Transaction (Usage)
182
-
183
- Now you can safely execute strictly-typed transactions anywhere in your app.
184
-
185
- ```tsx
186
- // src/components/SwapButton.tsx
187
- 'use client';
188
-
189
- import { OrbitAdapter } from '@tuwaio/sdk/orbit';
190
- import { useSatelliteConnectStore } from '@tuwaio/sdk/satellite';
191
- import { TxActionButton } from '@tuwaio/sdk/nova-transactions';
192
- import { usePulsarStore } from '@/hooks/usePulsarStore';
193
- import { AppTxType } from '@/types';
194
-
195
- export function SwapButton() {
196
- const executeTxAction = usePulsarStore((s) => s.executeTxAction);
197
- const getLastTxKey = usePulsarStore((s) => s.getLastTxKey);
198
- const transactionsPool = usePulsarStore((s) => s.transactionsPool);
199
- const activeConnection = useSatelliteConnectStore((s) => s.activeConnection);
200
-
201
- const handleSwapAction = async () => {
202
- await executeTxAction({
203
- actionFunction: async () => {
204
- /* your wagmi contract call */
205
- },
206
- params: {
207
- adapter: OrbitAdapter.EVM,
208
- type: AppTxType.SWAP,
209
- title: 'Token Swap',
210
- desiredChainID: 1,
211
- payload: { tokenIn: 'USDC', tokenOut: 'ETH', amount: 100 },
212
- },
213
- });
214
- };
215
-
216
- return (
217
- <TxActionButton
218
- action={handleSwapAction}
219
- getLastTxKey={getLastTxKey}
220
- transactionsPool={transactionsPool}
221
- walletAddress={activeConnection?.address}
222
- >
223
- Execute EVM Swap
224
- </TxActionButton>
225
- );
226
- }
227
- ```
73
+ `createDefaultTransports` uses the public, rate-limited RPC URLs of the viem chains; pass your own transports in production. The complete app, with Solana, Nova Transactions, SIWX and Quasar, is the **[Full-Stack React guide](https://docs.tuwa.io/guides/full-stack-react)**.
228
74
 
229
75
  ---
230
76
 
231
- ## 📦 Available Subpath Exports
77
+ ## 🗄️ Browser Storage
232
78
 
233
- - **`@tuwaio/evm-sdk/satellite`** — EVM Satellite adapter (`satelliteEVMAdapter`, `createEVMConnectionsWatcher`, `checkIsWalletAddressContract`, `impersonated`).
234
- - **`@tuwaio/evm-sdk/pulsar`** — EVM Pulsar adapter (`pulsarEvmAdapter`).
235
- - **`@tuwaio/evm-sdk/orbit`** — EVM Orbit helpers & types.
236
- - **`@tuwaio/evm-sdk/nova-connect`** — EVM React watcher component (`EVMConnectorsWatcher`).
237
- - **`@tuwaio/evm-sdk/siwx`** — EVM CAIP-122 signer adapter (`createEvmSiwxSigner`).
79
+ `@tuwaio/evm-sdk` saves nothing itself. The EVM packages use the `localStorage` keys of Satellite Connect and Pulsar, listed on the [`@tuwaio/sdk`](https://sdk.docs.tuwa.io/packages/sdk) page; `@tuwaio/satellite-evm` reads `satellite-connect:impersonatedAddress` for its `impersonated` development connector.
238
80
 
239
- ---
240
-
241
- ## 🤝 Contributing & Support
81
+ ## 🌐 External Services
242
82
 
243
- Contributions are welcome! Please read our main **[Contribution Guidelines](https://github.com/TuwaIO/workflows/blob/main/CONTRIBUTING.md)**.
83
+ `@tuwaio/evm-sdk` sends no requests itself. The re-exported packages contact the RPC transports of your wagmi config (balances, transaction tracking), the RPC of Ethereum Mainnet for ENS names and avatars, Pimlico or your bundler for ERC-4337 transactions, and the Safe Transaction Service for Safe transactions. Each package page lists the hosts: [satellite-evm](https://satellite.docs.tuwa.io/packages/satellite-evm), [pulsar-evm](https://pulsar.docs.tuwa.io/packages/pulsar-evm), [orbit-evm](https://orbit.docs.tuwa.io/packages/orbit-evm), [siwx-evm](https://siwx.docs.tuwa.io/packages/siwx-evm).
244
84
 
245
- If you find this library useful, please consider supporting its development. Every contribution helps!
246
-
247
- [**➡️ View Support Options**](https://github.com/TuwaIO/workflows/blob/main/Donation.md)
85
+ ---
248
86
 
249
87
  ## 📄 License
250
88
 
251
- This project is licensed under the **Apache-2.0 License** - see the [LICENSE](./LICENSE) file for details.
89
+ Licensed under the **Apache-2.0 License**. See the [LICENSE](https://github.com/TuwaIO/sdk/blob/main/packages/evm-sdk/LICENSE) file for details.
@@ -1 +1 @@
1
- 'use strict';var evm=require('@tuwaio/nova-connect/evm');Object.keys(evm).forEach(function(k){if(k!=='default'&&!Object.prototype.hasOwnProperty.call(exports,k))Object.defineProperty(exports,k,{enumerable:true,get:function(){return evm[k]}})});
1
+ 'use strict';var evm=require('@tuwaio/sdk/nova-connect/evm');Object.keys(evm).forEach(function(k){if(k!=='default'&&!Object.prototype.hasOwnProperty.call(exports,k))Object.defineProperty(exports,k,{enumerable:true,get:function(){return evm[k]}})});
@@ -1,4 +1,4 @@
1
- export * from '@tuwaio/nova-connect/evm';
1
+ export * from '@tuwaio/sdk/nova-connect/evm';
2
2
  import '@tuwaio/orbit-evm';
3
3
  import '@tuwaio/pulsar-evm';
4
4
  import '@tuwaio/satellite-evm';
@@ -1,4 +1,4 @@
1
- export * from '@tuwaio/nova-connect/evm';
1
+ export * from '@tuwaio/sdk/nova-connect/evm';
2
2
  import '@tuwaio/orbit-evm';
3
3
  import '@tuwaio/pulsar-evm';
4
4
  import '@tuwaio/satellite-evm';
@@ -1 +1 @@
1
- export*from'@tuwaio/nova-connect/evm';
1
+ export*from'@tuwaio/sdk/nova-connect/evm';
package/package.json CHANGED
@@ -1,10 +1,10 @@
1
1
  {
2
2
  "name": "@tuwaio/evm-sdk",
3
- "version": "0.1.13",
3
+ "version": "0.2.0",
4
4
  "private": false,
5
5
  "author": "Oleksandr Tkach",
6
6
  "license": "Apache-2.0",
7
- "description": "Layer 9 (L9) of the TUWA Ecosystem. The EVM Network Adapter SDK providing Wagmi/Viem transports, connectors, and SIWX adapters.",
7
+ "description": "Layer 9 (L9) of the TUWA Ecosystem. The EVM add-on of @tuwaio/sdk: re-exports the EVM packages of Orbit, Pulsar, Satellite Connect, SIWX and Nova Connect under subpaths.",
8
8
  "type": "module",
9
9
  "exports": {
10
10
  "./orbit": {
@@ -45,11 +45,8 @@
45
45
  "web3",
46
46
  "evm",
47
47
  "ethereum",
48
- "solana",
49
48
  "wagmi",
50
49
  "viem",
51
- "gill",
52
- "wallet-standard",
53
50
  "wallet",
54
51
  "wallet-connect",
55
52
  "wallets",
@@ -57,29 +54,13 @@
57
54
  "tracking",
58
55
  "transaction-tracking",
59
56
  "react",
60
- "ui",
61
- "ui-kit",
62
- "design-system",
63
57
  "hooks",
64
58
  "utils",
65
- "components",
66
- "tailwind",
67
- "tailwindcss",
68
59
  "typescript",
69
60
  "core",
70
61
  "headless",
71
- "zustand",
72
- "immer",
73
- "i18n",
74
- "modal",
75
- "toast",
76
- "quasar",
77
- "cloud",
78
62
  "sdk",
79
- "next-auth",
80
- "cosmos",
81
- "playground",
82
- "cli"
63
+ "siwx"
83
64
  ],
84
65
  "repository": {
85
66
  "type": "git",
@@ -97,31 +78,28 @@
97
78
  }
98
79
  ],
99
80
  "dependencies": {
100
- "@tuwaio/orbit-evm": "^0.2.22",
101
- "@tuwaio/pulsar-evm": "^0.5.10",
102
- "@tuwaio/satellite-evm": "^0.4.4",
103
- "@tuwaio/siwx-evm": "^0.2.1"
81
+ "@tuwaio/orbit-evm": "^0.3.2",
82
+ "@tuwaio/pulsar-evm": "^0.7.2",
83
+ "@tuwaio/satellite-evm": "^0.6.1",
84
+ "@tuwaio/siwx-evm": "^0.4.1"
104
85
  },
105
86
  "peerDependencies": {
106
- "@tuwaio/nova-connect": "^0.5.11",
107
- "@tuwaio/satellite-core": "^0.4.3",
108
- "@tuwaio/satellite-react": "^0.4.10",
87
+ "@tuwaio/sdk": "^0.2.0",
88
+ "@tuwaio/satellite-core": ">=0.6",
109
89
  "@wagmi/core": "3.x.x",
110
- "viem": "2.x.x",
111
- "@tuwaio/sdk": "^0.1.13"
90
+ "viem": "2.x.x"
112
91
  },
113
92
  "devDependencies": {
114
- "@tuwaio/nova-connect": "^0.5.11",
115
- "@tuwaio/satellite-core": "^0.4.3",
116
- "@tuwaio/satellite-react": "^0.4.10",
117
- "@wagmi/core": "^3.6.4",
93
+ "@tuwaio/satellite-core": "^0.6.2",
94
+ "@tuwaio/sdk": "^0.2.0",
95
+ "@wagmi/core": "^3.6.5",
118
96
  "tsup": "^8.5.1",
119
97
  "typescript": "6.0.3",
120
- "viem": "^2.55.16",
121
- "@tuwaio/sdk": "^0.1.13"
98
+ "viem": "^2.57.1"
122
99
  },
123
100
  "scripts": {
124
101
  "start": "tsup --watch",
125
- "build": "tsup"
102
+ "build": "tsup",
103
+ "test": "vitest run"
126
104
  }
127
105
  }