Scratchpad

Scratchpad is a native data type in the Autonomi Network:

  • Key-addressed: Network address is derived from a BLS public key

  • Size: Up to 4MB mutable storage

  • Pay-once, free updates: Unlimited updates for free after initial payment

  • Versioned & signed: Includes a version counter and cryptographically verifiable signatures

  • Encrypted: Content is automatically encrypted with the owner's key

Client Methods

scratchpad_get_from_public_key

Retrieves a scratchpad from the network using the owner's public key.

Input:

  • public_key: &PublicKey - The owner's public key

Output:

  • Rust: Result<Scratchpad, ScratchpadError>

  • Python: Scratchpad or raises exception

  • Node.js: Promise<Scratchpad>

scratchpad_get

Retrieves a scratchpad from the network by its address.

Input:

  • address: &ScratchpadAddress - The scratchpad address

Output:

  • Rust: Result<Scratchpad, ScratchpadError>

  • Python: Scratchpad or raises exception

  • Node.js: Promise<Scratchpad>

scratchpad_check_existence

Checks if a scratchpad exists on the network. Much faster than scratchpad_get.

Input:

  • address: &ScratchpadAddress - The scratchpad address

Output:

  • Rust: Result<bool, ScratchpadError>

  • Python: bool or raises exception

  • Node.js: Promise<boolean>

scratchpad_verify

Verifies a scratchpad's signature and size constraints.

Input:

  • scratchpad: &Scratchpad - The scratchpad to verify

Output:

  • Rust: Result<(), ScratchpadError>

  • Python: None or raises exception

  • Node.js: void (throws on error)

scratchpad_put

Manually uploads a scratchpad to the network. Requires the scratchpad to be already created and signed.

Input:

  • scratchpad: Scratchpad - The scratchpad to store

  • payment_option: PaymentOption - Payment method

Output:

  • Rust: Result<(AttoTokens, ScratchpadAddress), ScratchpadError>

  • Python: tuple[str, ScratchpadAddress] (cost as string) or raises exception

  • Node.js: Promise<ScratchpadPut> with cost: string and addr: ScratchpadAddress

scratchpad_create

Creates and uploads a new scratchpad to the network. Encrypts the content automatically.

Input:

  • owner: &SecretKey - The owner's secret key

  • content_type: u64 - Application-specific content type identifier

  • initial_data: &Bytes - The initial data to store

  • payment_option: PaymentOption - Payment method

Output:

  • Rust: Result<(AttoTokens, ScratchpadAddress), ScratchpadError>

  • Python: tuple[str, ScratchpadAddress] (cost as string) or raises exception

  • Node.js: Promise<ScratchpadPut> with cost: string and addr: ScratchpadAddress

scratchpad_update

Updates an existing scratchpad with new content. This operation is free.

Input:

  • owner: &SecretKey - The owner's secret key

  • content_type: u64 - Content type identifier

  • data: &Bytes - The new data to store

Output:

  • Rust: Result<(), ScratchpadError>

  • Python: None or raises exception

  • Node.js: Promise<void>

scratchpad_update_from

Updates an existing scratchpad from a specific scratchpad instance. Used internally by scratchpad_update.

Input:

  • current: &Scratchpad - The current scratchpad

  • owner: &SecretKey - The owner's secret key

  • content_type: u64 - Content type identifier

  • data: &Bytes - The new data to store

Output:

  • Rust: Result<Scratchpad, ScratchpadError>

  • Python: Scratchpad or raises exception

  • Node.js: Not directly exposed

scratchpad_cost

Estimates the storage cost for a new scratchpad.

Input:

  • owner: &PublicKey - The owner's public key

Output:

  • Rust: Result<AttoTokens, CostError>

  • Python: str (cost as string) or raises exception

  • Node.js: Promise<string>

Language-Specific Type Differences

Error Handling

  • Rust: Uses Result<T, ScratchpadError> with detailed error variants

  • Python: Raises exceptions with simplified error messages as strings

  • Node.js: Uses Promise rejection with Error objects containing simplified messages

Numeric Types

  • Rust: Uses u64 for content_type, AttoTokens for costs

  • Python: Uses int for content_type, str for costs

  • Node.js: Uses bigint for content_type, string for costs

Data Types

  • Rust: Uses Bytes type for data

  • Python: Uses bytes for data

  • Node.js: Uses Buffer for data

Examples

use autonomi::{Client, SecretKey, AttoTokens, Bytes};
use autonomi::client::payment::PaymentOption;

async fn scratchpad_example() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize client and wallet
    let client = Client::init_local().await?;
    let wallet = get_funded_wallet();
    let payment = PaymentOption::from(&wallet);

    // Create secret key for scratchpad
    let key = SecretKey::random();
    let public_key = key.public_key();
    
    // Check cost
    let cost = client.scratchpad_cost(&public_key).await?;
    println!("Scratchpad cost: {}", cost);

    // Create scratchpad
    let content_type = 42;
    let initial_data = Bytes::from("Hello, Autonomi!");
    let (cost, addr) = client
        .scratchpad_create(&key, content_type, &initial_data, payment.clone())
        .await?;
    println!("Created at {:?}, cost: {}", addr, cost);

    // Get scratchpad
    let scratchpad = client.scratchpad_get(&addr).await?;
    assert_eq!(scratchpad.counter(), 0);
    
    // Decrypt content
    let decrypted = scratchpad.decrypt_data(&key)?;
    assert_eq!(decrypted, initial_data);

    // Update scratchpad
    let new_data = Bytes::from("Updated content!");
    client.scratchpad_update(&key, content_type, &new_data).await?;

    // Get updated scratchpad
    let updated = client.scratchpad_get(&addr).await?;
    assert_eq!(updated.counter(), 1);
    let updated_content = updated.decrypt_data(&key)?;
    assert_eq!(updated_content, new_data);

    Ok(())
}

Error Handling

Rust Errors

The ScratchpadError enum provides detailed error variants:

  • PutError - Failed to store scratchpad

  • Pay - Payment failure

  • GetError - Failed to retrieve scratchpad

  • Corrupt - Invalid scratchpad data

  • Serialization - Serialization error

  • ScratchpadAlreadyExists - Scratchpad already exists at address

  • CannotUpdateNewScratchpad - Cannot update non-existent scratchpad

  • ScratchpadTooBig - Exceeds maximum size (4MB)

  • BadSignature - Invalid signature

  • Fork - Multiple conflicting versions detected

Last updated