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 exceptionNode.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 exceptionNode.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 exceptionNode.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 exceptionNode.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 storepayment_option: PaymentOption
- Payment method
Output:
Rust:
Result<(AttoTokens, ScratchpadAddress), ScratchpadError>
Python:
tuple[str, ScratchpadAddress]
(cost as string) or raises exceptionNode.js:
Promise<ScratchpadPut>
withcost: string
andaddr: ScratchpadAddress
scratchpad_create
Creates and uploads a new scratchpad to the network. Encrypts the content automatically.
Input:
owner: &SecretKey
- The owner's secret keycontent_type: u64
- Application-specific content type identifierinitial_data: &Bytes
- The initial data to storepayment_option: PaymentOption
- Payment method
Output:
Rust:
Result<(AttoTokens, ScratchpadAddress), ScratchpadError>
Python:
tuple[str, ScratchpadAddress]
(cost as string) or raises exceptionNode.js:
Promise<ScratchpadPut>
withcost: string
andaddr: ScratchpadAddress
scratchpad_update
Updates an existing scratchpad with new content. This operation is free.
Input:
owner: &SecretKey
- The owner's secret keycontent_type: u64
- Content type identifierdata: &Bytes
- The new data to store
Output:
Rust:
Result<(), ScratchpadError>
Python:
None
or raises exceptionNode.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 scratchpadowner: &SecretKey
- The owner's secret keycontent_type: u64
- Content type identifierdata: &Bytes
- The new data to store
Output:
Rust:
Result<Scratchpad, ScratchpadError>
Python:
Scratchpad
or raises exceptionNode.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 exceptionNode.js:
Promise<string>
Language-Specific Type Differences
Error Handling
Rust: Uses
Result<T, ScratchpadError>
with detailed error variantsPython: 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 costsPython: Uses
int
for content_type,str
for costsNode.js: Uses
bigint
for content_type,string
for costs
Data Types
Rust: Uses
Bytes
type for dataPython: Uses
bytes
for dataNode.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 scratchpadPay
- Payment failureGetError
- Failed to retrieve scratchpadCorrupt
- Invalid scratchpad dataSerialization
- Serialization errorScratchpadAlreadyExists
- Scratchpad already exists at addressCannotUpdateNewScratchpad
- Cannot update non-existent scratchpadScratchpadTooBig
- Exceeds maximum size (4MB)BadSignature
- Invalid signatureFork
- Multiple conflicting versions detected
Due to compatibility issues, Python and Node.js bindings simplify types (and error types to string messages within exceptions/rejections). For full experience and control it's recommended to use Rust.
Last updated