Skip to content

Commit 5995d16

Browse files
feruzmferuzm
committed
wallets package changes
1 parent fbdcb43 commit 5995d16

2 files changed

Lines changed: 205 additions & 88 deletions

File tree

‎src/content/docs/developers/wallets.mdx‎

Lines changed: 142 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -5,79 +5,155 @@ title: Ecency wallets
55
import { Code } from "@astrojs/starlight/components";
66
import { Aside } from "@astrojs/starlight/components";
77

8-
Ecency wallets replaces the older Ecency SDK experience and focuses purely on
9-
wallet-related operations across the Ecency website and mobile app. The new
10-
`@ecency/wallets` package gives us a single, dedicated layer for creating and
11-
managing wallets while keeping the rest of the Ecency stack lightweight.
12-
13-
## Multi-chain addresses
14-
15-
<Aside type="caution">
16-
The seed-phrase-based wallet creation flow is being discontinued. Managing
17-
a separate seed phrase added complexity to signups and transaction signing.
18-
Ecency is integrating **MetaMask** to handle external chain wallets instead.
19-
If your application generated wallets using the mnemonic flow described below,
20-
guide users to the [seed phrase migration guide](/guides/seed-phrase-migration/)
21-
so they can move funds to an external wallet.
22-
</Aside>
8+
The `@ecency/wallets` package (v2.0) provides wallet-related queries, MetaMask
9+
integration utilities, and Hive key derivation for the Ecency web and mobile apps.
10+
11+
## What's in v2.0
12+
13+
Version 2.0 is a major cleanup that removes seed-phrase-based wallet creation
14+
and replaces external chain signing with MetaMask. The package is now
15+
significantly smaller (~37 KB vs ~131 KB in v1.x) after dropping all `@okxweb3`
16+
dependencies.
17+
18+
### Kept
19+
20+
- **External wallet balance queries** — fetch balances for BTC, ETH, BNB, SOL
21+
from the Ecency private API.
22+
- **Token price queries** — market data for supported currencies.
23+
- **Hive key derivation** — `deriveHiveKeys()` (BIP44) and
24+
`deriveHiveMasterPasswordKeys()` for login and permissions flows.
25+
- **Wallet metadata** — save/read external wallet addresses from Hive account
26+
`posting_json_metadata`.
27+
- **Private API mutations** — create accounts with wallets, update wallet info,
28+
check wallet existence.
29+
30+
### Added
31+
32+
- **MetaMask multichain discovery** — `discoverMetaMaskWallets()`,
33+
`fetchMultichainAddresses()`, `fetchEvmAddress()` discover ETH, BNB, SOL,
34+
BTC addresses from MetaMask via `window.ethereum` and the Wallet Standard
35+
protocol.
36+
- **Hive Snap utilities** — `installHiveSnap()` and `getHivePublicKeys()`
37+
interact with the `@hiveio/metamask-snap` for Hive key management inside
38+
MetaMask.
39+
- **EVM transfers** — `sendEvmTransfer()`, `ensureEvmChain()`,
40+
`estimateEvmGas()`, `parseToWei()`, `formatWei()` for sending ETH/BNB via
41+
MetaMask's `eth_sendTransaction`.
42+
- **SOL transfers** — `sendSolTransfer()`, `parseToLamports()`,
43+
`formatLamports()` for sending SOL via MetaMask's Wallet Standard
44+
`solana:signAndSendTransaction` feature.
45+
- **Transfer mutation hook** — `useExternalTransfer(currency)` React Query
46+
mutation that routes to the correct chain signing method.
47+
48+
### Removed
49+
50+
- Mnemonic/seed phrase generation (`useSeedPhrase`, `mnemonicToSeedBip39`)
51+
- okxweb3 wallet factory and signing (`getWallet`, `signExternalTx`,
52+
`buildExternalTx`)
53+
- Seed-based wallet creation (`useWalletCreate`, `useImportWallet`,
54+
`getKeysFromSeed`)
55+
- Hive keys from seed query (`useHiveKeysQuery`)
56+
- Wallets cache query (`useWalletsCacheQuery`)
57+
- Memo encryption/decryption (`encryptMemo`, `decryptMemo`)
58+
- Direct Hive transaction signing (`signTx`, `signDigest`)
59+
- TRON, TON, APT currencies and their balance/info queries
60+
61+
### Supported currencies
62+
63+
| Currency | Balance query | Transfer (MetaMask) | Notes |
64+
|----------|:---:|:---:|-------|
65+
| BTC | Yes | No | MetaMask BTC support coming soon |
66+
| ETH | Yes | Yes | Via `eth_sendTransaction` |
67+
| BNB | Yes | Yes | Via `eth_sendTransaction` + chain switch |
68+
| SOL | Yes | Yes | Via Wallet Standard `signAndSendTransaction` |
69+
70+
## Installation
71+
72+
```bash
73+
pnpm add @ecency/wallets
74+
```
75+
76+
Peer dependencies:
77+
78+
```json
79+
{
80+
"@ecency/sdk": "workspace:*",
81+
"@hiveio/dhive": "^1.3.5",
82+
"hivesigner": "^3.3.4",
83+
"react": ">=18",
84+
"@tanstack/react-query": ">=5",
85+
"@wallet-standard/app": ">=1",
86+
"@solana/web3.js": ">=1"
87+
}
88+
```
89+
90+
`@wallet-standard/app` and `@solana/web3.js` are optional — only needed if
91+
using MetaMask multichain discovery or SOL transfers.
92+
93+
## Example: MetaMask wallet discovery
94+
95+
export const discoveryCode = `
96+
import {
97+
discoverMetaMaskWallets,
98+
installHiveSnap,
99+
getHivePublicKeys
100+
} from '@ecency/wallets';
101+
102+
// Discover ETH, BNB, SOL, BTC addresses from MetaMask
103+
const addresses = await discoverMetaMaskWallets();
104+
// { ETH: "0x...", BNB: "0x...", SOL: "7xyz...", BTC: "bc1..." }
105+
106+
// Install the Hive Snap and get Hive public keys
107+
await installHiveSnap();
108+
const hiveKeys = await getHivePublicKeys();
109+
// [{ publicKey: "STM...", role: "owner" }, ...]
110+
`;
111+
export const discoveryFileName = "discovery.ts";
23112

