Ready for the Rust SDK

Would you prefer to work with Rust? Follow these steps to use our Rust SDK.

Start by cloning our Rust SDK by typing:

git clone https://github.com/Golem-Base/rust-sdk.git

Next, inside the root folder for the repository, create a folder called practice.

Move into that folder and create a file called Cargo.toml, and add the following to it:

[package]
name = "golem-base-sdk-practice"
version = "0.1.0"
edition = "2021"

[dependencies]
alloy = "0.15"
bytes = "1.0"
dirs = "6.0"
env_logger = "0.11"
log = "0.4"
tokio = { version = "1", features = ["full"] }
ethers = "2"
rand = "0.8"

golem-base-sdk = { workspace = true }

Now in the same folder create a subfolder called src. Move into src and inside src create a file called main.rs. Add the following to main.rs:

use golem_base_sdk::entity::{Create, EntityResult, Update};
use golem_base_sdk::{Address, Annotation, GolemBaseClient, Hash, PrivateKeySigner, Url};
use log::info;
use std::fs;
use std::path::Path;

async fn log_num_of_entities_owned(client: &GolemBaseClient, owner_address: Address) {
    let n = client
        .get_entities_of_owner(owner_address)
        .await
        .expect("Failed to fetch entities of owner")
        .len();
    info!("Number of entities owned: {}", n);
}

#[tokio::main]
async fn main()  -> Result<(), Box<dyn std::error::Error>> {
    env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("info")).init();

    let private_key_path = Path::new("private.key");

    if !private_key_path.exists() {
        panic!("private.key not found in current directory.");
    }

    let private_key_bytes = fs::read(&private_key_path).expect("Failed to read private key file");
    let private_key = Hash::from_slice(&private_key_bytes);

    let signer = PrivateKeySigner::from_bytes(&private_key)
        .map_err(|e| format!("Failed to parse private key: {}", e))?;
    let url = Url::parse("http://localhost:8545").unwrap();
    let client = GolemBaseClient::builder()
        .wallet(signer)
        .rpc_url(url)
        .build();

    info!("Fetching owner address...");
    let owner_address = client.get_owner_address();
    info!("Owner address: {}", owner_address);
    log_num_of_entities_owned(&client, owner_address).await;

    info!("Creating entities...");
    let creates = vec![
        Create {
            data: "foo".into(),
            btl: 25,
            string_annotations: vec![Annotation::new("key", "foo")],
            numeric_annotations: vec![Annotation::new("ix", 1u64)],
        },
        Create {
            data: "bar".into(),
            btl: 2,
            string_annotations: vec![Annotation::new("key", "bar")],
            numeric_annotations: vec![Annotation::new("ix", 2u64)],
        },
        Create {
            data: "qux".into(),
            btl: 50,
            string_annotations: vec![Annotation::new("key", "qux")],
            numeric_annotations: vec![Annotation::new("ix", 3u64)],
        },
    ];
    let receipts: Vec<EntityResult> = client.create_entities(creates).await?;
    info!("Created entities: {:?}", receipts);
    log_num_of_entities_owned(&client, owner_address).await;

    info!("Deleting first entity...");
    client.delete_entities(vec![receipts[0].entity_key]).await?;
    log_num_of_entities_owned(&client, owner_address).await;

    info!("Updating the third entity...");
    let third_entity_key = receipts[2].entity_key;
    let metadata = client.get_entity_metadata(third_entity_key).await?;
    info!("... before the update: {:?}", metadata);
    client
        .update_entities(vec![Update {
            data: "foobar".into(),
            btl: 40,
            string_annotations: vec![Annotation::new("key", "qux"), Annotation::new("foo", "bar")],
            numeric_annotations: vec![Annotation::new("ix", 2u64)],
            entity_key: third_entity_key,
        }])
        .await?;
    let metadata = client.get_entity_metadata(third_entity_key).await?;
    info!("... after the update: {:?}", metadata);

    info!("Deleting remaining entities...");
    let remaining_entities = client
        .query_entity_keys("ix = 1 || ix = 2 || ix = 3")
        .await?;
    info!("Remaining entities: {:?}", remaining_entities);
    client.delete_entities(remaining_entities).await?;
    log_num_of_entities_owned(&client, owner_address).await;

    Ok(())
}

