Skip to content

Commit fb253bc

Browse files
acfunkacfunk
committed
Merge branch 'main' into lute-connect-update
2 parents e3a87c6 + bf1a4fb commit fb253bc

20 files changed

+5313
-0
lines changed

Diff for: ‎docs/README.md

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
description: Easily integrate Algorand wallets in your dApps
3+
---
4+
5+
# Overview
6+
7+
Use-wallet is a comprehensive wallet management solution for Algorand/AVM dApps. It reduces the complexity of wallet integrations, letting developers focus on core application logic.
8+
9+
The library is framework-agnostic and can be used in any modern front-end stack, with official adapters for [React](framework/react.md), [Vue](framework/vue.md), and [SolidJS](framework/solidjs.md).
10+
11+
Version 4.x introduces several major improvements:
12+
13+
* **Algorand SDK v3** - Full support for [Algorand JavaScript SDK](https://github.com/algorand/js-algorand-sdk) v3
14+
* **Runtime Node Configuration** - Let users connect to their private Algorand nodes ([guide](guides/runtime-node-configuration.md))
15+
* **Custom Networks** - Add support for custom network configurations
16+
17+
See the [Migration Guide](guides/migrating-from-v3.x.md) for help upgrading from v3.x.
18+
19+
{% hint style="info" %}
20+
**Looking for v3 docs?** You can find the use-wallet v3.x documentation [here](https://txnlab.gitbook.io/use-wallet/v3).
21+
{% endhint %}
22+
23+
### Links
24+
25+
* [GitHub Repository](https://github.com/TxnLab/use-wallet)
26+
* [Discord Support Channel](https://discord.gg/YkfksmJRrd) (#use-wallet on NFDomains Discord)
27+
28+
{% embed url="https://www.youtube.com/watch?v=DdvrcBdnRCI" %}
29+
Awesome Algorand #22 - Doug Richar: How 'use-wallet' transformed Algorand wallet management
30+
{% endembed %}

Diff for: ‎docs/SUMMARY.md

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Table of contents
2+
3+
## Getting Started
4+
5+
* [Overview](README.md)
6+
* [Installation](getting-started/installation.md)
7+
* [Configuration](getting-started/configuration.md)
8+
* [Supported Wallets](getting-started/supported-wallets.md)
9+
10+
## Framework Adapters <a href="#framework" id="framework"></a>
11+
12+
* [React](framework/react.md)
13+
* [Vue](framework/vue.md)
14+
* [SolidJS](framework/solidjs.md)
15+
16+
## Guides & Concepts <a href="#guides" id="guides"></a>
17+
18+
* [Connect Wallet Menu](guides/connect-wallet-menu.md)
19+
* [Signing Transactions](guides/signing-transactions.md)
20+
* [Switching Networks](guides/switching-networks.md)
21+
* [Runtime Node Configuration](guides/runtime-node-configuration.md)
22+
* [Testing with Mnemonic Wallet](guides/testing-with-mnemonic-wallet.md)
23+
* [Custom Provider](guides/custom-provider.md)
24+
* [Migrating from v3.x](guides/migrating-from-v3.x.md)
25+
26+
## API Reference
27+
28+
* [WalletManager](api-reference/walletmanager.md)
29+
* [useWallet](api-reference/usewallet.md)
30+
* [useNetwork](api-reference/usenetwork.md)
31+
32+
## Resources
33+
34+
* [Example Projects](resources/example-projects.md)
35+
* [AlgoKit Templates](resources/algokit-templates.md)

Diff for: ‎docs/api-reference/usenetwork.md

+222
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,222 @@
1+
---
2+
layout:
3+
title:
4+
visible: true
5+
description:
6+
visible: false
7+
tableOfContents:
8+
visible: true
9+
outline:
10+
visible: true
11+
pagination:
12+
visible: true
13+
---
14+
15+
# useNetwork
16+
17+
The `useNetwork` hook/composable provides access to network-related state and methods from the WalletManager. It enables applications to switch between networks and customize node configurations at runtime.
18+
19+
### Core Functionality
20+
21+
All framework adapters provide access to the same core network state and methods, with framework-specific reactive wrappers.
22+
23+
#### State Properties
24+
25+
```typescript
26+
interface NetworkState {
27+
// Currently active network ID (e.g., 'mainnet', 'testnet')
28+
activeNetwork: string
29+
30+
// Complete network configuration object
31+
networkConfig: Record<string, NetworkConfig>
32+
33+
// Configuration for the currently active network
34+
activeNetworkConfig: NetworkConfig
35+
}
36+
37+
interface NetworkConfig {
38+
// Algod node configuration
39+
algod: {
40+
token: string | algosdk.AlgodTokenHeader | algosdk.CustomTokenHeader
41+
baseServer: string
42+
port?: string | number
43+
headers?: Record<string, string>
44+
}
45+
46+
// Optional network identifiers
47+
genesisHash?: string
48+
genesisId?: string
49+
isTestnet?: boolean
50+
caipChainId?: string
51+
}
52+
```
53+
54+
#### Methods
55+
56+
```typescript
57+
interface NetworkMethods {
58+
// Switch to a different network
59+
setActiveNetwork(networkId: NetworkId | string): Promise<void>
60+
61+
// Update Algod configuration for a specific network
62+
updateAlgodConfig(networkId: string, config: Partial<AlgodConfig>): void
63+
64+
// Reset network configuration to default values
65+
resetNetworkConfig(networkId: string): void
66+
}
67+
```
68+
69+
### Framework-Specific Usage
70+
71+
Each framework adapter provides the same functionality with patterns optimized for that framework's ecosystem.
72+
73+
{% tabs %}
74+
{% tab title="React" %}
75+
```tsx
76+
import { useNetwork } from '@txnlab/use-wallet-react'
77+
78+
function NetworkComponent() {
79+
const {
80+
activeNetwork, // string
81+
networkConfig, // Record<string, NetworkConfig>
82+
activeNetworkConfig, // NetworkConfig
83+
setActiveNetwork, // (networkId: string) => Promise<void>
84+
updateAlgodConfig, // (networkId: string, config: Partial<AlgodConfig>) => void
85+
resetNetworkConfig // (networkId: string) => void
86+
} = useNetwork()
87+
88+
return (
89+
<div>
90+
<div>Current network: {activeNetwork}</div>
91+
<div>Is testnet: {activeNetworkConfig.isTestnet ? 'Yes' : 'No'}</div>
92+
</div>
93+
)
94+
}
95+
```
96+
{% endtab %}
97+
98+
{% tab title="Vue" %}
99+
```typescript
100+
<script setup>
101+
import { useNetwork } from '@txnlab/use-wallet-vue'
102+
103+
const {
104+
activeNetwork, // Ref<string>
105+
networkConfig, // NetworkConfig object
106+
activeNetworkConfig, // ComputedRef<NetworkConfig>
107+
setActiveNetwork, // (networkId: string) => Promise<void>
108+
updateAlgodConfig, // (networkId: string, config: Partial<AlgodConfig>) => void
109+
resetNetworkConfig // (networkId: string) => void
110+
} = useNetwork()
111+
</script>
112+
113+
<template>
114+
<div>
115+
<div>Current network: {{ activeNetwork }}</div>
116+
<div>Is testnet: {{ activeNetworkConfig.isTestnet ? 'Yes' : 'No' }}</div>
117+
</div>
118+
</template>
119+
```
120+
{% endtab %}
121+
122+
{% tab title="Solid" %}
123+
```tsx
124+
import { useNetwork } from '@txnlab/use-wallet-solid'
125+
126+
function NetworkComponent() {
127+
const {
128+
activeNetwork, // () => string
129+
networkConfig, // () => Record<string, NetworkConfig>
130+
activeNetworkConfig, // () => NetworkConfig
131+
setActiveNetwork, // (networkId: string) => Promise<void>
132+
updateAlgodConfig, // (networkId: string, config: Partial<AlgodConfig>) => void
133+
resetNetworkConfig // (networkId: string) => void
134+
} = useNetwork()
135+
136+
return (
137+
<div>
138+
<div>Current network: {activeNetwork()}</div>
139+
<div>Is testnet: {activeNetworkConfig().isTestnet ? 'Yes' : 'No'}</div>
140+
</div>
141+
)
142+
}
143+
```
144+
{% endtab %}
145+
{% endtabs %}
146+
147+
### Method Details
148+
149+
#### setActiveNetwork
150+
151+
```typescript
152+
setActiveNetwork(networkId: NetworkId | string): Promise<void>
153+
```
154+
155+
Switch to a different network. The method:
156+
157+
* Creates a new Algod client for the target network
158+
* Updates the active network in the store
159+
* Persists the selection to local storage
160+
* Maintains active wallet sessions (if supported by the wallet)
161+
162+
Throws an error if the network ID is not found in the configuration.
163+
164+
#### updateAlgodConfig
165+
166+
```typescript
167+
updateAlgodConfig(networkId: string, config: Partial<AlgodConfig>): void
168+
```
169+
170+
Update the Algod client configuration for a specific network. The method:
171+
172+
* Merges the new configuration with existing settings
173+
* Creates a new Algod client if updating the active network
174+
* Persists the configuration to local storage
175+
176+
Configuration options:
177+
178+
```typescript
179+
interface AlgodConfig {
180+
// API token or authentication header
181+
token: string | algosdk.AlgodTokenHeader | algosdk.CustomTokenHeader
182+
183+
// Base URL of the node
184+
baseServer: string
185+
186+
// Optional port number
187+
port?: string | number
188+
189+
// Optional custom headers
190+
headers?: Record<string, string>
191+
}
192+
```
193+
194+
#### resetNetworkConfig
195+
196+
```typescript
197+
resetNetworkConfig(networkId: string): void
198+
```
199+
200+
Reset a network's configuration to its default values. The method:
201+
202+
* Restores the original configuration for the specified network
203+
* Creates a new Algod client if resetting the active network
204+
* Removes any custom configuration from local storage
205+
206+
### Error Handling
207+
208+
The methods may throw errors in these situations:
209+
210+
* Invalid network ID passed to `setActiveNetwork`
211+
* Invalid configuration passed to `updateAlgodConfig`
212+
* Network ID not found in configuration when calling `resetNetworkConfig`
213+
214+
### TypeScript Support
215+
216+
Full type definitions are available for all properties and methods. The types are consistent across frameworks, with framework-specific wrappers where needed (e.g., Vue refs, Solid signals).
217+
218+
### See Also
219+
220+
* [Network Switching Guide](../guides/switching-networks.md) - Detailed guide on network management
221+
* [Runtime Node Configuration](../guides/runtime-node-configuration.md) - Guide for customizing node configurations
222+
* [Configuration](../getting-started/configuration.md#network-configuration) - Network configuration documentation

0 commit comments

Comments
 (0)