24-
The `@ecency/wallets` package previously used a blockchain-standard seed phrase
25-
to derive wallet addresses across different blockchains. A single mnemonic
26-
could:
113+
<Code code={discoveryCode} lang="ts" title={discoveryFileName} />
27114

28-
1. Generate addresses for multiple supported chains without asking the user to
29-
juggle several keys.
30-
2. Keep derivation compatible with common wallet tooling, so the same seed can
31-
be recovered in other BIP39-style wallets.
32-
3. Sync addresses between web and mobile clients while still letting each
33-
client enforce its own encryption and secure storage policies.
115+
## Example: send ETH via MetaMask
34116

35-
<Aside type="note">
36-
The seed phrase never left the client. When a wallet needed to be backed up
37-
or restored, the mnemonic was provided by the user, and derived addresses were
38-
synced to Ecency services only after local encryption was applied.
39-
</Aside>
117+
export const transferCode = `
118+
import { useExternalTransfer, EcencyWalletCurrency } from '@ecency/wallets';
40119
41-
## What `@ecency/wallets` handles
120+
function SendEthButton() {
121+
const transfer = useExternalTransfer(EcencyWalletCurrency.ETH);
42122
43-
`@ecency/wallets` is scoped to wallet functionality so the rest of the Ecency
44-
codebase can stay focused on social and content features. The package is
45-
responsible for:
123+
const handleSend = async () => {
124+
const result = await transfer.mutateAsync({
125+
to: "0xRecipientAddress...",
126+
amount: "0.05"
127+
});
128+
console.log("Tx hash:", result.txHash);
129+
};
46130
47-
- Generating or importing the mnemonic that seeds all derived addresses.
48-
- Deriving per-chain addresses from the same seed phrase, so Ecency can surface
49-
balances and transactions for multiple blockchains.
50-
- Publishing public wallet metadata to Ecency services when users choose to
51-
make their addresses available.
131+
return <button onClick={handleSend}>Send 0.05 ETH</button>;
132+
}
133+
`;
134+
export const transferFileName = "send-eth.tsx";
52135

53-
## Example: derive addresses from a mnemonic (legacy)
136+
<Code code={transferCode} lang="tsx" title={transferFileName} />
54137

