Skip to content

Commit 4ea38d6

Browse files
samsiegartsamsiegart
committed
chore: update readmes and address feedback
1 parent ce1099d commit 4ea38d6

File tree

8 files changed

+243
-250
lines changed

8 files changed

+243
-250
lines changed

‎packages/example/README.md‎

Lines changed: 167 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,183 @@
1-
This is an Interchain App project bootstrapped with [`create-interchain-app`](https://github.com/hyperweb-io/create-interchain-app).
1+
# Agoric React Components Example
2+
3+
This is a complete example application built with Vite that demonstrates how to integrate and use the `@agoric/react-components` package. It showcases wallet connection, smart wallet provisioning, and purse management functionality.
4+
5+
## Overview
6+
7+
This example app provides a practical implementation of:
8+
9+
- **Wallet Connection**: Connecting to Keplr wallet and managing offline signers
10+
- **Smart Wallet Provisioning**: Handling smart wallet setup and fees
11+
- **Purse Management**: Displaying and managing different asset purses
12+
- **Agoric Integration**: Using the Agoric React Components ecosystem
13+
14+
## Prerequisites
15+
16+
- Node.js (v20 or higher)
17+
- Yarn package manager
18+
- Keplr wallet browser extension
19+
- Access to Agoric devnet
220

321
## Getting Started
422

5-
First, install the packages and run the development server:
23+
### 1. Install Dependencies
24+
25+
From the root of the ui-kit repository:
626

727
```bash
8-
yarn install && yarn dev
28+
yarn install
29+
```
30+
31+
### 2. Build Dependencies
32+
33+
From the root of the ui-kit repository:
34+
35+
```bash
36+
yarn prepack
37+
```
38+
39+
### 3. Run the Example
40+
41+
```bash
42+
cd packages/example
43+
yarn dev
44+
```
45+
46+
The application will be available at `http://localhost:5173`
47+
48+
### 4. Build for Production
49+
50+
```bash
51+
yarn build
52+
yarn preview
53+
```
54+
55+
## Key Features
56+
57+
### Wallet Connection
58+
59+
- **Automatic Connection**: The app automatically attempts to connect to Keplr on load
60+
- **Manual Connection**: Users can manually connect via the "Connect Keplr" button
61+
- **Type Safety**: Uses `@keplr-wallet/types` for proper TypeScript support
62+
63+
### Smart Wallet Provisioning
64+
65+
- **Provision Status**: Displays whether the user's smart wallet is provisioned
66+
- **Fee Display**: Shows the BLD fee required for provisioning
67+
- **Faucet Link**: Provides a link to the Agoric devnet faucet for getting BLD
68+
- **One-Click Provisioning**: Allows users to provision their smart wallet with a single click
69+
70+
### Purse Management
71+
72+
- **Asset Display**: Shows all available purses with their balances
73+
- **Amount Formatting**: Properly formats amounts using the asset's decimal places
74+
- **Real-time Updates**: Purses update automatically as the wallet state changes
75+
76+
## Code Structure
77+
78+
### Key Files
79+
80+
- **`src/App.tsx`**: Main application component with AgoricProvider setup
81+
- **`src/hooks/useWalletManager.ts`**: Custom hook for wallet connection logic
82+
- **`src/components/WalletDetails.tsx`**: Component displaying wallet information and controls
83+
- **`src/utils/constants.ts`**: Network configuration and constants
84+
- **`src/types/global.d.ts`**: TypeScript declarations for Keplr wallet
85+
86+
### Key Components
87+
88+
#### AgoricProvider Setup
89+
90+
```tsx
91+
<AgoricProvider
92+
restEndpoint={REST_ENDPOINT}
93+
rpcEndpoint={RPC_ENDPOINT}
94+
offlineSigner={offlineSigner}
95+
address={address}
96+
chainName={CHAIN_ID}
97+
>
98+
{/* Your app components */}
99+
</AgoricProvider>
100+
```
101+
102+
#### Wallet Connection Hook
103+
104+
```tsx
105+
const { address, connectWallet, offlineSigner } = useWalletManager();
106+
```
107+
108+
#### Agoric Context Usage
109+
110+
```tsx
111+
const {
112+
isSmartWalletProvisioned,
113+
purses,
114+
address,
115+
provisionSmartWallet,
116+
smartWalletProvisionFee,
117+
} = useAgoric();
9118
```
10119

11-
Open [http://localhost:5173](http://localhost:5173) with your browser to see the result.
120+
## Configuration
121+
122+
### Network Settings
123+
124+
The app is configured for Agoric devnet by default. Key settings in `src/utils/constants.ts`:
125+
126+
- **Chain ID**: `agoricdev-25`
127+
- **RPC Endpoint**: `https://devnet.rpc.agoric.net:443`
128+
- **REST Endpoint**: `https://devnet.api.agoric.net`
129+
- **Network Config**: `https://devnet.agoric.net/network-config`
130+
131+
### Vite Configuration
132+
133+
The app includes Node.js polyfills for browser compatibility:
134+
135+
- Buffer polyfill for crypto operations
136+
- Process polyfill for development
137+
- Proper handling of Node.js modules in the browser
138+
139+
## Development
140+
141+
### Available Scripts
142+
143+
- **`yarn dev`**: Start development server with hot reload
144+
- **`yarn build`**: Build for production
145+
- **`yarn preview`**: Preview production build
146+
- **`yarn lint`**: Run ESLint
147+
148+
### TypeScript Support
149+
150+
The example includes comprehensive TypeScript support:
151+
152+
- Keplr wallet types via `@keplr-wallet/types`
153+
- Global type declarations for `window.keplr`
154+
- Proper typing for all Agoric components and hooks
155+
156+
## Troubleshooting
12157

13-
You can start editing the page by modifying `src/App.tsx`. The page auto-updates as you edit the file.
158+
### Common Issues
14159

15-
## Interchain JavaScript Stack
160+
1. **"Buffer is not defined"**: Ensure Node.js polyfills are properly configured in Vite
161+
2. **"Please install Keplr extension"**: Install the Keplr wallet browser extension
162+
3. **Connection failures**: Check that you're on the correct network (Agoric devnet)
163+
4. **Build errors**: Ensure all dependencies are built (`yarn build` in react-components)
16164

17-
A unified toolkit for building applications and smart contracts in the Interchain ecosystem ⚛️
165+
### Getting BLD for Testing
18166

19-
| Category | Tools | Description |
20-
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
21-
| **Chain Information** | [**Chain Registry**](https://github.com/hyperweb-io/chain-registry), [**Utils**](https://www.npmjs.com/package/@chain-registry/utils), [**Client**](https://www.npmjs.com/package/@chain-registry/client) | Everything from token symbols, logos, and IBC denominations for all assets you want to support in your application. |
22-
| **Wallet Connectors** | [**Interchain Kit**](https://github.com/hyperweb-io/interchain-kit)<sup>beta</sup>, [**Cosmos Kit**](https://github.com/hyperweb.io/cosmos-kit) | Experience the convenience of connecting with a variety of web3 wallets through a single, streamlined interface. |
23-
| **Signing Clients** | [**InterchainJS**](https://github.com/hyperweb-io/interchainjs)<sup>beta</sup>, [**CosmJS**](https://github.com/cosmos/cosmjs) | A single, universal signing interface for any network |
24-
| **SDK Clients** | [**Telescope**](https://github.com/hyperweb.io/telescope) | Your Frontend Companion for Building with TypeScript with Cosmos SDK Modules. |
25-
| **Starter Kits** | [**Create Interchain App**](https://github.com/hyperweb-io/create-interchain-app)<sup>beta</sup>, [**Create Cosmos App**](https://github.com/hyperweb.io/create-cosmos-app) | Set up a modern Interchain app by running one command. |
26-
| **UI Kits** | [**Interchain UI**](https://github.com/hyperweb.io/interchain-ui) | The Interchain Design System, empowering developers with a flexible, easy-to-use UI kit. |
27-
| **Testing Frameworks** | [**Starship**](https://github.com/hyperweb.io/starship) | Unified Testing and Development for the Interchain. |
28-
| **TypeScript Smart Contracts** | [**Create Hyperweb App**](https://github.com/hyperweb-io/create-hyperweb-app) | Build and deploy full-stack blockchain applications with TypeScript |
29-
| **CosmWasm Contracts** | [**CosmWasm TS Codegen**](https://github.com/CosmWasm/ts-codegen) | Convert your CosmWasm smart contracts into dev-friendly TypeScript classes. |
167+
Use the Agoric devnet faucet: https://devnet.faucet.agoric.net/
30168

31-
## Credits
169+
## Learn More
32170

33-
🛠 Built by Hyperweb (formerly Cosmology) — if you like our tools, please checkout and contribute to [our github ⚛️](https://github.com/hyperweb-io)
171+
- [Agoric React Components Documentation](../react-components/README.md)
172+
- [Agoric Web Components](../web-components/README.md)
173+
- [Agoric RPC Package](../rpc/README.md)
174+
- [Agoric Documentation](https://docs.agoric.com/)
34175

35-
## Disclaimer
176+
## Contributing
36177

37-
AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED “AS IS”, AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
178+
This example serves as a reference implementation. When making changes:
38179

39-
No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.
180+
1. Ensure the example still works end-to-end
181+
2. Update this README if functionality changes
182+
3. Test both development and production builds
183+
4. Verify TypeScript compilation passes

‎packages/example/package.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"name": "@agoric/ui-kit-example",
2+
"name": "example",
33
"private": true,
44
"version": "0.0.1",
55
"type": "module",
@@ -28,7 +28,7 @@
2828
"eslint-plugin-react-hooks": "^5.1.0-rc.0",
2929
"eslint-plugin-react-refresh": "^0.4.11",
3030
"globals": "^15.9.0",
31-
"typescript": "^5.5.3",
31+
"typescript": "~5.9.2",
3232
"typescript-eslint": "^8.3.0",
3333
"vite": "^5.4.2",
3434
"vite-plugin-node-polyfills": "^0.24.0"

‎packages/example/src/components/WalletDetails.tsx‎

Lines changed: 14 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -18,19 +18,20 @@ const WalletDetails = () => {
1818
<div>
1919
<p>
2020
Purses:{' '}
21-
{purses
22-
?.map(
23-
// eslint-disable-next-line @typescript-eslint/no-explicit-any
24-
(p: PurseJSONState<any>) =>
25-
p.brandPetname +
26-
': ' +
27-
stringifyAmountValue(
28-
p.currentAmount,
29-
p.displayInfo.assetKind,
30-
p.displayInfo.decimalPlaces,
31-
),
32-
)
33-
.join(', ') ?? 'Loading...'}
21+
{purses?.length
22+
? purses
23+
.map(
24+
(p: PurseJSONState<'nat' | 'copyBag' | 'set' | 'copySet'>) =>
25+
p.brandPetname +
26+
': ' +
27+
stringifyAmountValue(
28+
p.currentAmount,
29+
p.displayInfo.assetKind,
30+
p.displayInfo.decimalPlaces,
31+
),
32+
)
33+
.join(', ')
34+
: 'Loading...'}
3435
</p>
3536
</div>
3637
<div style={{ display: 'flex', alignItems: 'center' }}></div>

‎packages/example/src/hooks/useWalletManager.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,11 @@ export const useWalletManager = () => {
99
undefined,
1010
);
1111

12+
/**
13+
* Connects with keplr.
14+
*
15+
* See: https://docs.keplr.app/api/use-with/cosmjs#connecting-keplr-with-cosmjs
16+
*/
1217
const connectWallet = useCallback(async () => {
1318
try {
1419
if (!window.keplr) {

‎packages/example/vite.config.ts‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,6 @@ export default defineConfig({
2828
),
2929
},
3030
optimizeDeps: {
31-
include: ['@interchain-kit/core', '@interchain-kit/keplr-extension'],
3231
esbuildOptions: {
3332
define: {
3433
global: 'globalThis',

0 commit comments

Comments
 (0)