Skip to content

Commit a89ff2b

Browse files
Anmol1696Anmol1696
authored
Merge pull request #557 from hyperweb-io/anmol/docs
docs: move docs of cosmos-kit from docs repo to product repo
2 parents a38e649 + 3ff4a16 commit a89ff2b

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

46 files changed

+3165
-0
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
name: Docs
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
- "docs/**"
9+
- ".github/workflows/docs.yaml"
10+
11+
env:
12+
# Repository specific variables
13+
REPO_NAME: cosmos-kit
14+
DOCS_DEST_PATH: pages/cosmos-kit
15+
16+
jobs:
17+
docs-deploy:
18+
runs-on: ubuntu-latest
19+
20+
steps:
21+
- name: Checkout
22+
uses: actions/checkout@v4
23+
24+
- name: Setup Node.js
25+
uses: actions/setup-node@v4
26+
with:
27+
node-version: '20'
28+
enable-global-cache: true
29+
30+
- name: Clone docs repository
31+
run: git clone https://x-access-token:${{ secrets.GH_HYPERWEB_PAT }}@github.com/hyperweb-io/docs.hyperweb.io.git external-docs
32+
33+
- name: Sync the docs and build
34+
run: |
35+
rsync -av --delete ./docs/ ./external-docs/${{ env.DOCS_DEST_PATH }}/
36+
cd external-docs
37+
yarn install
38+
yarn export
39+
40+
- name: Git push
41+
run: |
42+
cd external-docs
43+
git config user.name 'GitHub Action'
44+
git config user.email '[email protected]'
45+
git add .
46+
if git diff --cached --quiet; then
47+
echo "No changes to commit."
48+
else
49+
git commit -m "Automated: Update ${{ env.REPO_NAME }} documentation"
50+
git push
51+
fi
52+

‎docs/_meta.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"index": "Introduction",
3+
"get-started": "Get Started",
4+
"migration-to-v2": "Migration to V2",
5+
"provider": "Provider",
6+
"hooks": "Hooks",
7+
"cookbook": "Cookbook",
8+
"integrating-wallets": "Integrating Wallets",
9+
"advanced": "Advanced"
10+
}

