Crate inf_circle_sdk 

Circle Rust SDK

A comprehensive Rust SDK for Circle’s Web3 Services API, designed with a clean separation between write (CircleOps) and read (CircleView) operations.

Architecture

The SDK provides two main clients:

• CircleOps: Handles all write operations (POST, PUT, PATCH) that require entity-level authentication. Uses an entity secret to sign requests.
• CircleView: Handles all read operations (GET) that only require API key authentication.

This separation ensures that read-only processes don’t require access to sensitive entity secrets, enhancing security and simplifying access control.

Features

• ✅ Clean Separation: Write operations require entity secret, reads only need API key
• ✅ Async First: Built on tokio for high-performance async I/O
• ✅ Type Safety: Strongly typed request/response structures prevent common errors
• ✅ Fluent Builders: Easy-to-use builders for complex API requests
• ✅ Comprehensive Error Handling: Detailed error types with helpful messages
• ✅ Developer Wallets: Create, manage, and transact with developer-controlled wallets
• ✅ Smart Contracts: Deploy, import, query, and interact with smart contracts
• ✅ Event Monitoring: Create monitors for contract events and retrieve event logs
• ✅ Webhook Support: Subscribe to and manage webhook notifications

Quick Start

Environment Setup

Create a .env file in your project root:

CIRCLE_BASE_URL="https://api.circle.com"
CIRCLE_API_KEY="YOUR_API_KEY"
CIRCLE_ENTITY_SECRET="YOUR_ENTITY_SECRET_HEX"
CIRCLE_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
CIRCLE_WALLET_SET_ID="YOUR_WALLET_SET_ID"

Create a Wallet

use inf_circle_sdk::{
    circle_ops::circler_ops::CircleOps,
    dev_wallet::{dto::AccountType, ops::create_dev_wallet::CreateDevWalletRequestBuilder},
    types::Blockchain,
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let ops = CircleOps::new(None)?;
    let wallet_set_id = std::env::var("CIRCLE_WALLET_SET_ID")?;

    let builder = CreateDevWalletRequestBuilder::new(
        wallet_set_id,
        vec![Blockchain::EthSepolia]
    )?
    .account_type(AccountType::Sca)
    .count(1)
    .build();

    let response = ops.create_dev_wallet(builder).await?;
    println!("Created wallet: {}", response.wallets[0].address);
    Ok(())
}

Query Wallet Balance

use inf_circle_sdk::{
    circle_view::circle_view::CircleView,
    dev_wallet::views::query::QueryParamsBuilder,
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let view = CircleView::new()?;
     
    let params = QueryParamsBuilder::new().build();
    let balances = view.get_token_balances("wallet-id", params).await?;
     
    for balance in balances.token_balances {
        println!("{}: {}", balance.token.symbol.unwrap_or_default(), balance.amount);
    }
    Ok(())
}

Transfer Tokens

use inf_circle_sdk::{
    circle_ops::circler_ops::CircleOps,
    dev_wallet::{
        dto::FeeLevel,
        ops::create_transfer_transaction::CreateTransferTransactionRequestBuilder,
    },
    types::Blockchain,
};
use uuid::Uuid;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let ops = CircleOps::new(None)?;

    let builder = CreateTransferTransactionRequestBuilder::new()
        .wallet_id("wallet-id".to_string())
        .destination_address("0x1234...".to_string())
        .amounts(vec!["0.1".to_string()])
        .blockchain(Blockchain::EthSepolia)
        .fee_level(FeeLevel::Medium)
        .idempotency_key(Uuid::new_v4().to_string())
        .build();

    let response = ops.create_dev_transfer_transaction(builder).await?;
    println!("Transaction ID: {}", response.id);
    Ok(())
}

Examples

The examples/ directory contains comprehensive examples for all major features:

• circle_ops_example.rs: Wallet creation
• transfer_transaction_example.rs: Native and ERC-20 token transfers
• contract_interaction_example.rs: Execute contract functions
• deploy_contract_example.rs: Deploy custom contracts
• create_event_monitor_example.rs: Monitor contract events
• sign_message_example.rs: Sign messages and typed data
• transaction_management_example.rs: Cancel and accelerate transactions

Run any example with:

cargo run --example circle_ops_example

Module Organization

• circle_ops: Write operations requiring entity secret authentication
• circle_view: Read operations requiring only API key
• dev_wallet: Developer-controlled wallet operations and views
• contract: Smart contract deployment, import, and interaction
• types: Common types used across the SDK (blockchains, etc.)
• helper: Utility functions and error handling

Error Handling

The SDK uses a custom CircleError type for comprehensive error reporting:

match ops.create_dev_wallet(builder).await {
    Ok(response) => println!("Success!"),
    Err(e) => eprintln!("Error: {}", e),  // Detailed error message
}

Testing

See TESTING.md for comprehensive testing guide.

Re-exports

pub use helper::encrypt_entity_secret;

pub use helper::CircleError;

pub use helper::CircleResult;

Modules

circle_ops

circle_view

contract

Smart contract operations

dev_wallet

Developer-controlled wallet operations

helper

Shared helper functions and types used across the SDK

near

NEAR Protocol Support

types

Common types used across the SDK

Structs

Uuid

A Universally Unique Identifier (UUID).

Traits

Deserialize

A data structure that can be deserialized from any data format supported by Serde.

Serialize

A data structure that can be serialized into any data format supported by Serde.

Derive Macros

Deserialize

Serialize