Crate xrpl_common_stdlib 

xrpl-wasm-stdlib Library

The XRPL Standard Library provides safe, type-safe access to XRPL host functions for WebAssembly smart contract development. This no_std library offers zero-cost abstractions over raw host function calls and handles memory management, error handling, and type conversions.

Quick Start

There is an interface available at https://ripple.github.io/xrpl-wasm-stdlib/ui/ for local or Devnet testing.

Examples Overview

• hello_world - Basic escrow with logging
• oracle - Price-based release using oracle data
• kyc - Credential-based verification
• notary - Multi-signature authorization
• nft_owner - NFT ownership verification
• ledger_sqn - Sequence-based release

Installation

A Smart Escrow needs two crates:

cargo add xrpl-common-stdlib xrpl-escrow-stdlib

Crate	Provides
xrpl-common-stdlib	Host bindings, transaction and ledger-object field access, and XRPL types
xrpl-escrow-stdlib	EscrowFinishContext, FinishResult, and the escrow-only host functions

Do not add xrpl-macros. It is internal, and xrpl-common-stdlib re-exports everything from it: #[smart_escrow], #[smart_contract], r_address!, hash256!, pubkey!, currency!, and blob!.

Contracts target wasm32v1-none and set crate-type = ["cdylib"]. See hello_world for a full manifest, and the Complete Developer Guide for the release profile.

Testing a contract

xrpl-stdlib-test-utils mocks the XRPL host, so you can test contract logic with cargo test — no node, no WASM. It depends on mockall, which is not no_std, so gate it to non-WASM targets:

cargo add --dev --target 'cfg(not(target_arch = "wasm32"))' xrpl-stdlib-test-utils

use xrpl_common_stdlib::types::amount::Amount;
use xrpl_stdlib_test_utils::EscrowScenario;

#[test]
fn releases_above_ten_xrp() {
    let _guard = EscrowScenario::builder()
        .with_amount(Amount::XRP { num_drops: 20_000_000 })
        .install();
    // ... call your contract's logic and assert on the result
}

Anything you leave unset gets a default. See the crate’s README for the full builder.

Documentation

Section	Description
Complete Developer Guide	Comprehensive guide with working internal links
Rust API Docs	Generated API documentation (cargo doc)

The complete developer guide includes:

• Getting Started - Installation, first contract, core concepts
• API Reference - Complete API documentation and usage patterns
• Examples - Smart escrow examples and tutorials
• Development Guide - Building, testing, and CI setup

Key Features

• Type-safe access to transaction and ledger data
• Memory-safe operations with no heap allocations
• Deterministic execution across all nodes/validators
• Zero-cost abstractions over host functions
• Comprehensive error handling with custom Result types

Safety and Constraints

Smart escrows run in a constrained WebAssembly environment:

• Read-only ledger access (except escrow data updates)
• Deterministic execution required
• Resource limits enforced
• No network/file system access

Contributing

See CONTRIBUTING.md for detailed guidelines on:

• Development setup and workflow
• Code standards and style guidelines
• Pull request process
• Testing requirements
• Release procedures

We welcome contributions of all kinds!

Modules

crypto

ctx

Smart Feature context primitives shared by all entry points.

current_tx

fields

Typed accessors for reading fields from the current transaction and ledger objects, plus the locator::Locator builder for inner field paths.

guide

Complete Developer Guide

host

Host bindings and utilities exposed to WASM smart contracts.

ledger_entry_ids

objects

Ledger-object field access.

sfield

types

Macros

blob

Converts a hex string to a compile-time [Blob<N>].

currency

Converts an XRPL currency code to a 20-byte [Currency] at compile time.

hash256

Converts a 64-character hex string to a 32-byte [Hash256] (UInt<32>) at compile time.

pubkey

Converts a 66-character hex string to a 33-byte [PublicKey] at compile time.

r_address

Converts an XRPL classic address (r-address) to a 20-byte [AccountID] at compile time.

Functions

decode_hex_20

Decode a 40-hex-character string into a 20-byte array.

decode_hex_32

Decode a 64-hex-character string into a 32-byte array.

Attribute Macros

smart_contract

Wraps a Smart Contract entry function in the appropriate extern "C" export.

smart_escrow

Wraps a Smart Escrow finish function in the extern "C" fn escrow_finish() entry point the XRPL host calls when an EscrowFinish transaction invokes the feature.