‎docs/advanced.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# Advanced
2+
3+
## Code Structure
4+
5+
To make user better understand the whole design structure of CosmosKit, here to briefly introduce some important classes from `@cosmos-kit/core`.
6+
7+
There are four important classes.
8+
9+
- WalletManager
10+
- MainWalletBase
11+
- ChainWalletBase
12+
- WalletRepo
13+
14+
Before all, we need to clarify that there are two types of entities in CosmosKit as a wallet adapter: **Chain** and **Wallet**. Chain is identified by chain name i.e. `cosmoshub`, `osmosis` etc. And wallet is identified by wallet name i.e. `keplr-extension`, `keplr-mobile`, `cosmostation-extension` etc.
15+
16+
> Note that we're taking a single wallet application as a wallet in CosmosKit rather than the wallet product name. Taking `Keplr` as an example, we differentiate `extension` and `mobile` in our code because they are connected via totally different codes. So for product `Keplr`, we have two wallets `keplr-extension` and `keplr-mobile` in CosmosKit.
17+
18+
### WalletManager
19+
20+
`WalletManager` is the entrance of the whole code and it manages all `WalletRepo`, `MainWalletBase`, `ChainWalletBase` instances in it. It also corresponds to `ChainProvider` in `@cosmos-kit/react-lite` and `@cosmos-kit/react`. You can find that the properties of JSX element `ChainProvider` are almost the same with the constructor arguments of `WalletManager`. All necessary chain information and wallet information from `ChainProvider` will be passed to corresponding wallet classes via `WalletManager`.
21+
22+
Three important properties/arguments in `ChainProvider`/`WalletManager` are `chains`, `assetLists` and `wallets`. `chains` and `assetLists` provide chain information, and `wallets` provides wallet information. Actually `wallets` is an array of `MainWalletBase` instances. Here leads to the second class `MainWalletBase`.
23+
24+
### MainWalletBase
25+
26+
`MainWalletBase` is meant to provide a base implementation and unified interface for all different wallets like `keplr-extension`, `keplr-mobile` and `cosmostation-extension`. Basically every wallet has it's own `MainWallet` class, which extends `MainWalletBase` in common, but with `WalletClient` implemented in different ways. In this way `WalletManager` can handle all different wallets no matter how different they're inside.
27+
28+
> For practice you can take a look at [How to Integrate New Wallets into CosmosKit](/integrating-wallets/adding-new-wallets)
29+
30+
`MainWalletBase` is only about wallet and it's not about any specific chain. And it's responsible for initializing wallet client and managing all chain wallets. Here brings in the third class `ChainWalletBase`.
31+
32+
> So far `MainWalletBase` is dealing with four different broadcast/synchronization events for chain wallets.
33+
>
34+
> - broadcast_client
35+
> - broadcast_env
36+
> - sync_connect
37+
> - sync_disconnect
38+
>
39+
> See details below.
40+
41+
### ChainWalletBase
42+
43+
When you're trying to connect to a wallet, you always need to provide a target chain name so that the wallet knows what to response. So `ChainWalletBase` is the class actually being used for real connection. It's the finest grain of functionality that with chain specified and also wallet specified.
44+
45+
We're separating `MainWalletBase` and `ChainWalletBase` because it's clearer to put some common properties like `wallet client` and `env` in the `MainWalletBase` to enable
46+
centralized management and distribution (events `broadcast_client` and `broadcast_env`), and put only chain specified functionalities in `ChainWalletBase`.
47+
48+
Basically how many `chains` are provided in `ChainProvider` or `WalletManager`, how many `ChainWalletBase` instances will be constructed for a wallet. `ChainWalletBase` instances are independent with each other unless `sync` is set `true`. All the synchronization are also handled in `MainWalletBase` (events `sync_connect` and `sync_disconnect`).
49+
50+
### WalletRepo
51+
52+
We have a class `MainWalletBase` with wallet specified to manage all chain wallets. All these chain wallets are with the same wallet name but different chain name. Accordingly we also have another class `WalletRepo`, which with chain specified to manage all chain wallets that with the same chain name but different wallet name.
53+
54+
### MainWalletBase vs. WalletRepo
55+
56+
#### 1. **MainWalletBase**
57+
- **Purpose**: Manages a collection of chain wallets.
58+
- **Key Identifier**: Wallet name.
59+
- **Example**: It handles wallets like cosmoshub/keplr-extension, osmosis/keplr-extension, etc. These are wallets from different chains but with the same wallet name.
60+
61+
#### 2. **WalletRepo**
62+
- **Purpose**: Manages chain wallets too, but with a different approach.
63+
- **Key Identifier**: Chain name.
64+
- **Example**: It manages wallets like cosmoshub/keplr-extension, cosmoshub/keplr-mobile, etc. These are wallets from the same chain but with different wallet names.
65+
66+
#### Common Point
67+
- **Both MainWalletBase and WalletRepo** are involved in managing chain wallets, which are wallets associated with different blockchain networks.
68+
69+
#### Key Differences
70+
- **MainWalletBase**: Focuses on managing wallets based on the wallet’s name. It doesn’t matter what chain the wallet is from; as long as they share the same wallet name, MainWalletBase manages them.
71+
- **WalletRepo**: Concentrates on managing wallets based on the chain’s name. Here, the specific wallet names don’t matter; WalletRepo groups and manages wallets that are on the same blockchain network.
72+
73+
#### Practical Use
74+
- **In some decentralized applications (dapps)**, the focus might be more on the blockchain network (chain) rather than the wallet itself. In such cases, WalletRepo is particularly useful because it provides a perspective based on the chain, allowing different wallets on the same chain to be managed together.
75+
76+
#### Summary
77+
- **MainWalletBase**: Manages wallets across different chains but with the same wallet name.
78+
- **WalletRepo**: Manages different wallets on the same chain.
79+
80+
In essence, these two classes offer different ways of organizing and accessing chain wallets, based on what the primary point of interest is (wallet name or chain name).
81+
82+
So far `WalletRepo` is only used in [`WalletModal`](https://docs.cosmology.zone/cosmos-kit/provider/chain-provider#walletmodal) properties.

‎docs/cookbook/_meta.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"connect-multi-chains": "Connect Multiple Chains",
3+
"sign": "Sign"
4+
}

