Skip to content

Commit 5df16e6

Browse files
EehMauroEehMauro
authored
docs: add examples (#46)
1 parent e6e722a commit 5df16e6

File tree

11 files changed

+555
-5
lines changed

11 files changed

+555
-5
lines changed

‎README.md‎

Lines changed: 73 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,6 @@ To add a wallet, you can do the following:
8888

8989
```sh
9090
cargo run -- wallet create
91-
9291
```
9392

9493
This will prompt you for a a name and a password. Keep in mind that losing the
@@ -102,8 +101,80 @@ cargo run -- provider create
102101

103102
This will prompt you for a name, a kind (only UTxORPC supported), whether it is for mainnet or testnet, a URL and the possibility to add headers.
104103

105-
>>> If you have a [Demeter](https://demeter.run) port you would have to set the URL as `https://{host}` and on put `dmtr-api-key:YOUR_API_KEY` on the headers.
104+
> If you have a [Demeter](https://demeter.run) port you would have to set the URL as `https://{host}` and on put `dmtr-api-key:YOUR_API_KEY` on the headers.
105+
106+
# Examples
107+
108+
In the `examples` folder you can find scripts demonstrating advanced capabilities.
109+
110+
## Batch transactions
111+
112+
This example shows how to send transactions to multiple recipients in a batch.
113+
114+
**Location:** `examples/batch-transactions/`
115+
116+
**Usage:**
117+
```sh
118+
./transfer.sh <sender_wallet> <receiver_wallets_list> <lovelace_amount>
119+
```
106120

121+
**Arguments:**
122+
- `sender_wallet`: Name of the wallet sending the funds (e.g., `alice`)
123+
- `receiver_wallets_list`: Comma-separated list of recipient wallet names (e.g., `bob,charlie,mark`)
124+
- `lovelace_amount`: Amount in lovelaces to send to each recipient (e.g., `1000000`)
107125

126+
**Example:**
127+
```sh
128+
./transfer.sh alice bob,charlie,mark 1000000
129+
```
130+
131+
This will send 1,000,000 lovelaces from Alice's wallet to Bob, Charlie, and Mark individually.
132+
133+
## Scheduled tasks
134+
135+
This example demonstrates how to schedule recurring transactions using cron expressions.
136+
137+
**Location:** `examples/scheduled-tasks/`
138+
139+
**Usage:**
140+
```sh
141+
./transfer.sh <sender_wallet> <receiver_wallet> <lovelace_amount> <cron_string>
142+
```
143+
144+
**Arguments:**
145+
- `sender_wallet`: Name of the wallet sending the funds (e.g., `alice`)
146+
- `receiver_wallet`: Name of the recipient wallet (e.g., `bob`)
147+
- `lovelace_amount`: Amount in lovelaces to send (e.g., `1000000`)
148+
- `cron_string`: Cron schedule expression in the format `'minute hour day month weekday'`
149+
150+
**Example:**
151+
```sh
152+
./transfer.sh alice bob 1000000 '0 */2 * * *'
153+
```
154+
155+
This will schedule a transfer of 1,000,000 lovelaces from Alice to Bob every 2 hours.
156+
157+
## Complex transaction
158+
159+
This example shows how to interact with a protocol that requires several parameters, specifically creating a ship in [Asteria](https://asteria.txpipe.io).
160+
161+
**Location:** `examples/complex-transaction/`
162+
163+
**Usage:**
164+
```sh
165+
./create-ship.sh <player_wallet> <pos_x> <pos_y>
166+
```
167+
168+
**Arguments:**
169+
- `player_wallet`: Name of the player's wallet (e.g., `alice`)
170+
- `pos_x`: X coordinate for the ship position (integer)
171+
- `pos_y`: Y coordinate for the ship position (integer)
172+
173+
**Example:**
174+
```sh
175+
./create-ship.sh alice 25 25
176+
```
108177

178+
This will create a new ship for Alice at coordinates (25, 25) in [Asteria](https://asteria.txpipe.io).
109179

180+
> Note: you need to use a provider with the Cardano preview testnet in order to submit this transaction

‎dist-workspace.toml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,11 @@ cargo-dist-version = "0.29.0"
88
# CI backends to support
99
ci = "github"
1010
# The installers to generate for each app
11-
installers = ["shell", "npm", "homebrew"]
11+
installers = ["shell", "powershell", "npm", "homebrew"]
1212
# A GitHub repo to push Homebrew formulas to
1313
tap = "txpipe/homebrew-tap"
1414
# Target platforms to build apps for (Rust target-triple syntax)
15-
targets = ["aarch64-apple-darwin", "aarch64-unknown-linux-gnu", "x86_64-apple-darwin", "x86_64-unknown-linux-gnu"]
15+
targets = ["aarch64-apple-darwin", "aarch64-unknown-linux-gnu", "x86_64-apple-darwin", "x86_64-unknown-linux-gnu", "x86_64-pc-windows-msvc"]
1616
# Publish jobs to run in CI
1717
publish-jobs = ["homebrew"]
1818
# Which actions to run on pull requests

‎docs/commands/_meta.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
label: Commands
2-
order: 5
2+
order: 6
33
collapsed: true

‎docs/examples.mdx‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
---
2+
title: Examples
3+
sidebar:
4+
order: 5
5+
---
6+
7+
In the CShell [repo](https://github.com/txpipe/cshell) you can find scripts demonstrating advanced capabilities.
8+
9+
## Batch transactions
10+
11+
This example shows how to send transactions to multiple recipients in a batch.
12+
13+
**Location:** [`examples/batch-transactions/`](https://github.com/txpipe/cshell/tree/main/examples/batch-transactions)
14+
15+
**Usage:**
16+
```sh
17+
./transfer.sh <sender_wallet> <receiver_wallets_list> <lovelace_amount>
18+
```
19+
20+
**Arguments:**
21+
- `sender_wallet`: Name of the wallet sending the funds (e.g., `alice`)
22+
- `receiver_wallets_list`: Comma-separated list of recipient wallet names (e.g., `bob,charlie,mark`)
23+
- `lovelace_amount`: Amount in lovelaces to send to each recipient (e.g., `1000000`)
24+
25+
**Example:**
26+
```sh
27+
./transfer.sh alice bob,charlie,mark 1000000
28+
```
29+
30+
This will send 1,000,000 lovelaces from Alice's wallet to Bob, Charlie, and Mark individually.
31+
32+
## Scheduled tasks
33+
34+
This example demonstrates how to schedule recurring transactions using cron expressions.
35+
36+
**Location:** [`examples/scheduled-tasks/`](https://github.com/txpipe/cshell/tree/main/examples/scheduled-tasks)
37+
38+
**Usage:**
39+
```sh
40+
./transfer.sh <sender_wallet> <receiver_wallet> <lovelace_amount> <cron_string>
41+
```
42+
43+
**Arguments:**
44+
- `sender_wallet`: Name of the wallet sending the funds (e.g., `alice`)
45+
- `receiver_wallet`: Name of the recipient wallet (e.g., `bob`)
46+
- `lovelace_amount`: Amount in lovelaces to send (e.g., `1000000`)
47+
- `cron_string`: Cron schedule expression in the format `'minute hour day month weekday'`
48+
49+
**Example:**
50+
```sh
51+
./transfer.sh alice bob 1000000 '0 */2 * * *'
52+
```
53+
54+
This will schedule a transfer of 1,000,000 lovelaces from Alice to Bob every 2 hours.
55+
56+
## Complex transaction
57+
58+
This example shows how to interact with a protocol that requires several parameters, specifically creating a ship in [Asteria](https://asteria.txpipe.io).
59+
60+
**Location:** [`examples/complex-transaction/`](https://github.com/txpipe/cshell/tree/main/examples/complex-transaction)
61+
62+
**Usage:**
63+
```sh
64+
./create-ship.sh <player_wallet> <pos_x> <pos_y>
65+
```
66+
67+
**Arguments:**
68+
- `player_wallet`: Name of the player's wallet (e.g., `alice`)
69+
- `pos_x`: X coordinate for the ship position (integer)
70+
- `pos_y`: Y coordinate for the ship position (integer)
71+
72+
**Example:**
73+
```sh
74+
./create-ship.sh alice 25 25
75+
```
76+
77+
This will create a new ship for Alice at coordinates (25, 25) in [Asteria](https://asteria.txpipe.io).
78+
79+
> Note: you need to use a provider with the Cardano preview testnet in order to submit this transaction

‎docs/index.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,13 @@ In this guide we're going to learn how to go from zero to a running Cshell insta
2626
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/txpipe/cshell/releases/latest/download/cshell-installer.sh | sh
2727
```
2828
</TabItem>
29+
<TabItem label="windows">
30+
You can use PowerShell to install Cshell on your system:
31+
32+
```sh
33+
powershell -c "irm https://github.com/txpipe/cshell/releases/latest/download/cshell-installer.ps1 | iex"
34+
```
35+
</TabItem>
2936
<TabItem label="npm">
3037
You can use Npm to install Cshell on your system:
3138

‎examples/batch-transactions/transfer.sh‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
#!/bin/bash
2+
3+
# Validate arguments
4+
if [ $# -ne 3 ]; then
5+
echo "Error: exactly 3 arguments are required"
6+
echo "Usage: $0 <sender_wallet> <receiver_wallets_list> <lovelace_amount>"
7+
echo "Example: $0 alice bob,charlie,mark 1000000"
8+
exit 1
9+
fi
10+
11+
# Get arguments
12+
SENDER_WALLET=$1
13+
RECEIVER_WALLETS=$2
14+
AMOUNT=$3
15+
16+
# Validate sender wallet name is not empty
17+
if [ -z "$SENDER_WALLET" ]; then
18+
echo "Error: sender wallet name cannot be empty"
19+
exit 1
20+
fi
21+
22+
# Validate receiver wallets list is not empty
23+
if [ -z "$RECEIVER_WALLETS" ]; then
24+
echo "Error: receiver wallets list cannot be empty"
25+
exit 1
26+
fi
27+
28+
# Validate amount is a positive integer
29+
if ! [[ "$AMOUNT" =~ ^[0-9]+$ ]]; then
30+
echo "Error: amount must be a positive integer"
31+
exit 1
32+
fi
33+
34+
# Get sender wallet info
35+
SENDER_INFO=$(cshell wallet info --name $SENDER_WALLET 2>&1)
36+
if [ $? -ne 0 ]; then
37+
echo "Error: sender wallet '$SENDER_WALLET' does not exist"
38+
exit 1
39+
fi
40+
41+
SENDER_ADDRESS=$(echo "$SENDER_INFO" | grep "Address (testnet)" | awk '{print $5}')
42+
43+
for RECEIVER_WALLET in ${RECEIVER_WALLETS//,/ }; do
44+
45+
echo "Sending $AMOUNT lovelaces from $SENDER_WALLET to $RECEIVER_WALLET"
46+
47+
RECEIVER_INFO=$(cshell wallet info --name $RECEIVER_WALLET 2>&1)
48+
if [ $? -ne 0 ]; then
49+
echo "Error: receiver wallet '$RECEIVER_WALLET' does not exist"
50+
exit 1
51+
fi
52+
53+
RECEIVER_ADDRESS=$(echo "$RECEIVER_INFO" | grep "Address (testnet)" | awk '{print $5}')
54+
55+
cshell tx invoke \
56+
--tx3-file ./transfer.tx3 --signers $SENDER_WALLET --unsafe \
57+
--tx3-args-json "{\"sender\":\"$SENDER_ADDRESS\",\"receiver\":\"$RECEIVER_ADDRESS\",\"quantity\":$AMOUNT}"
58+
59+
echo ""
60+
61+
done

‎examples/batch-transactions/transfer.tx3‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
party Sender;
2+
3+
party Receiver;
4+
5+
tx transfer(
6+
quantity: Int
7+
) {
8+
input source {
9+
from: Sender,
10+
min_amount: Ada(quantity) + fees,
11+
}
12+
13+
output {
14+
to: Receiver,
15+
amount: Ada(quantity),
16+
}
17+
18+
output {
19+
to: Sender,
20+
amount: source - Ada(quantity) - fees,
21+
}
22+
}

0 commit comments

Comments
 (0)