Now inside the src folder create another folder called bin:

mkdir bin
cd bin

Here we'll add code for creating a wallet. Create a new file called wallet.rs inside bin and add the following:

use ethers::signers::{LocalWallet, Signer};
use ethers::core::k256::ecdsa::SigningKey;
use std::fs::File;
use std::io::Write;
use std::path::Path;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let key_path = "private.key";

    if Path::new(key_path).exists() {
        println!("File \"{}\" already exists. Aborting.", key_path);
        return Ok(());
    }

    let wallet: LocalWallet = LocalWallet::new(&mut rand::thread_rng());
    let signing_key: &SigningKey = wallet.signer();
    let private_key_bytes = signing_key.to_bytes();

    let mut file = File::create(key_path)?;
    file.write_all(&private_key_bytes)?;

    println!("Address: {:?}", wallet.address());
    Ok(())
}

Now move back to the root folder of the repository. Let's make the current Cargo.toml aware of our practice project. Open Cargo.toml and find the section that looks like this:

[workspace]
members = ["api", "cli", "demo", "test-utils"]
resolver = "2"

Add a comma after test-utils and add an entry for practice:

[workspace]
members = ["api", "cli", "demo", "test-utils", "practice"]
resolver = "2"

Now we have two programs we can use; the second one we created, wallet.rs, we'll build and run first. This will create a new private.key file for us that will hold our wallet.

Creating a private.key file

While still in the root folder of the repo, type:

cargo build -p golem-base-sdk-practice --bin wallet

Note: If you get an error regarding finding openssl via pkg-config, you'll need to run the following:

sudo apt update
sudo apt install pkg-config libssl-dev

Then try running the build command again. After it builds, run it:

cargo run -p golem-base-sdk-practice --bin wallet

This will generate the private.key file in the root folder of the repo. The code will also print out the address. Copy the address into your clipboard, including the 0x and everything after it.

Now you're ready to add funds to it.

Adding Funds

Open your browser and go to this link, which is the faucet for Kaolin:

https://kaolin.holesky.golem-base.io/faucet/

Paste in your account Address that was printed out earlier and click Request Funds. After a moment, your account will have a couple Eth available in our testnet.

Creating Entities

And now you're ready to create and edit some entities with the code you created in the second file, main.rs. Here's how you build and run it:

cargo build -p golem-base-sdk-practice
cargo run -p golem-base-sdk-practice --bin golem-base-sdk-practice

(You can see a full example by looking in the /example folder as well as more in the /examples folder.)

• Wish to learn more?

  ---

  Golem Base introduces a novel architectural model for decentralized data infrastructure — designed to be modular, Ethereum-native, and accessible across both Web2 and Web3.

  For a complete overview:
  Read the Litepaper (PDF)

  It covers:

  • The structure and role of DB-Chains
  • How Golem Base aligns with Ethereum Layer 2/3 philosophy
  • Potential real-world use cases
  
  Golem Base Origins

  Golem Base was born from a need inside Golem Network — and grew into its own thing. Built by an independent team committed to the idea that data autonomy should be the norm, not the exception. Read more

• Join the Community

  ---

  Stay connected and get help as you explore Golem Base.

  • Discord — Chat with the team and other developers in real time.
  • GitHub — Ask questions, share feedback, or explore new ideas.
  • Twitter (X) — Follow us for announcements, updates, and ecosystem highlights.
  • Blog — Read technical deep dives, tutorials, and project news.
    
    
    Need Help?
  • Start with the Getting Started guide.
  • Browse the FAQ (coming soon).
  • Or open an issue on GitHub.