@tuwaio/pulsar-evm 0.0.9 → 0.0.11
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 +74 -57
- package/dist/index.d.mts +201 -172
- package/dist/index.d.ts +201 -172
- package/dist/index.js +2 -2
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +2 -2
- package/dist/index.mjs.map +1 -1
- package/package.json +9 -10
package/README.md
CHANGED
|
@@ -4,80 +4,97 @@
|
|
|
4
4
|
[](./LICENSE)
|
|
5
5
|
[](https://github.com/TuwaIO/pulsar-core/actions)
|
|
6
6
|
|
|
7
|
-
An advanced toolkit for the Pulsar Engine that adds support for tracking transactions on EVM-compatible chains. It integrates with Viem
|
|
7
|
+
An advanced toolkit for the Pulsar Engine that adds comprehensive support for tracking transactions on EVM-compatible chains. It integrates seamlessly with **Viem** & **Wagmi** and provides multiple tracking strategies, utility actions, and helpers.
|
|
8
|
+
|
|
9
|
+
---
|
|
8
10
|
|
|
9
11
|
## 🏛️ What is `@tuwaio/pulsar-evm`?
|
|
10
12
|
|
|
11
|
-
This package is a powerful
|
|
13
|
+
This package is a powerful, official adapter for `@tuwaio/pulsar-core`. It contains all the necessary logic to interact with EVM-compatible blockchains, acting as the primary logic provider for most dApps.
|
|
14
|
+
|
|
15
|
+
While its main export is the `evmAdapter`, it also includes a suite of standalone trackers, actions, and utilities that can be used for advanced or custom implementations.
|
|
12
16
|
|
|
13
|
-
|
|
17
|
+
---
|
|
14
18
|
|
|
15
19
|
## ✨ Core Features
|
|
16
20
|
|
|
17
|
-
-
|
|
18
|
-
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
-
|
|
23
|
-
-
|
|
24
|
-
-
|
|
21
|
+
- **🔌 Simple Integration:** A single `evmAdapter` factory function to easily plug full EVM support into `@tuwaio/pulsar-core`.
|
|
22
|
+
- **🎯 Multi-Tracker Support:** Provides distinct, optimized trackers for:
|
|
23
|
+
- **Standard EVM Transactions** (via transaction hash polling `viem`).
|
|
24
|
+
- **Safe (formerly Gnosis Safe)** Multisig Transactions (via the Safe Transaction Service API).
|
|
25
|
+
- **Gelato Relay** Meta-Transactions (via the Gelato API).
|
|
26
|
+
- **🤖 Automatic Routing:** The adapter automatically detects the correct tracker to use (Safe, Gelato, or standard EVM) based on the transaction context and wallet type.
|
|
27
|
+
- **⚡ Built-in Actions:** Includes ready-to-use functions for common user needs like `speedUpTxAction` and `cancelTxAction`.
|
|
28
|
+
- **🛠️ Utility Suite:** Exports a rich set of helpers, including **ENS resolvers** (`getName`, `getAvatar`) and an explorer link generator (`selectEvmTxExplorerLink`).
|
|
29
|
+
|
|
30
|
+
---
|
|
25
31
|
|
|
26
32
|
## 💾 Installation
|
|
27
33
|
|
|
28
|
-
This package is designed to be used as part of the Pulsar stack
|
|
34
|
+
This package is designed to be used as part of the Pulsar stack and requires `wagmi` and `viem`. Install all necessary packages together:
|
|
29
35
|
|
|
30
36
|
```bash
|
|
37
|
+
# Using pnpm
|
|
31
38
|
pnpm add @tuwaio/pulsar-evm @tuwaio/pulsar-core wagmi viem zustand immer
|
|
39
|
+
|
|
40
|
+
# Using npm
|
|
41
|
+
npm install @tuwaio/pulsar-evm @tuwaio/pulsar-core wagmi viem zustand immer
|
|
42
|
+
|
|
43
|
+
# Using yarn
|
|
44
|
+
yarn add @tuwaio/pulsar-evm @tuwaio/pulsar-core wagmi viem zustand immer
|
|
32
45
|
```
|
|
33
46
|
|
|
47
|
+
---
|
|
48
|
+
|
|
34
49
|
## 🚀 Usage
|
|
35
50
|
|
|
36
|
-
### 1
|
|
51
|
+
### 1\. Primary Usage: The `evmAdapter`
|
|
37
52
|
|
|
38
53
|
For most applications, you'll only need to import the `evmAdapter` and pass it to your `createPulsarStore` configuration.
|
|
39
54
|
|
|
40
55
|
```ts
|
|
56
|
+
// src/store/pulsarStore.ts
|
|
41
57
|
import { createPulsarStore } from '@tuwaio/pulsar-core';
|
|
42
58
|
import { evmAdapter } from '@tuwaio/pulsar-evm';
|
|
43
|
-
import {
|
|
44
|
-
import { mainnet, sepolia } from 'wagmi/chains';
|
|
45
|
-
|
|
46
|
-
// 1. Create your Wagmi config
|
|
47
|
-
const wagmiConfig = createConfig({
|
|
48
|
-
chains: [mainnet, sepolia],
|
|
49
|
-
transports: {
|
|
50
|
-
[mainnet.id]: http(),
|
|
51
|
-
[sepolia.id]: http(),
|
|
52
|
-
},
|
|
53
|
-
});
|
|
59
|
+
import { wagmiConfig, chains } from '../configs/wagmi'; // Your wagmi config
|
|
54
60
|
|
|
55
|
-
//
|
|
56
|
-
const pulsarStore = createPulsarStore({
|
|
61
|
+
// Create the Pulsar store and plug in the EVM adapter
|
|
62
|
+
export const pulsarStore = createPulsarStore({
|
|
63
|
+
// A unique name for localStorage persistence
|
|
57
64
|
name: 'my-dapp-transactions',
|
|
58
|
-
|
|
59
|
-
//
|
|
60
|
-
adapters: [
|
|
61
|
-
|
|
62
|
-
|
|
65
|
+
|
|
66
|
+
// Provide the evmAdapter with your wagmi config and supported chains
|
|
67
|
+
adapters: [evmAdapter(wagmiConfig, chains)],
|
|
68
|
+
|
|
69
|
+
// Optional: Add global callbacks for all successful transactions
|
|
70
|
+
onSucceedCallbacks: (tx) => {
|
|
71
|
+
console.log(`Transaction ${tx.txKey} succeeded on chain ${tx.chainId}!`);
|
|
72
|
+
// Example: show a success toast
|
|
73
|
+
},
|
|
63
74
|
});
|
|
64
75
|
```
|
|
65
76
|
|
|
66
|
-
### 2
|
|
77
|
+
### 2\. Using Standalone Actions
|
|
67
78
|
|
|
68
|
-
This package also exports utility actions that you can wire up to your UI.
|
|
79
|
+
This package also exports utility actions that you can wire up to your UI for features like speeding up or canceling transactions.
|
|
69
80
|
|
|
70
|
-
**Example:
|
|
81
|
+
**Example: A button to speed up a stuck transaction**
|
|
71
82
|
|
|
72
83
|
```tsx
|
|
84
|
+
// src/components/SpeedUpButton.tsx
|
|
73
85
|
import { speedUpTxAction } from '@tuwaio/pulsar-evm';
|
|
74
86
|
import { usePulsar } from '@tuwaio/pulsar-react'; // Or your custom hook
|
|
75
|
-
import { wagmiConfig } from '
|
|
87
|
+
import { wagmiConfig } from '../configs/wagmi'; // Your wagmi config
|
|
76
88
|
|
|
77
|
-
function
|
|
89
|
+
function SpeedUpButton({ txKey }) {
|
|
78
90
|
const { transactionsPool } = usePulsar();
|
|
79
91
|
const stuckTransaction = transactionsPool[txKey];
|
|
80
92
|
|
|
93
|
+
// Only show the button if the transaction is pending and is a standard EVM tx
|
|
94
|
+
if (!stuckTransaction?.pending || stuckTransaction.tracker !== 'ethereum') {
|
|
95
|
+
return null;
|
|
96
|
+
}
|
|
97
|
+
|
|
81
98
|
const handleSpeedUp = async () => {
|
|
82
99
|
try {
|
|
83
100
|
const newTxHash = await speedUpTxAction({
|
|
@@ -85,50 +102,50 @@ function TransactionDetails({ txKey }) {
|
|
|
85
102
|
tx: stuckTransaction,
|
|
86
103
|
});
|
|
87
104
|
console.log('Transaction sped up with new hash:', newTxHash);
|
|
88
|
-
// Pulsar will automatically track this new transaction
|
|
105
|
+
// Pulsar's `handleTransaction` will automatically add and track this new transaction
|
|
106
|
+
// if you integrate it with the action that calls this.
|
|
89
107
|
} catch (error) {
|
|
90
108
|
console.error('Failed to speed up transaction:', error);
|
|
91
109
|
}
|
|
92
110
|
};
|
|
93
111
|
|
|
94
|
-
return
|
|
95
|
-
<div>
|
|
96
|
-
{/* ... your component UI ... */}
|
|
97
|
-
<button onClick={handleSpeedUp}>Speed Up</button>
|
|
98
|
-
</div>
|
|
99
|
-
);
|
|
112
|
+
return <button onClick={handleSpeedUp}>Speed Up</button>;
|
|
100
113
|
}
|
|
101
114
|
```
|
|
102
115
|
|
|
103
|
-
### 3
|
|
116
|
+
### 3\. Using Standalone Utilities
|
|
104
117
|
|
|
105
|
-
You can use exported utilities, like selectors, to get derived data.
|
|
118
|
+
You can use exported utilities, like selectors, to get derived data for your UI.
|
|
106
119
|
|
|
107
|
-
**Example: Getting a block explorer link**
|
|
120
|
+
**Example: Getting a block explorer link for a transaction**
|
|
108
121
|
|
|
109
122
|
```tsx
|
|
123
|
+
// src/components/ExplorerLink.tsx
|
|
110
124
|
import { selectEvmTxExplorerLink } from '@tuwaio/pulsar-evm';
|
|
111
125
|
import { usePulsar } from '@tuwaio/pulsar-react';
|
|
112
126
|
import { mainnet, sepolia } from 'viem/chains';
|
|
113
127
|
|
|
114
|
-
function
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
[mainnet, sepolia], // Your app's chains
|
|
119
|
-
txKey
|
|
120
|
-
);
|
|
128
|
+
function ExplorerLink({ txKey }) {
|
|
129
|
+
const { transactionsPool } = usePulsar();
|
|
130
|
+
// The selector needs the pool, your app's chains, and the transaction key.
|
|
131
|
+
const explorerLink = selectEvmTxExplorerLink(transactionsPool, [mainnet, sepolia], txKey);
|
|
121
132
|
|
|
122
|
-
|
|
133
|
+
if (!explorerLink) return null;
|
|
123
134
|
|
|
124
|
-
|
|
135
|
+
return (
|
|
136
|
+
<a href={explorerLink} target="_blank" rel="noopener noreferrer">
|
|
137
|
+
View on Explorer
|
|
138
|
+
</a>
|
|
139
|
+
);
|
|
125
140
|
}
|
|
126
141
|
```
|
|
127
142
|
|
|
143
|
+
---
|
|
144
|
+
|
|
128
145
|
## 🤝 Contributing
|
|
129
146
|
|
|
130
|
-
Contributions are welcome
|
|
147
|
+
Contributions are welcome\! Please read our main **[Contribution Guidelines](https://github.com/TuwaIO/workflows/blob/main/CONTRIBUTING.md)**.
|
|
131
148
|
|
|
132
149
|
## 📄 License
|
|
133
150
|
|
|
134
|
-
This project is licensed under the **Apache-2.0 License
|
|
151
|
+
This project is licensed under the **Apache-2.0 License** - see the [LICENSE](./LICENSE) file for details.
|