You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
In this guide we're going to learn how to go from zero to a running Cshell instance with the least amount of effort.
10
+
11
+
<Steps>
12
+
1.### Installation
13
+
14
+
<Tabs>
15
+
<TabItemlabel="mac">
16
+
You can use Homebrew to install the latest version of Cshell in Mac (both x86 / ARM64)
17
+
18
+
```sh
19
+
brew install txpipe/tap/cshell
20
+
```
21
+
</TabItem>
22
+
<TabItemlabel="linux">
23
+
You can install Cshell on linux system using the following command:
24
+
25
+
```sh
26
+
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/txpipe/cshell/releases/latest/download/cshell-installer.sh | sh
27
+
```
28
+
</TabItem>
29
+
<TabItemlabel="npm">
30
+
You can use Npm to install Cshell on your system:
31
+
32
+
```sh
33
+
npm install @txpipe/cshell
34
+
```
35
+
</TabItem>
36
+
</Tabs>
37
+
38
+
2.### Configuration
39
+
40
+
_Cshell_ requires a UtxoRPC and TRP provider, the UtxoRPC is to fetch on-chain data, and the TRP is to resolve and submit transactions. You can get one free instance on [demeter](https://demeter.run/). So when you have the UtxoRPC and TRP url, run the following command that will guide you through a set of questions to define a provider:
41
+
42
+
```sh
43
+
cshell provider create
44
+
```
45
+
46
+
With the provider configured, it is possible to create a wallet or import one. The following example shows how to create one.
47
+
48
+
```sh
49
+
cshell wallet create
50
+
```
51
+
52
+
3.### Running
53
+
54
+
Explore the commands in the docs or run `cshell --help`. The following command opens a GUI explorer using the default provider.
Cshell uses [**UtxoRPC**](https://utxorpc.org) as its on-chain data provider. It connects to a UtxoRPC server to collect blockchain data and follow the tip. Any service that implements the UtxoRPC interface can act as a data provider for Cshell, for example, [**Dolos**](https://github.com/txpipe/dolos).
10
+
11
+
UtxoRPC is used only for supplying on-chain data. For transaction resolution and submission, Cshell uses a TRP (Transaction Resolution Protocol) server. TRP, used with [**Tx3**](https://github.com/tx3-lang/tx3), exposes a JSON-RPC interface to resolve and submit transactions. Any application that implements that JSON-RPC interface can serve as Cshell's TRP provider, for example [**Hydra TRP**](https://github.com/tx3-lang/tx3-hydra).
12
+
13
+
<Asidetype="tip">
14
+
Use [**Demeter**](https://demeter.run/) to get a free tier UtxoRPC and TRP instance.
15
+
</Aside>
16
+
17
+
### Provider storage
18
+
All cshell provider configurations are stored in a single file on your local machine:
19
+
20
+
- File: **cshell.toml**
21
+
- Location: In your user home directory (examples: **~/cshell.toml**)
22
+
23
+
This file contains the definitions for every provider you create.
24
+
25
+
## Usage
26
+
When providers are available, create and configure a provider in Cshell using the **interactive** command below:
27
+
28
+
```bash
29
+
cshell provider create
30
+
```
31
+
32
+
You can manage providers using Cshell's provider commands. To see which provider commands are available, run the following:
33
+
34
+
```bash
35
+
cshell provider --help
36
+
```
37
+
38
+
And the `--help` flag can be used anywhere in Cshell. For example, after choosing the create command, you can check the options available for that command as well:
With Cshell fully configured ([provider](/cshell/provider) and [wallet](/cshell/wallet)), it's time to start using it to manage transactions or fetch on-chain data.
10
+
11
+
You can execute any transaction in Cshell using [**tx3**](https://docs.txpipe.io/tx3). Cshell will call the TRP to resolve and submit the transaction.
12
+
13
+
<Asidetype="tip">
14
+
Use `--help` to view the CLI options.
15
+
</Aside>
16
+
17
+
<Asidetype="note">
18
+
The `--help` flag can be used anywhere in Cshell
19
+
</Aside>
20
+
21
+
## Commands
22
+
The commands below are used to handle transactions and fetch on-chain data.
23
+
24
+
### Transactions
25
+
You can manage transactions by using Cshell's `tx` or `transactions` commands. To see which tx commands are available, run the following:
26
+
27
+
```bash
28
+
cshell tx --help
29
+
```
30
+
31
+
Use the `--help` flag with any command to view its available options.
32
+
33
+
```bash
34
+
cshell tx invoke --help
35
+
```
36
+
37
+
### Search
38
+
You can search by block or transactions using the commands search. To see which search commands are available, run the following
39
+
40
+
<Asidetype="note">
41
+
Use the `--output-format` flag to change the output format, it supports `json`, `table`. Default is `table`.
42
+
</Aside>
43
+
44
+
```bash
45
+
cshell search --help
46
+
```
47
+
48
+
Use the `--help` flag with any command to view its available options.
How cshell handles wallet creation, storage, and security. Understanding these concepts is crucial for managing your funds safely.
10
+
11
+
### Wallet storage
12
+
All cshell wallet configurations are stored in a single file on your local machine:
13
+
14
+
- File: **cshell.toml**
15
+
- Location: In your user home directory (examples: **~/cshell.toml**)
16
+
17
+
This file contains the definitions for every wallet you create, import, or restore.
18
+
19
+
### Security and encryption
20
+
Cshell protects private keys using a password-based encryption model.
21
+
22
+
- When you create a wallet you set a spending password.
23
+
- The password is run through Argon2 to derive an encryption key, and that key is used with the `ChaCha20-Poly1305` cipher to encrypt the wallet’s private key.
24
+
-**Your password is never stored on disk**, it exists only in memory when needed to sign a transaction.
25
+
26
+
<Asidetype="caution">
27
+
Because the password is never stored, it cannot be recovered. If you lose it you must restore the wallet from its mnemonic seed phrase
28
+
</Aside>
29
+
30
+
### Unsafe wallets (plain-text keys)
31
+
Cshell supports an `--unsafe` option at creation time (wallet create --unsafe).
32
+
33
+
- What it does: disables password protection and stores the private key in plain text inside cshell.toml.
34
+
- Intended use: temporary, disposable wallets for development or testing only.
35
+
36
+
<Asidetype="caution">
37
+
Never store real funds in an unsafe wallet. Anyone with access to cshell.toml can control those funds
38
+
</Aside>
39
+
40
+
### Importing vs restoring wallets
41
+
Cshell supports both wallet import and wallet restore, these are different operations with different functional implications.
- Restore: recovering fully functional wallets using the mnemonic seed phrase.
45
+
46
+
## Usage
47
+
Create a wallet using the **interactive** command below:
48
+
49
+
```bash
50
+
cshell wallet create
51
+
```
52
+
53
+
You can manage wallets using Cshell's wallet commands. To see which wallet commands are available, run the following:
54
+
55
+
```bash
56
+
cshell wallet --help
57
+
```
58
+
59
+
And the `--help` flag can be used anywhere in Cshell. For example, after choosing the create command, you can check the options available for that command as well:
0 commit comments