DEV Community: Row-Bear

Launch your own SorobanRPC server

Row-Bear — Fri, 16 Aug 2024 21:24:51 +0000

This is a submission for the Build Better on Stellar: Smart Contract Challenge : Create a Tutorial

Your Tutorial

https://dev.to/row-bear/rpc-for-soroban-mainnet-36eo

What I Created

This is a tutorial I wrote shortly after the launch of Soroban, to help devs set up their own SorobanRPC server.
Now, there are also good public RPC services available, but this may still be useful for someone out there.

Journey

Int he days leading up to the launch of Soroban, I had set myself the goal to be the first to invoke a Soroban contract.
I realized that there'd likely not be any public RPC service available off the bat, so I figured out how to use the SorobanRPC docker image to run my own.

Alas, I did think of the RPC Server, but did not properly account for the resource limits.
Deploying the XLM contract was not possible with the CLI during phase 0, so my RPC Server ended up not used. Overcat managed to deploy the contracts via SDK, leaving me the dubious honour of being the first to 'burn' a stroop via smart contract transfer.

Anyway, I hope this may still come in handy for anyone wanting their own RPC server for developing and testing purposes.

As always, join the Stellar Dev discord to discuss the technical stuff, and the Stellar Global discord for everything Stellar.

Happy coding!

Soroban RPC - on Windows

Row-Bear — Sat, 24 Feb 2024 21:58:16 +0000

Earlier, I posted how to run the Soroban RPC Docker image locally on Linux.
Today, I'll give you the steps for Windows.

1) Install Docker Desktop
You can just use the installer.
https://docs.docker.com/desktop/install/windows-install/

2) Sign in (or not)

3) Search for stellar/soroban-rpc and pull it

4) Create a stellar-core.toml config file
I use the example I stored here but as Kalepail pointed out during his stream on the Stellar Dev discord, you can use one from the Quickstart image.
You may need to remove some lines from the header.

I placed it at c:\soroban-rpc

4) Start a terminal (cmd) window and run the container:
I used the following command to start:

docker run -p 8001:8001 -p 8000:8000 ^
-v c:/soroban-rpc:/config stellar/soroban-rpc ^
--captive-core-config-path="/config/stellar-core.toml" ^
--captive-core-storage-path="/var/lib/stellar/captive-core" ^
--stellar-core-binary-path="/usr/bin/stellar-core" ^
--db-path="/var/lib/stellar/soroban-rpc-db.sqlite" ^
--stellar-captive-core-http-port=11626 ^
--network-passphrase="Public Global Stellar Network ; September 2015" ^
--history-archive-urls="https://history.stellar.org/prd/core-live/core_live_001" ^
--admin-endpoint="0.0.0.0:8001" ^
--endpoint="0.0.0.0:8000"

Two things of note:

notice how I used the directory of the stellar-core.toml config in the second line.
Windows cmd uses ^ for multi-line input. Delightfully, Powershell uses ` (backtick) ¯\_(ツ)_/¯ You can probably do this from the Docker Desktop UI, but I haven't figured out how to easily launch it with all these flags.

5) Go back to Docker Desktop and check the containers tab.

You can start/stop the container from here, and also see its stats.

During initial sync, it uses ~50% of my CPU (i5 12450h) and about 4-5 GB RAM, but after about 15 minutes that dropped to 15% and 1GB. Docker Desktop itself uses 7GB RAM though, I guess it reserves quite some headroom.

If you have any practical tips for others, please share them in the comments :-)

As always, join the Stellar Dev discord to discuss the technical stuff, and the Stellar Global discord for everything Stellar.

Happy coding!

RPC for Soroban mainnet

Row-Bear — Thu, 22 Feb 2024 12:01:52 +0000

It's here! Soroban smart contracts have launched on Stellar mainnet on 20 Feb 2024 at 17:00 UTC.

The validators cast their votes at 17:00 UTC, and the first ledger after that (50457424) was running on protocol 20.
And within seconds, the first smart contract was deployed: CDGFGODCSQQQFFBUEJGS7NIDUA5OQKBRFQ57IOKZAZIEJDNQNHS3RV5O

But then.. quiet!? No other contract calls. Why is that?
First of all, Soroban is in phase 0 for the first week, with very low limits on resources contracts can use.
But another thing that perhaps caught devs by surprise was the lack of RPC servers.
See, you need an RPC server to interact with Soroban. And for testnet and futurenet, the SDF has made their RPC server publicly availabe. Not so on mainnet though.

So what's a dev to do?
The docs have a list of public RPC providers you can have a look at.
There are paid and free plans, and even no-signup options.
But you can also run one yourself. It's not very hard, I managed to do it.
There is a page in the Soroban docs, but I found myself needing more info.
And I've compiled that info and steps into a bite-size guide here!

You will need:

~ 80GB of disk space
~ 1 hour for initial sync
~ 1o minutes for re-sync when you re-start it
An internet connection
At least some CPU and RAM, I run it comfortably on my laptop with (i5 12450h CPU and 16 GB RAM.

The below is for Linux, see my other post for Windows.

I give you my

10 easy steps to run Soroban-RPC

1) Docker
First, you'll need to install docker on your PC.
I followed this guide

2) Set up a folder
Create a folder in your home/user dir, called soroban-rpc
For me, that is at /home/row-bear/soroban-rpc
(Or whatever you like, just remember the name)

3) Get the Docker image
In a new terminal window: docker pull stellar/soroban-rpc image

4) Configure
The RPC image will need a stellar-core.toml file.
The best practice is to craft one yourself, so you can evaluate which validators you want to include or exclude in your trust set.
I use this one.
Place that file in the folder you made in step 2.
For me, it's at /home/row-bear/soroban-rpc/stellar-core.toml

5) Start it up!
Replace 'row-bear' in the below command with your username (or the whole path with whichever directory you made) and in a new terminal window, run:



docker run -p 8001:8001 -p 8000:8000 \
--name sorobanrpc \
-v /home/row-bear/soroban-rpc:/config stellar/soroban-rpc \
--captive-core-config-path="/config/stellar-core.toml" \
--captive-core-storage-path="/var/lib/stellar/captive-core" \
--stellar-core-binary-path="/usr/bin/stellar-core" \
--db-path="/var/lib/stellar/soroban-rpc-db.sqlite" \
--stellar-captive-core-http-port=11626 \
--network-passphrase="Public Global Stellar Network ; September 2015" \
--history-archive-urls="https://history.stellar.org/prd/core-live/core_live_001" \
--admin-endpoint="0.0.0.0:8001" \
--endpoint="0.0.0.0:8000"

(Edited to add the --name parameter, as suggested by Alex in the comments. Much easier than fiddling with the ID later on!)

You may need to use sudo, depending on your system config.
If you want it to run on testnet or futurenet, adjust the passphrase in the command (and modify your stellar-core.toml !).

It will start and start to sync. This can take up to an hour, for the first time.

6) Find the container ID
To make sure you can stop and restart the image without doing the full sync again (and eating your disk space in the process!) we'll need to find the container id.
In a new terminal, run docker container ls -a
Remember the -a flag. Else, it will only show running containers. One might assume the container is gone, and keep creating new ones.. 1/10 would not recommend.
If it does happen to you: docker container prune will remove the stopped containers

Note down the ID of the container that is running. For me, it's 929de777dddc.
Alternatively, you can use the name we supplied when starting it.

7) Stopping and starting it
In a terminal window, run
sudo docker stop <id> and then
sudo docker start <id>
So, for me: sudo docker stop 929de777dddc
Or: sudo docker stop sorobanrpc

8) Monitor the logs
After restarting, you won't see the log output in your terminal window. If you want that, run:
sudo docker logs -f sorobanrpc

9) Check the status
Again in a terminal, you can run:



curl --location 'http://localhost:8000' \
--header 'Content-Type: application/json' \
--data '{
"jsonrpc":"2.0",
"id":2,
"method":"getHealth"
}'

If it's synced, you'll get:

10) Now let's use it!
It's up and running, and hopefully synced.
If you use soroban-cli, you can now add a network to use your RPC: soroban network add local_rpc --rpc-url http://localhost:8000 --network-passphrase "Public Global Stellar Network ; September 2015"
Then, in your next soroban contract invoke, you can use your very own RPC with --network local_rpc

If you have any practical tips for others, please share them in the comments :-)

As always, join the Stellar Dev discord to discuss the technical stuff, and the Stellar Global discord for everything Stellar.

Happy coding!

Soroban Reverse Auction

Row-Bear — Fri, 22 Dec 2023 22:42:52 +0000

The past week, I have been tinkering with a new Soroban project.
It's been quite a learning experience, both in Soroban and in frontend.
I'll talk you through how I built my app, and share some of my lessons and thoughts.

The code (and a large readme) can be found on github

Reverse Dutch Auction
What I've made is a Reverse Dutch Auction.
I am still missing a few cards from my RPCiege collection, so I want to find a way to acquire the missing ones.

With a Reverse Auction, a buyer can:
-Set a (low) starting price
-Define how much and how often the price will increase over time

A seller can then interact with the auction, to sell their card/asset when the price is high enough for them.
However, if they wait too long, someone else may take the offer!

Soroban
To set this up in Soroban, I've made a contract with 5 functions.

setup_auction
The first function is for setting up the auction.

It takes in some arguments, and returns a Status (or an error)
The arguments define what's being bought and sold, and how the price behaves.
For example: I (host) will buy 1 RPCiege card (auction_asset) and pay in XLM (counter_asset). My starting bid will be 20 XLM (starting_bid), and I will increase it with 10 XLM (bid_incr_amount) every 17000 ledgers (about 1x per day) (bid_incr_interval).
I will increase it 10 times (bid_incr_times).

That means I will pay at least 20 XLM, up to 120 XLM after 10 days.

The function starts out with some sanity checks:

The host must be authorised: in effect, that means the address/account we provide must sign the transaction. After all, they will provide the 'money' to buy the asset with.

Then we check if the contract was already initialised/started.
We do that by seeing if there is already a Datakey for State set in storage.
If there is, we return an Status::AuctionAlreadyInitialised.
This lets users know what's up, without a full error.

Then, we check if the bid is actually positive. We don't want any weird negative prices being paid.

Next, we ensure that the contract will have it's rent paid for the duration of the auction.
In Soroban, entries need to pay rent to stay on the ledger.
This avoids bloating the ledger with old and irrelevant data.
In this case, I've put all the contract's data in the .instance() storage.
That means any bump/extend_ttl operation will pay the rent for our data and the contract itself.

Then, we transfer the counter_asset from the buyer to the contract:

That means the contract acts as broker, and the funds are guaranteed to be available for a seller.
Note that we use the try_transfer method. If it were to fail, we can catch that error.

Then, we save all the information we have received and calculated.

I've made a custom struct AuctionData to hold all that information.
That makes it easier to pass that object around, for example into and out of storage. It's probably not the most efficient way though.
We store that AuctionData struct into the instance() storage.
We also store a datakey to show that the auction is now Running.

Next, we emit an event.

Events can be monitored via the Soroban RPC servers.
We emit all information needed to calculate how the bid changes over time, so that sellers don't need to invoke the contract.

Then finally, we return a Status to the user, to let them know the auction has started.

Since a Soroban contract/transaction will execute atomically, any errors will result in the whole function failing/reverting.
No need to worry whether any funds were transferred if the contract fails to save it's data. It's all or nothing!

get_bid_info
The second function in the auction contract is get_bid_info().
This one doesn't take any parameters!

It does return another custom struct: BidInfo.
This functions does the basic arthritics to determine what the price is at this moment.
The price increase happens not strictly on a time base, but on the closing of ledgers. A ledger will generally close every 5 or 6 seconds.

First, we do a bit of state checking:

If there is no State datakey set, the auction has not been setup, so we throw an error.
And similar, if the State is anything other than Running, we also throw an error.

Then, we ask the Soroban env what the current ledger is. We also retrieve our AuctionData from storage:

After some basic calculations, we stumble on some mildly interesting (to me) Rust.
I want to have two different flows, based on if the price has reached its maximum or not.
But if we declare the variables inside the scope of the if, we can't use them outside it.
So, we declare (but don't assign values to) the variables first.

Then, we go on to calculate what the price is now, when it will increase, and when it will reach the maximum:

Finally, we create a BidInfo struct with all this information, and return that.
We also emit an event, for anyone interested. It saves them a contract invoke.

sell_asset
Next up is the function to be used by a seller.
They call the sell_asset function, which requires their address as parameter:

We then make sure the state of the auction is right, and that the seller is authorised (has signed the transaction):

To proceed with the sale, we retrieve the auction data, but we also need to know what the current bid is.
Good thing we already wrote a function to get that bid information!
We call the contracts own get_bid_info() function with Self::get_bid_info(env.clone()).unwrap().current_bid;
We pass it a clone of the current env, then take the current bid value out.
It's not the most efficient way. We spend some cycles to calculate things we don't need, we only use the .current_bid
But, it saves me from writing that specific part of code.
And this function will only rarely be used: once per auction. So, I accept that overhead.

We go on to transfer the funds:
The seller sends 1 stroop of the NFT asset to to contract, and the contract returns the current price.

Again, this happens all at once, or not at all.
The way Soroban is built ensures that execution can not stop after the first transfer. If the second transfer fails, none of the operations take place.

We emit an event with the sell price, set the auction state to Fulfilled and return a Status message to the seller, and that's it for this function.

close_auction
The organiser of the auction (the buyer) has the option to close the auction down again.
They can do this before or after a seller sells their asset.
If it's done before, the auction is Aborted, the funds return to the buyer and the auction becomes inactive.
If it's done after the sale took place, it goes slightly different.
The NFT is transferred to the buyer, along with any left-over funds.
Then, the auction is set to Closed

We start again with some checks on the state of the auction:

Then, we load the auction data and make sure the host/organiser is signing the transaction:

If the auction is running, we return all the funds to the buyer, before setting the status to Aborted.

Notice how we get the balance: we cross contract call the contract of the funds, and ask it for the balance of our contract.
It's possible to avoid this by keeping track of the balance ourselves.
But, that also opens up chances for errors and bugs.
Again, I'll take that overhead cost and use this method of getting the balance.

If the auction was Fulfilled, we use two transfers.
One for the NFT, and one for any remaining funds (if any, we check to see if that is > 0).

All that remains is to set the state to Closed and return the buyer the good news:

reset_auction
For demonstration purposes, I've added a reset function to the auction.
If it has been closed, we remove the storage information.
Effectively, this means the auction contract can be reset again.
For here, the interesting part is to show how we clear the storage:

We only have the two datakeys, one for State and one for AuctionData.
We simply remove them.
Note though, the information can still be found by people going back through ledger histories. So don't put any secrets in a public ledger, thinking you can remove them later :)

That concludes the Rust code used in the Soroban Reverse Auction.
The readme on github has a detailed step-by-step guide on how to compile(build), deploy and interact with this contract yourself.
It also has files and instructions for hosting a local copy of the interactive demo, so you can experiment with your own auction contract.

I'll spare you the details of the many hours spent getting that demo working. I'll summarize:

Happy coding!

RPCIEGE - Skirmish 10

Row-Bear — Fri, 06 Oct 2023 14:46:34 +0000

And we're already moving on to Skirmish 10 of the RPCiege!

Have a look at the booklet for the exact details of the mission. Here's my summary:

We have been given a game contract, and its code
To complete the skirmish, we have to guess an "unpredictable" number, and invoke the contract with that number as parameter.
Since we have the code, the number is not exactly unpredictable. We just have to extract it.

As a small diversion, you can try to make a manual guess.
After all, you have about 1 in 4 billion chance to guess correct.

Okay, that's not going to work. We'll have to look at the contracts code.

The magic happens in this part of the code:

let state = u64::MIN
    .wrapping_add(env.ledger().timestamp())
    .wrapping_add(env.ledger().sequence() as u64);
let mut rng = SmallRng::seed_from_u64(state);

if guess != rng.gen_range(0..1_000_000_000) {
    return Err(Error::WrongGuess);
}

We see that a random number is derived from the ledger timestamp and ledger sequence.
Then, our guess is compared to that number.
Back in Skirmish 6 there was a similar situation. Then, there was some room to calculate the number, then quickly invoke the game contract.

Now, we don't have that option. We have to make the guess in the same ledger as the calculation happens.
Luckily, cross-contract calls come to the rescue.
If your contract calls another contract, that will happen in the same ledger.
So, we can make our own contract and use the same logic to calculate the guess. Then call the game contract from our own contract, and since it happens in the same ledger, the timestamp and sequence will be the same.

The Soroban Examples include a cross-contract example, which I've used as the basis for the solution.
Like the in previous skirmish, we can use soroban contract fetch in soroban-cli to retreive the game contract.

Then, it can be imported in your own contract code, so you can interact with it.

I'm not going to give out the full solution, but I'll share my wrong_guess function.

It sets my guess to 1, then calls the target contract with it.
Notice how I've put a target: Address parameter in the contract.
When invoking my contract, I have to put the game contract in as argument. That way, my contract knows which contract to shoot the guess at.

Now it's up to you to replace let guess: u32 = 1; with the calculation for the correct number. With the information above and in the booklet, you should be able to :-)
And if not, leave a comment, or even better, hop in the Stellar Dev Discord.

Happy cieging!

Row-Bear

PS: If you get stuck, chances are you'll have to add a dependency or two to your Cargo.toml:

[dependencies]
soroban-sdk = "20.0.0-rc2"
rand = { version = "0.8.5", default-features = false, features = ["small_rng"] }
getrandom = { version = "0.2", features = ["js"] }

RPCIEGE - Skirmish 9

Row-Bear — Thu, 05 Oct 2023 21:31:07 +0000

It's time to have a go at Skirmish 9 of the Soroban RPCiege!
For a short recap on what RPCiege is, see my previous post.

Skirmish 9 is about upgrading our contract.

Our mission:

We're pointed to the game contract, which is a deployer: it will deploy a contract for us to work with.
Let's call it, then see what we have to work with.

(You'll notice I took the lazy route with the salt again: copied the example value and adjusted it slightly. You'll have to generate your own unique one)
A little spoiler: after you've used the deploy function, you don't need to do anything with the deployer contract anymore.

Now that we have a contract, let's see what it does.
Last time we used -h to let soroban-cli show us information about the functions. This time, we'll use fetch

soroban contract fetch --network rpciege --id <your_contract_id_here> -o skirmish_9.wasm

This lets soroban-sli download the contract (through the specified RPC server) and store it in the specified -o file.

Then, we can inspect it:

soroban contract inspect --wasm skirmish_9.wasm

It's not as pretty as -h, but it does show all functions and their parameters at once.
Here we can see that the run function doesn't take any parameters, and that the upgrade_contract function takes one parameter, named hash. It takes a value of the types BytesN.
Luckily, soroban-cli will handle the conversion from String to BytesN for us.

If you've completed any of the other skirmishes, you may notice that there's no parameter for _nft_dest.
That means we can't claim those slick trading cards!

But you've probably connected the dots by now:

Contract with missing function parameter
Upgradable contract
??
Profit!

Yes, you need to write a new contract now.
I'm not going to show the exact Rust code to use.
You could write one from scratch, or modify one you have. I don't know if it must have a function called run, but I named my function that.
I know it doesn't need to do anything, but you can be creative.
Just make sure it also has a parameter _nft_dest.
Now soroban contract build it, and let's get to upgrading.

To upgrade a contract, three things are needed:

An existing contract with code to upgrade itself (already provided)
A new wasm thats been installed on the ledger. (It doesn't have to be deployed though)
A hash to identify which wasm you want to use.

To install the wasm of your new upgrade, you can use:

soroban contract install --network rpciege --source <your identity> --wasm <path_to_your_wasm>

The install command will return you the hash of your installed contract.

So, we finally reach the conclusion:

You have a target contract, with an upgrade_contract function that takes a --hash argument.
You also have your own contract, installed, and its hash

Happy cieging!

RPCIEGE - Skirmish 8

Row-Bear — Mon, 02 Oct 2023 21:51:25 +0000

So, I'll give this a try: my writeup of Skirmish 8 in the RPCiege.

On the off-chance someone reads this without knowing what that is, here's a brief summary.
On www.rpciege.com there is a series of coding games/challenges on the Soroban smart contract platform. It's currently in a testing stage, aiming to go live end of 2023.
RPCiege (and its predecessor Stellar Quest) will let you get familiar with the language and platform, and gives you kick-ass collectible cards to boot.

So, on to Skirmish 8. I'll give a brief writeup of how I attempted to tackle this, and give some hints on how you can solve it.
No full solution, but enough to get you going.

The booklet gives you your mission, and a helpful link to documentation. However, with the latest preview release, you don't actually need the linked docs!

To get started, we have a contract. I always start by pointing my friend -h at the contract.
It will tell you what functions the contract has, which is always a good start.

And you can also use -h on those functions itself, to get information about what parameters the function expects. Let's have a look:

The _nft_dest is optional, so I'll skip it. I already have the cards and my spot on the leaderboard :)
For source, I'll just use my configured identity.
But notice how --answer expects an <Array<u32>>? And it even gives an example of such an array.
I took the lazy route, and just tried it with that example.

In the current release, we see a lot of diagnostic events, along with the return of the function.
So, a few things to unwrap here:
1) I just passed [1] as answer
2) The diagnostics return a vector: [0, 4508]
3) We died.. that's usually not good.

So, we didn't solve this yet. But did you expect that, with an answer of [1]?

I'll give a hint here: the 0 in that vector is the number of positions we got correct.
And we got some information: the number 4508.
So, let's try --answer with that as input:

And now we starved.. so something has changed.
And notice that we did not get a screen full of diagnostic info.
So, when we Died, the contract emitted a diagnostic event, and when we Starved, it did not.

But that also leaves us stuck for a bit.
Any random input leads to Died, except for that number we got returned earlier.
But --answer takes a vector! So we can input more numbers.
After some fiddling around, I decided to add my random guess after the 4508:

We still Died, but have a different diagnostic event.
So we're getting somewhere. 1 correct position, and the number 4509.

That should be enough to get you going.
For reference, there is another way to get the diagnostic events.
Soroban-cli has a command for it. You can point it at a contract, and it will return (recent) events emitted by it.
The part that always trips me up is the --start-ledger
I end up getting that from Stellar Laboratory. If there's a better way to find out what the latest ledger is, let me know!

Row-Bear

PS: After you have some parts of your sequence right, you might be able to predict the next parts..
If you're smarter than me, that may take you less time than uncovering them one by one.

PPS: Other than Died or Starved, you can also get Exploded. Bonus points if you reach that :)