‎docs/cookbook/connect-multi-chains.mdx‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
## How to connect multiple chains?
2+
3+
### 1. Use `useChains` Hook
4+
CosmosKit introduces **[`useChains`](../hooks/use-chains)** hook starting from `v2.3.0`. Use it to connect to multiple chains.
5+
6+
### 2. For A Specific Wallet (No Modal Required)
7+
8+
Let's take `keplr-extension` for example.
9+
10+
```javascript
11+
import { useWalletClient } from "@cosmos-kit/react";
12+
13+
export default function Home() {
14+
const { status, client } = useWalletClient("keplr-extension"); // or cosmostation-extension, leap-extension, etc.
15+
16+
useEffect(() => {
17+
if (status === "Done") {
18+
client.enable?.(["cosmoshub-4", "osmosis-1", "juno-1"]);
19+
client.getAccount?.("juno-4").then((account) => console.log(account));
20+
client.getAccount?.("osmosis-1").then((account) => console.log(account));
21+
client
22+
.getAccount?.("cosmoshub-4")
23+
.then((account) => console.log(account));
24+
}
25+
}, [status]);
26+
// ...
27+
}
28+
```
29+
30+
### 3. No Specific Wallets (Modal Required, Version Prior to `v2.3.0`)
31+
32+
There's no `useChains` hook in CosmosKit then, so the best you can do is below.
33+
34+
```javascript
35+
export default function Home() {
36+
const { openView } = useChain("cosmoshub"); // or juno, osmosis, etc.
37+
const { status, client } = useWalletClient();
38+
39+
useEffect(() => {
40+
if (status === "Done") {
41+
client.enable?.(["cosmoshub-4", "osmosis-1", "juno-1"]);
42+
client.getAccount?.("juno-4").then((account) => console.log(account));
43+
client.getAccount?.("osmosis-1").then((account) => console.log(account));
44+
client
45+
.getAccount?.("cosmoshub-4")
46+
.then((account) => console.log(account));
47+
}
48+
}, [status]);
49+
50+
return (
51+
<div style={{ textAlign: "center", margin: "4rem" }}>
52+
<Button onClick={openView}>Connect</Button>
53+
</div>
54+
);
55+
}
56+
```

‎docs/cookbook/sign.mdx‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Sign
2+
3+
## Global Settings
4+
5+
```ts
6+
<ChainProvider
7+
...
8+
signerOptions={{
9+
preferredSignType: (chain: Chain) => {
10+
return 'amino';
11+
}
12+
}}
13+
>
14+
<Components />
15+
</ChainProvider>
16+
17+
const { getSigningStargateClient } = useChain('cosmoshub');
18+
const aminoSigningClient = await getSigningStargateClient();
19+
```
20+
21+
By default use `amino` signer. Or you need to set `return 'direct'` if `direct` signer required.
22+
23+
## Individual Settings
24+
25+
```ts
26+
const { status, client } = useWalletClient('keplr-extension');
27+
28+
if (status === 'Done') {
29+
/**
30+
* OR:
31+
* const aminoSigner = client.getOfflineSignerAmino('cosmoshub');
32+
* const directSigner = client.getOfflineSignerDirect('cosmoshub');
33+
*/
34+
const aminoSigner = client.getOfflineSigner('cosmoshub', 'amino');
35+
}
36+
37+
const aminoSigningClient = await SigningStargateClient.connectWithSigner(
38+
rpcEndpoint,
39+
aminoSigner
40+
);
41+
```