55-
<Aside type="caution">
56-
This mnemonic-based flow is being phased out. The example below is kept for
57-
reference only. New integrations should not rely on seed phrase generation.
138+
<Aside type="note">
139+
MetaMask handles gas estimation, signing, and broadcasting. The user sees
140+
the standard MetaMask confirmation popup. For SOL, the Wallet Standard
141+
protocol is used instead of `window.ethereum`.
58142
</Aside>
59143

60-
The snippet below shows the legacy flow for creating a mnemonic and deriving a
61-
set of addresses.
62-
63-
export const exampleCode = `
64-
import { createWalletClient } from '@ecency/wallets';
65-
66-
// Create a client for wallet-only operations in web or mobile apps
67-
const walletClient = createWalletClient();
68-
69-
// Either generate or import a mnemonic
70-
const mnemonic = await walletClient.createMnemonic();
71-
72-
// Derive addresses for the chains you need to display in Ecency
73-
const addresses = await walletClient.deriveAddresses({
74-
mnemonic,
75-
chains: ['hive', 'bitcoin', 'ethereum'],
76-
});
77-
78-
// Store only public addresses with Ecency services; keep the mnemonic local
79-
await walletClient.publishPublicWallets({ addresses });
80-
`;
81-
export const fileName = "wallets.ts";
82-
83-
<Code code={exampleCode} lang="ts" title={fileName} />
144+
## Migration from v1.x
145+
146+
If you were using the seed-phrase-based wallet creation flow:
147+
148+
1. Remove imports of `useSeedPhrase`, `useWalletCreate`, `useImportWallet`,
149+
`getKeysFromSeed`, `useHiveKeysQuery`, `useWalletsCacheQuery`.
150+
2. Remove imports of `signExternalTx`, `buildExternalTx`, `getWallet`.
151+
3. Remove `@okxweb3/*` and `bip39` from your dependencies (they are no longer
152+
needed by the wallets package).
153+
4. For external chain transfers, use `useExternalTransfer()` which signs via
154+
MetaMask.
155+
5. For Hive key derivation from seed, `deriveHiveKeys()` and
156+
`deriveHiveMasterPasswordKeys()` still work as before — the only change is
157+
the BIP32 library switched from `@okxweb3/crypto-lib` to `@scure/bip32`.
158+
6. Guide users with existing seed-phrase wallets to the
159+
[seed phrase migration guide](/guides/seed-phrase-migration/).

‎src/content/docs/ecency/wallets/cross-chain-wallets.md‎

Lines changed: 63 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,47 +1,88 @@
11
---
22
title: Cross-chain wallets
3-
description: Manage BTC, ETH, BNB, SOL, APT, TRX, and TON wallets alongside your Hive balances in Ecency.
3+
description: Manage ETH, BNB, SOL, and BTC wallets alongside your Hive balances in Ecency using MetaMask.
44
---
55

66
# Cross-chain wallets
77

8-
Ecency supports lightweight, self-custodied wallets for **BTC**, **ETH**, **BNB**, **SOL**, **APT**, **TRX**, and **TON** so you can monitor and transfer multi-chain assets next to your Hive balances.
8+
Ecency supports external wallets for **BTC**, **ETH**, **BNB**, and **SOL** so you can monitor balances and send transfers next to your Hive assets.
99

10-
> **Migration notice:** Ecency previously generated seed phrases for cross-chain wallets. To simplify the signup flow and reduce complexity around seed security and transaction signing, Ecency is integrating **MetaMask** to handle external chain wallets. If you have funds in a wallet created with a seed phrase, see the [seed phrase migration guide](/guides/seed-phrase-migration/) to move them.
10+
> **What changed:** Ecency previously supported TRON, TON, and APT wallets and used seed phrases to generate addresses. The wallet system now uses **MetaMask** for address discovery, key management, and transaction signing. If you have funds in a wallet created with a seed phrase, see the [seed phrase migration guide](/guides/seed-phrase-migration/) to move them to an external wallet.
1111
1212
---
1313

14-
## Cross-chain addresses
14+
## Setting up external wallets
1515

16-
1. Open **Wallet → Tokens** in the Ecency web or mobile app.
17-
2. Scroll to the **External chain tokens** section.
18-
3. Select the chain (BTC, ETH, BNB, SOL, APT, TRX, TON) to view or manage your address.
16+
There are two ways to add external wallet addresses to your Ecency account:
1917

