Skip to content

Commit 07b643a

Browse files
PoisonPhangPoisonPhang
authored
docs: create guides for TS SDK examples (#5182)
Adds three guides to walk through creating our TS examples
2 parents 6961174 + eb302b1 commit 07b643a

File tree

4 files changed

+560
-8
lines changed

4 files changed

+560
-8
lines changed

‎docs/astro.config.ts‎

Lines changed: 31 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ const { PORT = 4321, ENABLE_DEV_TOOLBAR = "false" } = loadEnv(
2424
"",
2525
)
2626

27+
// @ts-ignore
2728
export default defineConfig({
2829
site: SITE_URL,
2930
output: "static",
@@ -297,16 +298,38 @@ export default defineConfig({
297298
link: "/integrations/typescript",
298299
},
299300
{
300-
label: "Examples (EVM)",
301-
autogenerate: {
302-
directory: "/integrations/typescript/examples/evm",
303-
},
301+
label: "Guides (EVM)",
302+
items: [
303+
{
304+
label: "Guide: Send Funds Holesky → Sepolia",
305+
link: "/integrations/typescript/guided-tutorial/evm-holesky-sepolia",
306+
},
307+
{
308+
label: "Example: Send Funds Holesky → Sepolia",
309+
link: "/integrations/typescript/examples/evm/send-funds-holesky-to-sepolia/",
310+
},
311+
],
304312
},
305313
{
306-
label: "Examples (Cosmos)",
307-
autogenerate: {
308-
directory: "/integrations/typescript/examples/cosmos",
309-
},
314+
label: "Guides (Cosmos)",
315+
items: [
316+
{
317+
label: "Guide: Cross Chain Contract Call",
318+
link: "/integrations/typescript/guided-tutorial/cosmos-call",
319+
},
320+
{
321+
label: "Example: Cross Chain Contract Call",
322+
link: "/integrations/typescript/examples/cosmos/call/",
323+
},
324+
{
325+
label: "Guide: Send Funds Union → Sepolia",
326+
link: "/integrations/typescript/guided-tutorial/cosmos-union-sepolia",
327+
},
328+
{
329+
label: "Example: Send Funds Union → Sepolia",
330+
link: "/integrations/typescript/examples/cosmos/send-funds-union-to-sepolia/",
331+
},
332+
],
310333
},
311334
],
312335
},

‎docs/src/content/docs/integrations/typescript/guided-tutorial/cosmos-call.mdx‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
---
2+
title: Cross Chain Contract Calls
3+
description: Example call on Babylon to Ethereum contract.
4+
---
5+
6+
This guide walk's you through writing our example ["Call"](/integrations/typescript/examples/cosmos/call/). The goal of this guide is to show you how to conduct a cross chain contract call using [USC03 - ZKGM](/ucs/03/). In this case we will be calling a contract on Ethereum from Babylon.
7+
8+
Relevant imports will be included with each step. Outside of libraries provided by Union, this guide uses [Effect](https://effect.website/).
9+
10+
## Program
11+
12+
This first section is a walk through of creating the program section of the send funds example.
13+
14+
### 1. Program Declaration
15+
16+
Begin by using Effect to create a program function.
17+
18+
The signer used for this transaction is also declared here.
19+
20+
```ts
21+
import { DirectSecp256k1HdWallet } from "@cosmjs/proto-signing"
22+
import { Effect, Logger } from "effect"
23+
24+
const signer = await DirectSecp256k1HdWallet.fromMnemonic(
25+
process.env.MEMO ?? "memo memo memo",
26+
{ prefix: "bbn" },
27+
)
28+
29+
const program = Effect.gen(function*() {})
30+
```
31+
32+
### 2. Source and Destination
33+
34+
Using the `ChainRegistry` from the Union TS SDK, you can declare the source and destination chains used in this example. In this case, the source is Babylon (`babylon.bbn-1`) and the destination is Ethereum (`ethereum.1`).
35+
36+
```ts
37+
import { ChainRegistry } from "@unionlabs/sdk/ChainRegistry"
38+
import { UniversalChainId } from "@unionlabs/sdk/schema/chain"
39+
import { Effect, Logger } from "effect"
40+
41+
const program = Effect.gen(function*() {
42+
const source = yield* ChainRegistry.byUniversalId(
43+
UniversalChainId.make("babylon.bbn-1"),
44+
)
45+
46+
const destination = yield* ChainRegistry.byUniversalId(
47+
UniversalChainId.make("ethereum.1"),
48+
)
49+
})
50+
```
51+
52+
:::note
53+
The ID's provided here are Universal Chain ID's as defined by [UCS04](/ucs/04).
54+
:::
55+
56+
### 3. Call
57+
58+
To create a `Call`, we supply the `sender`, `contractAddress`, and `contractCalldata`.
59+
60+
More information about `Call` and its fields can be found in the [UCS03 - 0x01 Call Docs](/ucs/03/#0x01---call).
61+
62+
```ts
63+
import { Call, Ucs05, ZkgmClientRequest, ZkgmClientResponse } from "@unionlabs/sdk"
64+
import { Effect, Logger } from "effect"
65+
66+
const program = Effect.gen(function*() {
67+
68+
// ... snip ...
69+
70+
const call = Call.make({
71+
sender: Ucs05.CosmosDisplay.make({
72+
address: "bbn122ny3mep2l7nhtafpwav2y9e5jrslhekrn8frh",
73+
}),
74+
eureka: false,
75+
contractAddress: Ucs05.EvmDisplay.make({
76+
address: "0x921e5b5091f431f84f14423ec487783a853bc4b0",
77+
}),
78+
contractCalldata: "0xDEADBEEF",
79+
})
80+
})
81+
```
82+
83+
### 4. zkgm Request
84+
85+
Finally, with the `Call` ready - you can construct a `ZkgmClientRequest`.
86+
87+
```ts
88+
import { Call, Ucs05, ZkgmClientRequest, ZkgmClientResponse } from "@unionlabs/sdk"
89+
import { Effect, Logger } from "effect"
90+
91+
const program = Effect.gen(function*() {
92+
93+
// ... snip ...
94+
95+
const request = ZkgmClientRequest.make({
96+
source,
97+
destination,
98+
channelId: ChannelId.make(3),
99+
ucs03Address: "bbn1336jj8ertl8h7rdvnz4dh5rqahd09cy0x43guhsxx6xyrztx292q77945h",
100+
instruction: call,
101+
})
102+
})
103+
```
104+
105+
:::note
106+
UCS03 addresses can be found on the [Deployments page](/protocol/deployments/)
107+
:::
108+
109+
### 5. zkgm Execution and Response
110+
111+
Now that you’ve created a full zkgm request, you can execute it and wait on the response to close out the program.
112+
113+
```ts
114+
import { Call, Ucs05, ZkgmClientRequest, ZkgmClientResponse } from "@unionlabs/sdk"
115+
import { GasPrice } from "@cosmjs/stargate"
116+
import { Cosmos, CosmosZkgmClient } from "@unionlabs/sdk-cosmos"
117+
import { Effect, Logger } from "effect"
118+
const program = Effect.gen(function*() {
119+
120+
// ... snip ...
121+
122+
const client = yield* CosmosZkgmClient.make.pipe(
123+
Effect.provide(Cosmos.SigningClient.Live(
124+
"bbn122ny3mep2l7nhtafpwav2y9e5jrslhekrn8frh",
125+
"https://rpc.bbn-1.babylon.chain.kitchen",
126+
signer,
127+
{ gasPrice: GasPrice.fromString("0.0007ubbn") },
128+
)),
129+
Effect.provide(Cosmos.Client.Live("https://rpc.bbn-1.babylon.chain.kitchen")),
130+
)
131+
132+
const response: ZkgmClientResponse.ZkgmClientResponse = yield* client.execute(request)
133+
134+
yield* Effect.log("TX Hash:", response.txHash)
135+
})
136+
```
137+
138+
## Execution
139+
140+
With the program ready, we can now use Effect to execute our transfer and listen for a response.
141+
142+
```ts
143+
const program = Effect.gen(function*() {
144+
// ... program ...
145+
}).pipe(
146+
Effect.provide(ChainRegistry.Default),
147+
Effect.provide(Logger.replace(Logger.defaultLogger, Logger.prettyLoggerDefault)),
148+
)
149+
150+
Effect.runPromise(program)
151+
.then(console.log)
152+
.catch(console.error)
153+
```

‎docs/src/content/docs/integrations/typescript/guided-tutorial/cosmos-union-sepolia.mdx‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
---
2+
title: Send Funds Union → Sepolia
3+
description: Example transfer from Union to Sepolia.
4+
---
5+
6+
This guide walk's you through writing our example ["Send Funds Union -> Sepolia"](/integrations/typescript/examples/cosmos/send-funds-union-to-sepolia/). The goal of this guide it to show you how to create a token order and submit it to the [UCS03 - ZKGM](/ucs/04) interface.
7+
8+
Relevant imports will be included with each step. Outside of libraries provided by Union, this guide uses [Effect](https://effect.website/).
9+
10+
## Program
11+
12+
This first section is a walk through of creating the program section of the send funds example.
13+
14+
### 1. Program Declaration
15+
16+
Begin by using Effect to create a program function.
17+
18+
```ts
19+
import { Effect, Logger } from "effect"
20+
21+
const program = Effect.gen(function*() {})
22+
```
23+
24+
### 2. Source and Destination
25+
26+
Using the `ChainRegistry` from the Union TS SDK, you can declare the source and destination chains used in this example. In this case, the source is Union Testnet (`union.union-testnet-10`) and the destination is Sepolia (`ethereum.11155111`).
27+
28+
```ts
29+
import { ChainRegistry } from "@unionlabs/sdk/ChainRegistry"
30+
import { UniversalChainId } from "@unionlabs/sdk/schema/chain"
31+
import { Effect, Logger } from "effect"
32+
33+
const program = Effect.gen(function*() {
34+
const source = yield* ChainRegistry.byUniversalId(
35+
UniversalChainId.make("union.union-testnet-10"),
36+
)
37+
const destination = yield* ChainRegistry.byUniversalId(
38+
UniversalChainId.make("ethereum.11155111"),
39+
)
40+
})
41+
```
42+
43+
:::note
44+
The ID's provided here are Universal Chain ID's as defined by [UCS04](/ucs/04).
45+
:::
46+
47+
### 3. Token Order
48+
49+
Now you can define the token order that will be responsible for the transfer. This example uses the `TokenOrderV2` TS interface.
50+
51+
To construct the token order, you will need the token contract/denom on both the source chain (`baseToken`) and the destination chain (`quoteToken`). In this case, we are using the relevant denom and contract address for U.
52+
53+
We also need to determine the `Kind` for the `TokenOrder`. In this case, we use `solve`. Though kind can be `initialize`, `escrow`, `unescrow`, or `solve`. To understand which kind of token order to use, refer to the [UCS03 EVM Token Order Examples docs](/ucs/03/#evm-token-order-examples).
54+
55+
```ts
56+
import { TokenOrder, ZkgmClient, ZkgmClientRequest, ZkgmClientResponse } from "@unionlabs/sdk"
57+
import { Effect, Logger } from "effect"
58+
59+
const program = Effect.gen(function*() {
60+
61+
// ... snip ...
62+
63+
const tokenOrder = yield* TokenOrder.make({
64+
source,
65+
destination,
66+
sender: "union122ny3mep2l7nhtafpwav2y9e5jrslhek76hsjl",
67+
receiver: "0x50A22f95bcB21E7bFb63c7A8544AC0683dCeA302",
68+
baseToken: "au",
69+
baseAmount: 10n,
70+
quoteToken: "0xba5eD44733953d79717F6269357C77718C8Ba5ed",
71+
quoteAmount: 10n,
72+
kind: "solve",
73+
metadata:
74+
"0x000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000014ba5ed44733953d79717f6269357c77718c8ba5ed0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
75+
version: 2,
76+
})
77+
})
78+
```
79+
80+
:::note
81+
Solver metadata is supplied here in accordance with [UCS03](/ucs/03)
82+
:::
83+
84+
### 4. zkgm Request
85+
86+
Finally, the token order you've constructed can be used as an `instruction` to create a `ZkgmClientRequest`.
87+
88+
```ts
89+
import { TokenOrder, ZkgmClient, ZkgmClientRequest, ZkgmClientResponse } from "@unionlabs/sdk"
90+
import { ChannelId } from "@unionlabs/sdk/schema/channel"
91+
import { Effect, Logger } from "effect"
92+
93+
const program = Effect.gen(function*() {
94+
95+
// ... snip ...
96+
97+
const request = ZkgmClientRequest.make({
98+
source,
99+
destination,
100+
channelId: ChannelId.make(1),
101+
ucs03Address: "union1336jj8ertl8h7rdvnz4dh5rqahd09cy0x43guhsxx6xyrztx292qpe64fh",
102+
instruction: tokenOrder,
103+
})
104+
})
105+
```
106+
107+
:::note
108+
UCS03 addresses can be found on the [Deployments page](/protocol/deployments/)
109+
:::
110+
111+
### 5. zkgm Execution & Response
112+
113+
Now that you've created a full zkgm request, you can execute it and wait on the response to close out the program.
114+
115+
```ts
116+
import { TokenOrder, ZkgmClient, ZkgmClientRequest, ZkgmClientResponse } from "@unionlabs/sdk"
117+
import { Effect, Logger } from "effect"
118+
119+
const program = Effect.gen(function*() {
120+
121+
// ... snip ...
122+
123+
const zkgmClient = yield* ZkgmClient.ZkgmClient
124+
125+
const response: ZkgmClientResponse.ZkgmClientResponse = yield* zkgmClient.execute(request)
126+
127+
yield* Effect.log("TX Hash:", response.txHash)
128+
})
129+
```
130+
131+
## Execution
132+
133+
With the program ready, we can now use Effect to execute our transfer and listen for a response.
134+
135+
Below, several items of note are provided to the program:
136+
137+
- `Cosmos.SigningClient` connected to a Union Testnet RPC
138+
- This contains a manually crated key pair (normally fetched from wallet)
139+
- Network base gas price
140+
- `Cosmos.Client` connected to a Union Testnet RPC
141+
142+
```ts
143+
import { DirectSecp256k1HdWallet } from "@cosmjs/proto-signing"
144+
import { GasPrice } from "@cosmjs/stargate"
145+
import { Cosmos, CosmosZkgmClient } from "@unionlabs/sdk-cosmos"
146+
import { ChainRegistry } from "@unionlabs/sdk/ChainRegistry"
147+
import { Effect, Logger } from "effect"
148+
149+
const program = Effect.gen(function*() {
150+
// ... program ...
151+
}).pipe(
152+
Effect.provide(CosmosZkgmClient.layerWithoutSigningClient),
153+
Effect.provide(Cosmos.SigningClient.Live(
154+
"union122ny3mep2l7nhtafpwav2y9e5jrslhek76hsjl",
155+
"https://rpc.union-testnet-10.union.chain.kitchen",
156+
await DirectSecp256k1HdWallet.fromMnemonic(
157+
"memo memo memo",
158+
{ prefix: "union" },
159+
),
160+
{ gasPrice: GasPrice.fromString("100000au") },
161+
)),
162+
Effect.provide(Cosmos.Client.Live("https://rpc.union-testnet-10.union.chain.kitchen")),
163+
Effect.provide(ChainRegistry.Default),
164+
Effect.provide(Logger.replace(Logger.defaultLogger, Logger.prettyLoggerDefault)),
165+
)
166+
167+
Effect.runPromise(program)
168+
.then(console.log)
169+
.catch(console.error)
170+
```
171+
172+
---
173+
174+
You have now created and executed a transfer from a Cosmos chain using USC03-ZKGM with the Union TS SDK 🎉.
175+
176+
For ease of use, you can refer to the complete example ["Send Funds Union -> Sepolia"](/integrations/typescript/examples/cosmos/send-funds-union-to-sepolia/).
177+
178+
Happy building!

0 commit comments

Comments
 (0)