Skip to content

Commit

Permalink
Update READMEs for Protocol 22 (#36)
Browse files Browse the repository at this point in the history
* Update README

* Update quest READMEs

* Feedback from Elliot
  • Loading branch information
anataliocs authored Jan 9, 2025
1 parent 818a9b3 commit 41d6536
Show file tree
Hide file tree
Showing 6 changed files with 82 additions and 83 deletions.
12 changes: 6 additions & 6 deletions quests/1-hello-world/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,7 @@ commands from within your Testnet terminal.
# change into the quest directory
cd quests/1-hello-world
# build the contract
soroban contract build
stellar contract build
```

### Run a Test
Expand Down Expand Up @@ -241,9 +241,9 @@ got a couple of suggestions for where you might go from here.

[pq-lib]: https://github.com/stellar/soroban-quest--pioneer/blob/main/quests/0-hello-world/src/lib.rs
[pq-test]: https://github.com/stellar/soroban-quest--pioneer/blob/main/quests/0-hello-world/src/test.rs
[docs-build]: https://soroban.stellar.org/docs/getting-started/hello-world#build
[docs-deploy]: https://soroban.stellar.org/docs/getting-started/deploy-to-testnet
[soroban]: https://soroban.stellar.org/docs
[docs-build]: https://developers.stellar.org/docs/build/smart-contracts/getting-started/hello-world#build-the-contract
[docs-deploy]: https://developers.stellar.org/docs/build/smart-contracts/getting-started/deploy-to-testnet
[soroban]: https://developers.stellar.org/
[cap]: https://github.com/stellar/stellar-protocol/blob/master/core/cap-0046.md
[tutorials]: https://soroban.stellar.org/docs/tutorials
[contract-lifecycle]: https://soroban.stellar.org/docs/soroban-internals/contract-lifecycle
[tutorials]: https://developers.stellar.org/docs/build/smart-contracts/example-contracts
[contract-lifecycle]: https://developers.stellar.org/docs/learn/encyclopedia/contract-development/contract-lifecycle
16 changes: 8 additions & 8 deletions quests/2-auth-store/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,7 @@ Soroban has three types of Storage: `Temporary`, `Persistent`, and `Instance`.
- The default "lifetime" for temporary storage is **16 ledgers** (with an
estimated 5 seconds per ledger, that lifetime is roughly 80 seconds).
- The entry will become "dead" once the lifetime ends (unless the entry's TTL
has been extended). Once dead, the ledger entry is **permanently**
has been extended). Once dead, the the ledger entry is **permanently**
deleted.
- Later on, the entry _can_ be re-created, but it _cannot_ be restored.

Expand Down Expand Up @@ -190,11 +190,11 @@ contract code immediately extends the TTL of the entry to the maximum lifetime
when it is created. This is one technique to extend ledger entry lifetimes, but
certainly not the only method. You can also utilize a
[`ExtendFootprintTTLOp`][extend-ttl] operation inside a Stellar transaction to
accomplish the same thing. The `soroban` CLI also has a command to help
accomplish the same thing. The `stellar` CLI also has a command to help
facilitate these TTL extension transactions.

```bash
soroban contract extend \
stellar contract extend \
--id CARCWZOD26AJQ42VRJ3UYC3MJNGJV5UHO4VFHV5FWLVIKDCJ4CZOJXII \
--key KeySymbol \
--durability temporary \
Expand Down Expand Up @@ -236,8 +236,8 @@ check out [this section](../../README.md#feeling-lost) in our main README. It's
got a couple of suggestions for where you might go from here.

[how-to-play]: ../1-hello-world/README.md#how-to-play
[data-example]: https://soroban.stellar.org/docs/getting-started/storing-data
[auth-example]: https://soroban.stellar.org/docs/tutorials/auth
[persist-data]: https://soroban.stellar.org/docs/soroban-internals/persisting-data
[state-archival]: https://soroban.stellar.org/docs/soroban-internals/state-archival
[extend-ttl]: https://soroban.stellar.org/docs/soroban-internals/state-archival#extendfootprintttlop
[data-example]: https://developers.stellar.org/docs/build/smart-contracts/getting-started/storing-data
[auth-example]: https://developers.stellar.org/docs/build/smart-contracts/example-contracts/auth
[persist-data]: https://developers.stellar.org/docs/learn/encyclopedia/storage/persisting-data
[state-archival]: https://developers.stellar.org/docs/learn/encyclopedia/storage/state-archival
[extend-ttl]: https://developers.stellar.org/docs/build/guides/cli/extend-contract-storage
48 changes: 24 additions & 24 deletions quests/3-reverse-engineer/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ correct function in that contract, while providing the correct argument.**
- [How to Play](#how-to-play)
- [The Task at Hand](#the-task-at-hand)
- [Explore the Contract Code](#explore-the-contract-code)
- [Using `soroban` CLI to Decode XDR](#using-soroban-cli-to-decode-xdr)
- [Using `stellar` CLI to Decode XDR](#using-stellar-cli-to-decode-xdr)
- [How do I find a `contract_address`?](#how-do-i-find-a-contract_address)
- [1. Find an Operation](#1-find-an-operation)
- [2. View the Transaction Envelope](#2-view-the-transaction-envelope)
Expand Down Expand Up @@ -61,22 +61,22 @@ honestly). Sure, reading the code will help you understand the contract. Yes,
that's what we're trying to do. **But**, it will also answer many of the
questions you'll come up with as you work on this task.

### Using `soroban` CLI to Decode XDR
### Using `stellar` CLI to Decode XDR

A term you may already be familiar with is "XDR" which stands for _e**X**ternal
**D**ata **R**epresentation_. So much of what happens on the Stellar network is
done in XDR format: transactions, ledger data, history, operation results, and
the list goes on. XDR is a compact, network-efficient, binary format. While it's
great for many things, it's not human readable, so it can be pretty confusing.

Thankfully, the [`soroban` CLI][soroban-cli] makes it pretty easy to get
Thankfully, the [`stellar` CLI][stellar-cli] makes it pretty easy to get
decoded, useful, and understandable output from supplied XDR. For example, when
a transaction is submitted to the Network, the validators work with it in XDR
format. Here is how you could use the `soroban lab xdr decode` command to decode
format. Here is how you could use the `stellar lab xdr decode` command to decode
a Friendbot transaction XDR into a more human-readable format.

```bash
soroban lab xdr decode \
stellar lab xdr decode \
--type TransactionEnvelope \
--output json-formatted \
<<< AAAAAgAAAABIu5usRTTahvcdKMNti3923mNvvKPWQV3xI7qtMuKh2AAPQkAAAADaAAAAGAAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAAAABAAAAABB90WssODNIgi6BHveqzxTRmIpvAFRyVNM+Hm2GVuCcAAAAAAAAAADoiSQ5BfDlk+YhXpfApUuA63FeWkousb+bg9gfpDrGnQAAABdIdugAAAAAAAAAAAIy4qHYAAAAQJRl+oVaaDSwh2FcfmLdsEr/72DPFt9HxtBHRS0tNFiy+PymjWsWlO0v2/UOIo85gjXxHpZ3nzp63pdr/0KTvgiGVuCcAAAAQHq1Q5lFYJHU0HILXH70DIzdbWvbsk9/dnGcEhNNlzXsSp3WXeNk8xlDx0CtrD5DqVhITfOOVMGzlRFuWN1Tews=
Expand All @@ -87,8 +87,8 @@ if you were to run the above command, you'd see a human-readable representation
of a transaction creating an account with a starting balance of 10,000 XLM
(Testnet XLM, of course).

There are many different "types" you could use the `soroban` cli to decode. If
you run `soroban lab xdr types list` in your terminal, you'll see all the
There are many different "types" you could use the `stellar` cli to decode. If
you run `stellar lab xdr types list` in your terminal, you'll see all the
different options that are available to you.

### How do I find a `contract_address`?
Expand All @@ -99,7 +99,7 @@ skin a cat!! Anyway, I'm getting sidetracked...

There are a few different ways you could find a `contract_address` for an
already deployed contract. Currently, all of them involve decoding XDR. Decoding
can be done using the `soroban` cli, or the Stellar Laboratory, or RunKit, or
can be done using the `stellar` cli, or the Stellar Laboratory, or RunKit, or
you could come up with your own way to decode/encode the base64 as needed. But
they all start with finding the correct XDR to decode.

Expand Down Expand Up @@ -194,7 +194,7 @@ to the XDR viewer, where you can find the `contractId`.
</details>

Alternatively, you could copy/paste the whole Transaction Envelope string and
decode it using the `soroban` CLI to get the information you're after.
decode it using the `stellar` CLI to get the information you're after.

#### 3. Decode the Contract Address

Expand All @@ -214,7 +214,7 @@ discover a contract address from a known deployer account:
`HostFunctionTypeHostFunctionTypeCreateContract` operation.
- Use a block explorer or indexer to find relevant operations and/or
transactions.
- Use the soroban cli to generate a contract address from a provided wasm hash
- Use the stellar cli to generate a contract address from a provided wasm hash
and salt.

The possibilities are limitless!
Expand All @@ -238,11 +238,11 @@ installed executable's hash identifier).

It's a bit of a journey from there, and I highly suggest you take a trip to
[this part][get-wasm-code] of the [`getLedgerEntries` method][gle] on the
Soroban-RPC docs. You could ultimately retrieve the binary byte-code, decode it
Stellar-RPC docs. You could ultimately retrieve the binary byte-code, decode it
from base64 into hex, and then store it as a binary `.wasm` file locally.

The resulting `.wasm` file would be **identical** to the compiled contract that
was initially deployed. You could re-deploy it, use `soroban contract inspect`
was initially deployed. You could re-deploy it, use `stellar contract inspect`
to get information about it, or whatever else you could come up with. Cool,
huh!?

Expand All @@ -258,12 +258,12 @@ in handy at some point for you.
you get a handle on what's happening inside of Soroban. (Hint: Starting around
[23:14][twitch] is a _really_ useful discussion about decoding the XDR values
into something a little more user-friendly.)
- Developers can also use the Soroban-RPC interface to interact with futurenet
and get current state data. [The existing API docs][soroban-rpc] are still a
- Developers can also use the Stellar-RPC interface to interact with futurenet
and get current state data. [The existing API docs][stellar-rpc] are still a
work in progress, but contain some _very_ helpful information about how
Soroban contract invocations actually happen.
- Some basic information about the usage of the `soroban` CLI can be found on
the [Soroban Docs website][install-soroban]. In addition to that page many of
- Some basic information about the usage of the `stellar` CLI can be found on
the [Stellar Docs website][install-stellar]. In addition to that page many of
the tutorials and examples contain example CLI commands.

## Still Stuck?
Expand All @@ -274,15 +274,15 @@ got a couple of suggestions for where you might go from here.

[how-to-play]: ../1-hello-world/README.md#how-to-play
[xdr]: https://developers.stellar.org/docs/encyclopedia/xdr
[soroban-cli]: https://soroban.stellar.org/docs/reference/soroban-cli
[lab]: https://laboratory.stellar.org/#?network=test
[ops]: https://horizon-testnet.stellar.org/accounts/GDUISJBZAXYOLE7GEFPJPQFFJOAOW4K6LJFC5MN7TOB5QH5EHLDJ2SGP/operations?order=desc
[stellar-cli]: https://developers.stellar.org/docs/tools/developer-tools/cli/stellar-cli
[lab]: https://lab.stellar.org/?$=network$id=testnet&label=Testnet&horizonUrl=https:////horizon-testnet.stellar.org&rpcUrl=https:////soroban-testnet.stellar.org&passphrase=Test%20SDF%20Network%20/;%20September%202015;;
[ops]: https://horizon-testnet.stellar.org/operations/GDUISJBZAXYOLE7GEFPJPQFFJOAOW4K6LJFC5MN7TOB5QH5EHLDJ2SGP
[tx]: https://horizon-testnet.stellar.org/transactions/21f329e415594da21dbe4c12e446411aa435603801bd5bf67dd1b376f5f37fab
[twitch]: https://www.twitch.tv/videos/1642865389?t=00h23m14s
[twitch-clip]: https://clips.twitch.tv/FragileSneakyOstrichGivePLZ-DK9h3VVmUjqVDDZG
[twitch-full]: https://www.twitch.tv/videos/1642865389
[soroban-rpc]: https://soroban.stellar.org/api
[install-soroban]: https://soroban.stellar.org/docs/getting-started/setup#install-the-soroban-cli
[gle]: https://soroban.stellar.org/api/methods/getLedgerEntries
[get-wasm-code]: https://soroban.stellar.org/api/methods/getLedgerEntries#requesting-a-contracts-wasm-code
[sdk-encode-contract]: https://stellar.github.io/js-stellar-sdk/StrKey.html#.encodeContract
[stellar-rpc]: https://developers.stellar.org/docs/data/rpc
[install-stellar]: https://developers.stellar.org/docs/build/smart-contracts/getting-started/setup#install-the-stellar-cli
[gle]: https://developers.stellar.org/docs/data/hubble/analyst-guide/queries-for-horizon-like-data#getledgerentries
[get-wasm-code]: https://developers.stellar.org/docs/build/guides/dapps/state-archival#step-4-handling-contract-instance-restoration
[sdk-encode-contract]: https://stellar.github.io/js-stellar-sdk/StrKey.html#.encodeContract
24 changes: 12 additions & 12 deletions quests/4-cross-contract/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ the `get` function from your `DataStore` contract.**
- [Making an On-Chain Oracle](#making-an-on-chain-oracle)
- [Importing Contracts](#importing-contracts)
- [Using a Contract Client](#using-a-contract-client)
- [Passing Arguments to Soroban CLI](#passing-arguments-to-soroban-cli)
- [Passing Arguments to Stellar CLI](#passing-arguments-to-stellar-cli)
- [Further Reading](#further-reading)
- [Still Stuck?](#still-stuck)

Expand Down Expand Up @@ -136,7 +136,7 @@ sequenceDiagram
You can think of this contract client as if it were an existing "module" that
you're using in your own contract. Not too bad, Soroban my ol' buddy!

### Passing Arguments to Soroban CLI
### Passing Arguments to Stellar CLI

In case you haven't realized yet, Soroban depends on [Remote Procedure Call
(RPC)][rpc-wiki] to pass messages between clients and the network. RPC is used
Expand All @@ -159,7 +159,7 @@ lot more information, but I'll demonstrate how you might use this syntax to
authenticate and increment a counter, taken from the [Auth tutorial][auth].

```bash
soroban contract invoke \
stellar contract invoke \
--id C... \
-- \
increment \
Expand All @@ -174,14 +174,14 @@ contract's function that requires you to specify a custom type you've created.
You may need to pass it in the cli like this:

```bash
soroban contract invoke \
stellar contract invoke \
--id C... \
-- \
foo \
--address '{"cylinder":{"radius":3,"height":14}}'
```

You can see that it's very much like a JSON object. Often the `soroban` cli is
You can see that it's very much like a JSON object. Often the `stellar` cli is
smart enough to figure out what kind of argument you're _trying_ to supply, and
doing the JSON for you. It will let you know when it can't, though.

Expand All @@ -205,15 +205,15 @@ check out [this section](../../README.md#feeling-lost) in our main README. It's
got a couple of suggestions for where you might go from here.

[how-to-play]: ../1-hello-world/README.md#how-to-play
[ccc-example]: https://soroban.stellar.org/docs/tutorials/cross-contract-call
[ccc-example]: https://developers.stellar.org/docs/build/smart-contracts/example-contracts/cross-contract-call
[rpc-wiki]: https://en.wikipedia.org/wiki/Remote_procedure_call
[rpc-gforg]: https://www.geeksforgeeks.org/remote-procedure-call-rpc-in-operating-system/
[jsonrpc]: https://www.jsonrpc.org/
[auth]: https://soroban.stellar.org/docs/tutorials/auth#run-the-contract
[optimizing]: https://soroban.stellar.org/docs/getting-started/hello-world#optimizing-builds
[auth]: https://developers.stellar.org/docs/build/smart-contracts/example-contracts/auth#run-the-contract
[optimizing]: https://developers.stellar.org/docs/build/smart-contracts/getting-started/hello-world#optimizing-builds
[rust-traits]: https://doc.rust-lang.org/book/ch10-02-traits.html
[interacting-contracts]: https://soroban.stellar.org/docs/soroban-internals/contract-interactions
[persisting-data]: https://soroban.stellar.org/docs/soroban-internals/persisting-data
[hello-world-tut]: https://soroban.stellar.org/docs/getting-started/deploy-to-testnet#interact
[interacting-contracts]: https://developers.stellar.org/docs/learn/encyclopedia/contract-development/contract-interactions/overview
[persisting-data]: https://developers.stellar.org/docs/learn/encyclopedia/storage/persisting-data
[hello-world-tut]: https://developers.stellar.org/docs/build/smart-contracts/getting-started/deploy-to-testnet#interact
[fca00c]: https://fastcheapandoutofcontrol.com
[state-archival]: https://soroban.stellar.org/docs/soroban-internals/state-archival
[state-archival]: https://developers.stellar.org/docs/learn/encyclopedia/storage/state-archival
Loading

0 comments on commit 41d6536

Please sign in to comment.