-
Notifications
You must be signed in to change notification settings - Fork 8
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Docs: CLI #52
Docs: CLI #52
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,217 @@ | ||
# 💻 CLI for `jstz` | ||
|
||
This guide will instruct through how to use the command line interface for `jstz` where the user can easily run the sandbox environment and test smart functions. | ||
|
||
`jstz` offers a number of commands to manage and test your smart functions. | ||
|
||
- [sandbox](#sandbox) - Locally deploy a sandbox environment. | ||
- [bridge](#bridge) - Interact with the XTZ asset bridge between Tezos and `jstz`. | ||
- [deploy](#deploy) - Deploy your smart function. | ||
- [run](#run) - Run your smart function. | ||
- [repl](#repl) - Enter an interactive REPL for the `jstz` runtime. | ||
|
||
::: tip | ||
|
||
- `jstz help`: Displays a general help message or help information for specific subcommands. | ||
|
||
- `jstz --version (-V)`: Displays the current version of `jstz`. | ||
|
||
::: | ||
|
||
# Setup config | ||
|
||
In order to run `jstz` cli, you need to create a setup file in `~/.jstz/config.json` that looks as follows: | ||
|
||
```json | ||
{ | ||
"jstz_path": "<path_to_jstz>", | ||
"octez_path": "<path_to_octez>", | ||
"octez_node_port": <octez_node_port_number>, # typically 18731 | ||
"octez_node_rpc_port": <octez_node_rpc_port_number>, # typically 18730 | ||
"sandbox": null | ||
} | ||
``` | ||
|
||
In the file, you should set your path to `jstz` and `octez` and also set the port numbers. | ||
Once the sandbox gets started with the `sandbox start` command, the `"sandbox"` property will contain the information about its run. | ||
|
||
# Commands | ||
|
||
## Sandbox | ||
|
||
The sandbox commands are responsible for managing the `jstz` sandbox environment. | ||
|
||
### Commands: | ||
|
||
- `start`: Starts the sandbox environment. | ||
|
||
- `stop`: Shuts down the sandbox environment. | ||
|
||
### Example: | ||
|
||
```bash | ||
# Terminal #1: | ||
$ jstz sandbox start | ||
$ | ||
$ Configuring sandbox... done | ||
$ Initializing octez-node configuration... done | ||
$ Generating identity... done | ||
$ Starting node... done | ||
$ Waiting for node to initialize.... done | ||
$ Waiting for node to bootstrap... done | ||
$ Importing activator account... done | ||
$ Activating alpha... done | ||
$ Importing account bootstrap1:unencrypted:edsk3gUfUPyBSfrS9CCgmCiQsTCHGkviBDusMxDJstFtojtc1zcpsh | ||
$ Importing account bootstrap2:unencrypted:edsk39qAm1fiMjgmPkw1EgQYkMzkJezLNewd7PLNHTkr6w9XA2zdfo | ||
$ Importing account bootstrap3:unencrypted:edsk4ArLQgBTLWG5FJmnGnT689VKoqhXwmDPBuGx3z4cvwU9MmrPZZ | ||
$ Importing account bootstrap4:unencrypted:edsk2uqQB9AY4FvioK2YMdfmyMrer5R8mGFyuaLLFfSRo8EoyNdht3 | ||
$ Importing account bootstrap5:unencrypted:edsk4QLrcijEffxV31gGdN2HU7UpyJjA8drFoNcmnB28n89YjPNRFm | ||
$ Client initialized | ||
$ Starting baker... done | ||
$ Deploying bridge... | ||
$ `jstz_bridge` deployed at KT1Qc6k3U3EYmQBEZfB58zt69wk5PFzy4XXM | ||
$ Creating installer kernel...done | ||
$ `jstz_rollup` originated at sr1UXVmFED596weKjgPCN8GgWhRrfDGMPxH9 | ||
$ Starting rollup node... done | ||
$ `jstz_bridge` `rollup` address set to sr1UXVmFED596weKjgPCN8GgWhRrfDGMPxH9 | ||
$ Bridge deployed | ||
$ Sandbox started 🎉 | ||
$ Saving sandbox config | ||
|
||
# Terminal #2: | ||
$ # Work with the sandbox ... | ||
$ jstz sandbox stop | ||
``` | ||
|
||
## Bridge | ||
|
||
Bridge commands facilitate the interaction between L1 and L2. | ||
|
||
### Commands: | ||
|
||
- `deposit`: Transfer assets between an L1 sandbox address and an L2 sandbox address. | ||
|
||
### Usage: | ||
|
||
```bash | ||
jstz bridge deposit --from <TZ1_ADDRESS> --to <TZ4_ADDRESS> --amount <AMOUNT> | ||
``` | ||
|
||
### Options: | ||
|
||
- `--from (-f) <TZ1_ADDRESS>`: The L1 sandbox address or alias to withdraw from. | ||
|
||
- `--to (-t) <TZ4_ADDRESS>`: The L2 sandbox address or alias to deposit to. | ||
|
||
- `--amount (-a) <INTEGER>`: The quantity in ctez to transfer. | ||
|
||
### Example: | ||
|
||
```bash | ||
$ jstz bridge deposit --from tz1faswCTDciRzE4oJ9jn2Vm2dvjeyA9fUzU --to tz4N7y3T2e2dfCyHB1Ama68jnt3Fps7Ufu6d --amount 57 | ||
``` | ||
|
||
## Deploy | ||
|
||
This command allows users to deploy smart functions. | ||
|
||
### Usage: | ||
|
||
```bash | ||
jstz deploy --self-address <SELF_ADDRESS> --function-code <FUNCTION_CODE> --balance <BALANCE> | ||
``` | ||
|
||
### Options: | ||
|
||
- `--self-address (-s) <SELF_ADDRESS>`: Address used when deploying the contract. | ||
|
||
- `--function-code (-f) <FUNCTION_CODE>`: The code for the function being deployed. | ||
|
||
- `--balance (-b) <BALANCE>`: Specifies the initial balance for the function. | ||
Comment on lines
+126
to
+130
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Types instead of names |
||
|
||
### Example | ||
|
||
```bash | ||
$ jstz deploy --self-address tz4CNucLU82UYRcnkGvk1UWmVdVdj8AfDzvU --function-code "$(cat examples/counter.js)" --balance 42 | ||
``` | ||
|
||
## Run | ||
|
||
Execute a smart function using a specified URL. | ||
|
||
### Usage: | ||
|
||
```bash | ||
jstz run [OPTIONS] <URL> <referrer> | ||
``` | ||
|
||
### Arguments: | ||
|
||
- `<URL>`: The URL containing the function's address or alias. | ||
- `<referrer>`: The address of the entity calling the function. | ||
|
||
### Options: | ||
|
||
- `--request (-r) <request>`: Specifies the HTTP method used in the request. Default is `GET`. | ||
|
||
- `--data (-d) <data>`: Defines the JSON data to be included in the request body. | ||
|
||
### Example | ||
|
||
```bash | ||
$ export counter=tz4CYGgcFtphw3AXS2Mx2CMmfj6voV5mPc9b # Address of the previously deployed contract examples/counter.js | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Unnecessary |
||
$ cargo run -- run "tezos://${counter}/" tz4CNucLU82UYRcnkGvk1UWmVdVdj8AfDzvU | ||
$ cargo run -- run "tezos://${counter}/" tz4CNucLU82UYRcnkGvk1UWmVdVdj8AfDzvU | ||
$ cargo run -- run "tezos://${counter}/" tz4CNucLU82UYRcnkGvk1UWmVdVdj8AfDzvU | ||
$ cargo run -- run "tezos://${counter}/" tz4CNucLU82UYRcnkGvk1UWmVdVdj8AfDzvU | ||
``` | ||
|
||
In the logs, you should be able to see an output of the counter smart function looking like this: | ||
|
||
``` | ||
[🪵] Counter: null | ||
[🪵] Counter: 0 | ||
[🪵] Counter: 1 | ||
[🪵] Counter: 2 | ||
``` | ||
|
||
## REPL | ||
|
||
Starts a REPL environment for experimentation and testing of smart functions. | ||
|
||
### Usage: | ||
|
||
```bash | ||
jstz repl [OPTIONS] | ||
``` | ||
|
||
### Options: | ||
|
||
- `--self-address (-s) <SELF_ADDRESS>`: Address used when deploying the contract. | ||
|
||
### Example | ||
|
||
```bash | ||
$ jstz repl | ||
$ Using mock self-address tz4RepLRepLRepLRepLRepLRepLRepN7Cu8j. | ||
$ >> const subcontract1 = Contract.create(`export default (() => { return Response.json({ message: "hello world" }); });`) | ||
$ [📜] Contract created: tz4JGZp7XEojgrpnzL8UdTi3Kn4NaPRVQNwS | ||
$ >> const response = subcontract1.then(address => Contract.call(new Request(`tezos://${address}/`))) | ||
$ Evaluating: "export default (() => { return Response.json({ message: \"hello world\" }); });" | ||
$ >> response.then(async response => console.log((await response.json()).message)) | ||
$ [🪵] hello world | ||
$ [object Promise] | ||
$ >> exit | ||
``` | ||
|
||
::: tip | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Tip feels unnecessary, given the tip at the start |
||
|
||
Remember, the `-h` or `--help` flag can always be used after any command or subcommand to receive more detailed information about its usage. This guide is a brief overview, and the `help` command will provide the most current and detailed instructions. | ||
|
||
::: | ||
|
||
# Logs | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Would be best to move the logs section to the top |
||
|
||
In order to see the output logs of the above commands, you should check the logs/kernel.log file. | ||
We provide `scripts/commands/view-console.sh` script through which conveniently shows the tail of most relevant parts of the log file. | ||
Alternatively you can use tools like `tail` or `grep` for lookup in the logs. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd rephase this for the
--help
flag