20-
> Cross-chain wallet structure is being upgraded. Addresses are associated with your Hive account for convenience, and you remain in control of the keys.
18+
### Link MetaMask (recommended)
19+
20+
1. Go to **Wallet** and click **Setup External Wallets**.
21+
2. Choose **Link MetaMask**.
22+
3. MetaMask will discover your ETH, BNB, and SOL addresses automatically.
23+
4. The Hive Snap is installed to derive Hive keys inside MetaMask, enabling MetaMask login.
24+
5. Your wallet addresses are stored in your Hive account metadata.
25+
26+
After linking, you can **send ETH, BNB, and SOL** directly from your wallet page — MetaMask handles signing.
27+
28+
### Watch Wallet (view-only)
29+
30+
1. Go to **Wallet** and click **Setup External Wallets**.
31+
2. Choose **Watch Wallet**.
32+
3. Enter wallet addresses manually for any supported chain.
33+
4. Balances are displayed but **transfers are not available** — this is view-only.
2134

2235
---
2336

24-
## Deposits and withdrawals
37+
## Sending transfers
2538

26-
- **Deposits**: Send assets directly to your address. Confirm network fees and memo requirements (if any) for that chain.
27-
- **Withdrawals**: Use the **Send/Transfer** action inside the token panel, confirm the destination address, and sign with the required key or device.
28-
- **Fees**: Network fees vary by chain and are displayed before submitting the transaction.
39+
Transfer support requires MetaMask-linked wallets. From your wallet page:
40+
41+
1. Navigate to the token page (e.g., **/@you/wallet/eth**).
42+
2. Click **Send**.
43+
3. Enter the recipient address and amount.
44+
4. Review the transaction details and estimated network fee.
45+
5. Click **Confirm with MetaMask** — MetaMask shows its signing popup.
46+
6. Once confirmed, the transaction is broadcast to the network.
47+
48+
| Chain | Transfer support | Signing method |
49+
|-------|:---:|-------|
50+
| **ETH** | Yes | MetaMask `eth_sendTransaction` |
51+
| **BNB** | Yes | MetaMask `eth_sendTransaction` + chain switch |
52+
| **SOL** | Yes | MetaMask Wallet Standard |
53+
| **BTC** | Coming soon | — |
54+
55+
> **Watch-only wallets** do not support transfers. You need to link MetaMask to send tokens.
2956
3057
---
3158

32-
## Security tips
59+
## Receiving tokens
3360

34-
- If you were previously given a **seed phrase**, keep it safe - you may need it to [migrate funds](/guides/seed-phrase-migration/) to an external wallet.
35-
- Start with low-value test transfers, especially on faster chains like SOL or TRX.
36-
- Avoid pasting addresses from untrusted sources; verify QR codes or manually check checksums.
37-
- Keep your device updated and avoid transacting on public Wi‑Fi.
61+
All wallet types (MetaMask-linked and watch-only) support receiving:
62+
63+
1. Navigate to your token page.
64+
2. Click **Receive** to see your address and QR code.
65+
3. Share the address or QR with the sender.
3866

3967
---
4068

41-
## When to use cross-chain wallets
69+
## Login to mobile app
70+
71+
MetaMask users can transfer their web session to the Ecency mobile app:
72+
73+
1. Open the user menu and click **Log in to Mobile**.
74+
2. Read the security warning and click **Reveal QR code**.
75+
3. Open the Ecency mobile app and tap the QR scanner.
76+
4. Scan the QR code — you're logged in on mobile.
77+
78+
> The QR code contains your session credentials. Do not share it, screenshot it, or scan it in public spaces.
4279
43-
- Consolidate **on-chain tips or payments** from other platforms without leaving Ecency.
44-
- Track multiple chains while focusing on Hive content.
45-
- Move value between chains before trading or staking elsewhere.
80+
---
81+
82+
## Security tips
4683

47-
For full wallet capabilities (staking, swapping, hardware wallet support), you may still use dedicated wallets and then deposit or withdraw through Ecency-managed addresses.
84+
- MetaMask handles all private key storage — Ecency never sees your external chain keys.
85+
- Start with small test transfers, especially on chains you haven't used before.
86+
- Verify recipient addresses carefully — blockchain transactions are irreversible.
87+
- Keep MetaMask and your browser updated.
88+
- If you were previously given a **seed phrase**, keep it safe until you have [migrated all funds](/guides/seed-phrase-migration/).

0 commit comments

Comments
 (0)