BDO Rust Client

This is the Rust client SDK for the BDO (Blockchain Data Objects) miniservice.

Installation

Add this to your Cargo.toml:

[dependencies]
bdo-rs = { path = "path/to/bdo-rs" }
sessionless = "0.x"
tokio = { version = "1", features = ["full"] }
serde_json = "1"

Usage

Basic Example

use bdo_rs::BDO;
use sessionless::Sessionless;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize sessionless for key management
    let sessionless = Sessionless::new();

    // Create BDO client (uses dev environment by default)
    let bdo = BDO::new(None, Some(sessionless));

    let hash = "this hash describes the context for this bdo";

    let new_bdo = json!({
        "you": "can",
        "put": "whatever",
        "you": {
            "want": "here",
            "so": "long",
            "as": "it's"
        },
        "an": "object"
    });

    // Create a new user
    let user = bdo.create_user(hash, &new_bdo, &false).await?;
    println!("Created user with UUID: {}", user.uuid);

    // Update the BDO
    let updated_bdo = json!({
        "put": "something else"
    });
    let updated_user = bdo.update_bdo(&user.uuid, hash, &updated_bdo, &false).await?;

    // Get the BDO back
    let retrieved_user = bdo.get_bdo(&user.uuid, hash).await?;
    println!("Retrieved BDO: {:?}", retrieved_user.bdo);

    // Delete the user
    let result = bdo.delete_user(&user.uuid, hash).await?;
    println!("User deleted: {}", result.success);

    Ok(())
}

Working with Emojicodes

Emojicodes are human-memorable identifiers for public BDOs. They consist of 8 emoji (3 base emoji + 5 unique emoji) and are automatically assigned when you create a public BDO.

use bdo_rs::BDO;
use sessionless::Sessionless;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let sessionless = Sessionless::new();
    let bdo = BDO::new(None, Some(sessionless));

    let hash = "my_public_bdo";
    let pub_key = bdo.sessionless.public_key().to_hex();

    // Create a public BDO (automatically gets an emojicode)
    let public_bdo = json!({
        "name": "My Public Data",
        "description": "This is accessible via emojicode"
    });

    let user = bdo.create_user(hash, &public_bdo, &true).await?;

    // Retrieve BDO by emojicode (public BDOs only)
    let emojicode = "🌍🔑💎🌟💎🎨🐉📌"; // Example emojicode
    let response = bdo.get_bdo_by_emojicode(emojicode).await?;

    println!("Emojicode: {}", response.emojicode);
    println!("Public Key: {}", response.pub_key);
    println!("BDO: {:?}", response.bdo);
    println!("Created At: {}", response.created_at);

    Ok(())
}

Getting Public BDOs

// Get a public BDO using the pubKey parameter
let pub_key = "02a1b2c3..."; // Public key of the BDO owner
let public_user = bdo.get_public_bdo(&user_uuid, hash, pub_key).await?;

Working with Bases

Bases are Planet Nine base preferences:

use bdo_rs::Bases;
use serde_json::json;

// Get user's bases
let bases_value = bdo.get_bases(&user.uuid, hash).await?;

// Save bases
let new_bases = Bases {
    bases: json!({
        "base1": "data",
        "base2": "more_data"
    })
};
let saved_bases = bdo.save_bases(&user.uuid, hash, &new_bases).await?;

Working with Spellbooks

Spellbooks are used for the MAGIC protocol:

use bdo_rs::Spellbook;
use serde_json::json;

// Get user's spellbooks
let spellbooks = bdo.get_spellbooks(&user.uuid, hash).await?;
for spellbook in spellbooks {
    println!("Spellbook: {}", spellbook.spellbookName);
}

// Save a new spellbook
let new_spellbook = Spellbook {
    spellbookName: "MySpellbook".to_string(),
    spells: json!({
        "spell1": {
            "incantation": "abracadabra"
        }
    })
};
let updated_spellbooks = bdo.put_spellbook(&user.uuid, hash, &new_spellbook).await?;

Teleportation

The teleport feature validates teleportation tags with allyabase:// protocol support:

let teleport_url = "allyabase://some/resource";
let content = bdo.teleport(&user.uuid, hash, teleport_url).await?;
println!("Teleported content: {:?}", content);

API Reference

BDO Client

BDO::new(base_url: Option<String>, sessionless: Option<Sessionless>) -> Self

Creates a new BDO client instance.

• base_url: Optional custom base URL (defaults to https://dev.bdo.allyabase.com/)
• sessionless: Optional sessionless instance for key management (creates a new one if not provided)

create_user(&self, hash: &str, bdo: &Value, is_public: &bool) -> Result<BDOUser, Error>

Creates a new BDO user with an optional initial BDO.

update_bdo(&self, uuid: &str, hash: &str, bdo: &Value, is_public: &bool) -> Result<BDOUser, Error>

Updates or creates a BDO for an existing user.

get_bdo(&self, uuid: &str, hash: &str) -> Result<BDOUser, Error>

Retrieves a private BDO.

get_public_bdo(&self, uuid: &str, hash: &str, pub_key: &str) -> Result<BDOUser, Error>

Retrieves a public BDO using the pubKey parameter.

get_bdo_by_emojicode(&self, emojicode: &str) -> Result<EmojicodeResponse, Error>

Retrieves a public BDO by its emojicode. Returns the emojicode, public key, BDO data, and creation timestamp.

get_bases(&self, uuid: &str, hash: &str) -> Result<Value, Error>

Gets user's Planet Nine bases.

save_bases(&self, uuid: &str, hash: &str, bases: &Bases) -> Result<Value, Error>

Updates user's bases.

get_spellbooks(&self, uuid: &str, hash: &str) -> Result<Vec<Spellbook>, Error>

Gets user's spellbooks.

put_spellbook(&self, uuid: &str, hash: &str, spellbook: &Spellbook) -> Result<Vec<Spellbook>, Error>

Stores a user spellbook.

delete_user(&self, uuid: &str, hash: &str) -> Result<SuccessResult, Error>

Deletes a user account. Returns a SuccessResult indicating if the operation succeeded.

teleport(&self, uuid: &str, hash: &str, url: &str) -> Result<Value, Error>

Validates teleportation tags with allyabase:// protocol support.

Data Structures

BDOUser

pub struct BDOUser {
    pub uuid: String,
    pub bdo: Value
}

EmojicodeResponse

pub struct EmojicodeResponse {
    pub emojicode: String,
    pub pub_key: String,
    pub bdo: Value,
    pub created_at: i64
}

Spellbook

pub struct Spellbook {
    pub spellbookName: String,
    #[serde(flatten)]
    spells: serde_json::Value
}

Bases

pub struct Bases {
    pub bases: serde_json::Value
}

SuccessResult

pub struct SuccessResult {
    pub success: bool
}

Environment

By default, the client connects to the development BDO server at https://dev.bdo.allyabase.com/. To use a different environment, pass a custom base URL when creating the client:

let bdo = BDO::new(Some("https://prod.bdo.allyabase.com/".to_string()), Some(sessionless));

Testing

Run the test suite:

cargo test

License

[Your License Here]