DOCSEARCHbyAlgolia
Submit Docs

xrpl.js

repository·main·Indexed 23 days ago

https://github.com/xrplf/xrpl.js

The recommended JavaScript/TypeScript library for interacting with the XRP Ledger. It allows developers to manage keys, submit transactions, observe ledger state, and subscribe to real-time updates. The library includes specialized packages for isomorphic cryptographic functions (@xrplf/isomorphic), address encoding and decoding (ripple-address-codec), and binary serialization for transactions and ledger data (ripple-binary-codec).

Tokens
19.6K
Snippets
46
Records
127
Agent score
79%

What's inside xrpl.js

  1. Overview of @xrplf/isomorphic

    main
    @xrplf/isomorphic is a collection of isomorphic implementations of cryptographic and utility functions. It is designed to work in both browser and Node.js environments. Browser implementations of cryptographic functions utilize @noble/hashes, while Node.js implementations use the native crypto module.

  2. Use ripple-binary-codec for XRPL transaction serialization

    main
    The ripple-binary-codec library provides tools to serialize and deserialize transactions according to the XRP Ledger (XRPL) protocol. Use this library when you need to convert transaction objects into the specific binary format required by the network or decode binary data back into usable transaction objects.

  3. Core Features of xrpl.js

    main

    The xrpl.js library provides several key capabilities for interacting with the XRP Ledger:

    • Key Management: Managing keys and creating test credentials using Wallet and Client.fundWallet().
    • Transaction Submission: Submitting transactions to the ledger via Client.submit().
    • Ledger Observation: Sending requests to observe the ledger using Client.request() and public API methods.
    • Subscriptions: Subscribing to real-time changes in the ledger (e.g., transactions, ledger updates).
    • Data Parsing: Converting ledger data into convenient formats using utilities like xrpToDrops and rippleTimeToISOTime.

    The library is compatible with Node.js (v20+ recommended) and web browsers (tested in Chrome).

  4. Explore applications using xrpl.js

    main
    The xrpl.js library is used across a wide variety of XRP Ledger (XRPL) ecosystem applications, including exchanges, explorers, wallets, and development tools. This list serves as a reference for real-world implementations and potential integration patterns.

  5. How hash functions work in @xrplf/isomorphic

    main

    All hash functions in this package (such as sha256, sha512, and ripemd160) follow a consistent pattern. They can be used in two ways:

    1. Direct Call: Pass a Uint8Array or a string directly to the function. If a string is provided, it is converted to a Uint8Array via UTF-8 encoding (not hex). The function returns a Uint8Array.
    2. Streaming/Incremental via .create(): Use the .create() method to get a Hash subclass instance. This allows you to incrementally add data using .update() and finalize the hash using .digest(). Once .digest() is called, the instance can no longer be used.

    Supported hash modules include:

    • @xrplf/isomorphic/ripemd160
    • @xrplf/isomorphic/sha256
    • @xrplf/isomorphic/sha512
    // Direct call
const hashA = sha256('abc');

// Incremental usage
const hashB = sha256
  .create()
  .update(Uint8Array.from([1, 2, 3]))
  .digest();

  6. Understand Serialization Field (SField) properties

    main

    The ripple-binary-codec uses definitions to manage how fields are serialized. Key properties for a field include:

    • Key: The string identifier (e.g., "LedgerEntry", "Transaction").
    • nth: A sort code used to construct a unique Field ID. This ensures deterministic ordering of fields that share the same data type.
    • isVLEncoded: A boolean indicating if the field is Variable Length encoded (length-prefixed). Examples include STI_VL/Blob, STI_ACCOUNT/AccountID, and STI_VECTOR256/Vector256.
    • isSerialized: Indicates if the field should be included in the serialized blob. Fields that are not SFields or are not in the exclusion list are serialized.
    • isSigningField: Indicates if the field is part of the transaction signing payload. This is true unless explicitly marked as SField::notSigning.

  7. Replace Buffer with Uint8Array

    main
    In xrpl.js 3.0, Buffer has been replaced with Uint8Array because Buffer is not native to browsers. Since Buffer is a subclass of Uint8Array, you can often replace Buffer instances with Uint8Array directly. However, you must be aware that Uint8Array does not possess the additional helper functions that Buffer provides. You may need to update your code where you rely on specific Buffer methods.

  8. Handle currency code encoding and decoding

    main

    The library follows specific rules for XRPL currency codes:

    Encoding

    • Currency codes must be exactly 3 ASCII characters.
    • The library allows any 3-character ASCII string to be encoded, though the rippled server may enforce stricter rules.

    Decoding

    • If a currency code matches the regex /^[A-Z0-9]{3}$/ (three uppercase letters or numbers), it is decoded as a standard ISO 4217 or pseudo-ISO currency string.
    • If the code does not match this regex (e.g., it contains lowercase letters like aBC), it is treated as a non-ISO currency and returned as a 160-bit hex-string (40 hex characters).

  9. Migrate from `Buffer` to `Uint8Array` in xrpl.js 3.0

    main

    In version 3.0, Buffer has been replaced by Uint8Array. While Buffer is a subclass of Uint8Array and can often be used as a parameter, many methods that previously returned Buffer now return Uint8Array. You must update your code to handle Uint8Array and use its specific syntax for conversions.

    Affected packages and methods:

    ripple-address-codec

    • decodeAccountID, encodeAccountID, decodeAccountPublic, encodeAccountPublic, decodeNodePublic, encodeNodePublic, encodeSeed, decodeXAddress, encodeXAddress

    ripple-binary-codec

    • SerializedType constructor and .toBytes() (including subclasses like AccountID, Amount, Blob, Currency, Hash, Hash128, Hash160, Hash256, Issue, PathSet, STArray, STObject, UInt, UInt8, UInt16, UInt32, UInt64, Vector256, XChainBridge)
    • ShaMapNode.hashPrefix
    • BinarySerializer.put
    • BytesList.put and BytesList.toBytes
    • BinaryParser.read and BinaryParser.readVariableLength
    • Quality.encode and Quality.decode
    • Sha512Half.put and Sha512Half.finish256
    • transactionID, sha512Half, signingClaimData, serializeObject, makeParser
    • FieldInstance.header, Bytes.bytes, and HashPrefix entries

    secret-numbers

    • entropyToSecret, randomEntropy, and the Account constructor

    xrpl

    • rfc1751MnemonicToKey

  10. Integrate with XRPL wallets and dApp gateways

    main

    If you are building decentralized applications (dApps) on the XRP Ledger, you can integrate with existing self-custody wallets and gateways that support XRPL interactions:

    • Joey Wallet: A secure, self-custody gateway to Web3 dApps. Documentation: https://docs.joeywallet.xyz/.
    • Crossmark Wallet: A browser-first, self-custodial wallet. Documentation: https://docs.crossmark.io/.
    • GemWallet: A non-custodial web extension for browser-based XRPL interactions. Documentation: https://gemwallet.app/.
    • XUMM: A platform for developers to build applications that allow users to track accounts and transactions.

  11. Sign a transaction using hashTx

    main

    To single-sign a transaction, you must follow these steps:

    1. Encode: Convert the transaction from JSON format (txJSON) into the XRP Ledger's binary format.
    2. Hash: Hash the binary data using the appropriate prefix. For single-signing, the prefix is 0x53545800. For multi-signing, the prefix is 0x534D5400.
    3. Sign: Perform the cryptographic signing.
    4. Re-serialize: Include the TxnSignature field in the final serialized transaction.

    The hashTx method automates step 2 by automatically applying the 0x53545800 prefix required for single-signing.