‎docs/get-started.mdx‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# How to use CosmosKit
2+
3+
> 💡 Make sure you are using `React18`
4+
>
5+
> `CosmosKit V1` is deprecated, we suggest using [`CosmosKit V2`](./migration-to-v2)
6+
>
7+
> `defaultSignOptions` has been preset as below in latest version (core >= 2.7, react-lite >= 2.5, react >= 2.9):
8+
9+
```json
10+
{
11+
preferNoSetFee: false,
12+
preferNoSetMemo: true,
13+
disableBalanceCheck: true,
14+
};
15+
```
16+
17+
## Quickstart
18+
19+
🏁 Get started quickly by using [create-cosmos-app](https://github.com/hyperweb-io/create-cosmos-app) to help you build high-quality Cosmos apps fast!
20+
21+
## Use CosmosKit from Scratch
22+
23+
### 1️⃣ Install Dependencies
24+
25+
Taking `Keplr` wallet as an example.
26+
27+
```sh
28+
yarn add @cosmos-kit/react @cosmos-kit/keplr chain-registry
29+
```
30+
31+
`@cosmos-kit/react` includes default modal made with `@interchain-ui/react`. If [customized modal](./provider/chain-provider/#customize-modal-with-walletmodal) is provided, you can use `@cosmos-kit/react-lite` instead to lighter your app.
32+
33+
There are multiple wallets supported by CosmosKit. Details see [Integrating Wallets](./integrating-wallets)
34+
35+
> Note: `@cosmjs/*` packages are peer dependencies in `@cosmos-kit/core`, so if you're not using `@cosmjs/*` in your dapp, `yarn install` would complain UNMET cosmjs peer dependencies.
36+
37+
### 2️⃣ Wrap Provider
38+
39+
First, add [`ChainProvider`](./provider/chain-provider) and provider [required properties](./provider/chain-provider#required-properties).
40+
41+
Example:
42+
43+
```tsx
44+
import * as React from 'react';
45+
46+
import { ChainProvider } from '@cosmos-kit/react';
47+
import { chains, assets } from 'chain-registry';
48+
import { wallets } from '@cosmos-kit/keplr';
49+
50+
// Import this in your top-level route/layout
51+
import "@interchain-ui/react/styles";
52+
53+
function CosmosApp() {
54+
return (
55+
<ChainProvider
56+
chains={chains} // supported chains
57+
assetLists={assets} // supported asset lists
58+
wallets={wallets} // supported wallets
59+
walletConnectOptions={...} // required if `wallets` contains mobile wallets
60+
>
61+
<YourWalletRelatedComponents />
62+
</ChainProvider>
63+
);
64+
}
65+
```
66+
67+
### 3️⃣ Consume with Hook
68+
69+
Take `useChain` as an example.
70+
71+
```tsx
72+
import * as React from 'react';
73+
74+
import { useChain } from "@cosmos-kit/react";
75+
76+
function Component ({ chainName }: { chainName: string }) => {
77+
const chainContext = useChain(chainName);
78+
79+
const {
80+
status,
81+
username,
82+
address,
83+
message,
84+
connect,
85+
disconnect,
86+
openView,
87+
} = chainContext;
88+
}
89+
```
90+
91+
## Localstorage Settings
92+
93+
### current wallet
94+
95+
- **Key**: `cosmos-kit@2:core//current-wallet`
96+
- **Type**: `string`
97+
98+
It records current wallet name. You can use this key to implement auto-connection in dapp. And it will expire after provided [session duration](./provider/chain-provider#sessionoptions).
99+
100+
### accounts
101+
102+
- **Key**: `cosmos-kit@2:core//accounts`
103+
- **Type**: `SimpleAccount[]`
104+
105+
It records the connected chains' account information. It's used for account restore when refreshing in CosmosKit. And it will expire after provided [session duration](./provider/chain-provider#sessionoptions).

‎docs/hooks/_meta.json‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"index": "Introduction",
3+
"use-chain": "- useChain",
4+
"use-chains": "- useChains",
5+
"use-chain-wallet": "- useChainWallet",
6+
"use-iframe": "- useIframe",
7+
"use-manager": "- useManager",
8+
"use-modal-theme": "- useModalTheme",
9+
"use-name-service": "- useNameService",
10+
"use-wallet": "- useWallet",
11+
"use-wallet-client": "- useWalletClient"
12+
}

‎docs/hooks/index.mdx‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
There are multiple hooks provided in CosmosKit. They all require [**ChainProvider**](./provider/chain-provider) from either `@cosmos-kit/react` or `@cosmos-kit/react-lite` to provide necessary information.
2+
3+
- [`useChain`](./hooks/use-chain): Provide chainWallet related properties and methods, and support multiple chains connected at one time. When `useChain` is called, corresponding chainWallets will be activated.
4+
5+
- [`useChainWallet`](./hooks/use-chain-wallet): Provide chainWallet related properties and methods, and support multiple chains and wallets connected at one time. When `useChainWallet` is called, corresponding chainWallet will be activated.
6+
7+
> See more information about [Differences Between `useChain` And `useChainWallet`](#differences-between-usechain-and-usechainwallet)
8+
9+
- [`useManager`](./hooks/use-manager): Manage all chains and wallets.
10+
11+
- [`useModalTheme`](./hooks/use-modal-theme): Manage default modal themes.
12+
13+
- [`useNameService`](./hooks/use-name-service): Get alias name of address from a particular name server.
14+
15+
- [`useWallet`](./hooks/use-wallet): Manage all chainWallets and the global status for a particular wallet.
16+
17+
- [`useWalletClient`](./hooks/use-wallet-client): Get the wallet client for a particular wallet.
18+
19+
- [`useIframe`](./hooks/use-iframe): Set up an iframe that can access the currently connected wallet automatically.
20+
21+
## Differences Between `useChain` And `useChainWallet`
22+
23+
1. `useChainWallet` requires an extra parameter `walletName`.
24+
2. `useChain` will pop up a wallet modal to connect while `useChainWallet` not.
25+
3. `useChain` exposes extra `openView` and `closeView` methods and `walletRepo` property.
26+
4. the return value of methods `getRpcEndpoint`, `getRestEndpoint`, `getStargateClient`, `getCosmWasmClient`, `getNameService` can be different between `useChain` and `useChainWallet`, because `useChain` explores all `chainWallets` related to the parameter `chainName`.

0 commit comments

Comments
 (0)