xrpl-ruby 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e07e1a6fd2b134d36dbbdaaa977cc39e8e9176499a29e69bd84e69ddfd6f6979
-  data.tar.gz: bcca5b159608288c0cdeffc562a76332fe4e831e4dc9813676f66d46c53546ac
+  metadata.gz: cb8b3e628ddf6a9d9a7e329e6e8c51e4b0cd4f872eb609e589d78795aa9f4782
+  data.tar.gz: 2f5b18b34cb386901a8ad1a7549f7cca241facce58c0841f36a10a4c200413cc
 SHA512:
-  metadata.gz: fffeb72058c2a328c01bda6e6bfd63718147fc12326385c18c304b9d0e92013e60ba9ad11424af2ee6bd72c69e016494113db5c05ed26e10ee2501bc0873288a
-  data.tar.gz: 3aa7f43f67c50faaf0139a5f42737a35c5fd59408dc3098144a7a0b3a57bab5dad3eac3fa68fb9819749ba2dd0b7f91460de5e87899279e49b6ab07fcae87c83
+  metadata.gz: f066a56166ec0aa81ec3acb34106d504962a6e1cf2cee89eb13103719467f9ded35a34d432d9901c8a81f11b7dedc93311d8ebd184dc21564585163536e18558
+  data.tar.gz: 97397fe795b08eed3c56111b876d5476da705e2577c635f12e6aeee9ebc5ef86106fd44e525dc67c3716c11472b273bd4235764d9df2b7bf8bcc3e0d152078a7

data/CHANGELOG.md

@@ -5,6 +5,88 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.0] - 2026-09-24
+
+The codec now targets **rippled 3.4.0** (released 2026-09-17) and passes the
+ripple-binary-codec 2.11.0 fixture set: 39 transactions and 263 ledger
+entries, both directions (302 cases; 287 before). Measured before the change:
+transactions 38/39, accountState 262/263 decode.
+
+### Breaking
+
+- **`definitions.json` is rippled 3.4.0.** It is what a 3.4.0 node reports
+  through `server_definitions` (s1.ripple.com), with the node's own digest in
+  `hash`. FIELDS 381 → 357: the 27 `Hook*` fields plus `EmitGeneration` and
+  `EmittedTxn` are gone, because rippled dropped Hooks; a blob carrying one
+  of them no longer decodes. Added: `VaultKind`, `SubscriptionDate`,
+  `RedemptionDate`, `LEVersion`, `ContractResult` (LendingProtocolV1_1,
+  closed-ended vaults), and `CredentialIDs` on `VaultWithdraw` and
+  `LoanBrokerCoverWithdraw`. ripple-binary-codec's `main` additionally
+  carries four `*KeyEpoch` fields from rippled's development branch; they
+  are in no release and deliberately not here.
+- **`PermissionValue` decodes to its name.** A `DelegateSet` permission is
+  a UInt32 that rippled renders by name: a transaction type as its code plus
+  one (`"Payment"` = 1), the twelve granular permissions from 65537
+  (`"TrustlineAuthorize"`). Encoding accepts the names; they were silently
+  serialised as 0 before.
+
+### Added
+
+- **Ledger entry models** — `XRPL::LedgerEntry::AccountRoot`,
+  `::RippleState`, `::Offer` and the other 28 types, generated from
+  `LEDGER_ENTRY_FORMATS` the way the transaction models are generated from
+  `TRANSACTION_FORMATS`. `XRPL::LedgerEntry.from(node)` builds the right
+  class from anything `ledger_entry`, `account_objects` or `ledger_data`
+  returns and keeps rippled's `index` alongside. Every `lsf` flag is a
+  constant on its type. All 263 reference ledger entries round-trip through
+  their model unchanged.
+- **Flag helpers** on transactions and ledger entries: `#flag?` takes the
+  ledger's name, the constant's name or the bit, `#flag_names` lists what
+  is set.
+- **Fees by transaction type.** `autofill` now charges what rippled charges:
+  `EscrowFinish` pays for its `Fulfillment` (base × (33 + bytes / 16)),
+  `AccountDelete`, `AMMCreate` and `VaultCreate` cost the owner reserve
+  from `server_state`, a `Batch` pays two base fees plus those of its inner
+  transactions, the confidential MPT transactions cost ten base fees, and
+  multisigning adds one base fee per signature. Ordinary fees are capped at
+  2 XRP (`Client.new(url, max_fee_drops:)`); the reserve-priced types are
+  not. The rules are a pure module, `XRPL::Fee.calculate`, and the same
+  ones xrpl.js applies. Before, every transaction paid the base fee, so an
+  AccountDelete or an EscrowFinish with a fulfillment could not be
+  autofilled.
+- **Payment channel claims.** `Wallet#sign_payment_channel_claim(channel,
+  drops)` and `#verify_payment_channel_claim`, plus
+  `Wallet.verify_payment_channel_claim(..., public_key)` for the receiving
+  side; `BinaryCodec.signing_claim_data` underneath. Checked against the
+  xrpl.js signature vector byte for byte.
+- The hash prefixes for batch, counterparty and sponsor signatures
+  (`fixCleanup3_4_0`) are in `BinaryCodec::HASH_PREFIX`; the signing
+  helpers for them are not written yet.
+- `Definitions#delegatable_permissions`, and readers for the transaction
+  type, ledger entry type and result tables the codec resolves names
+  against.
+
+### Changed
+
+- `XRPL::Transaction` is built on a new `XRPL::Model` base shared with
+  `XRPL::LedgerEntry`. Its public surface is unchanged;
+  `Transaction::ValidationError` is now `Model::ValidationError`, reachable
+  under both names. A model rejects a hash whose type field contradicts the
+  class (`Payment.new('TransactionType' => 'TrustSet')`), where it used to
+  keep the foreign value and serialise a TrustSet.
+- The transaction models pick up the 3.4.0 fields without a code change:
+  `VaultCreate.new(vault_kind:, subscription_date:, redemption_date:)`.
+- A parity spec that pins `definitions.json` to the 3.4.0 digest and fails
+  if a Hook or development-branch field comes back.
+
+### Fixed
+
+- `ConfidentialOutstandingAmount` renders in base 10 like the other MPToken
+  amounts, not as a 16 digit hex string.
+- `Definitions#get_field_instance` returns `nil` for an unknown field name.
+  Serialising a hash with a foreign key now fails with "Field x is not
+  defined" instead of a `NoMethodError` on `nil`.
+
 ## [0.7.0] - 2026-08-26
 
 The binary codec now passes the full ripple-binary-codec reference fixture set

data/README.md

@@ -12,14 +12,19 @@ A pure-Ruby library to interact with the [XRP Ledger](https://xrpl.org) (XRPL) b
 ## Features
 
 - Key and wallet management (secp256k1 and ed25519)
-- Address codec and binary (transaction) codec
+- Address codec and binary codec, conformant with rippled 3.4.0 and the
+  ripple-binary-codec reference fixtures
+- Transaction and ledger entry models generated from the ledger's own
+  definitions
 - WebSocket client for the XRP Ledger public API
 - Testnet faucet helper to create and fund wallets
-- Transaction lifecycle: autofill, sign, submit, and reliable "submit and wait"
+- Transaction lifecycle: autofill with per-type fees, sign, submit, and
+  reliable "submit and wait"
+- Payment channel claims, signed and verified locally
 
 ## Requirements
 
-- Ruby 3.0 or later
+- Ruby 3.2 or later
 
 ## Installation
 
@@ -111,6 +116,55 @@ hash, which is useful for anything read back off the ledger. Note that
 `validate!` follows rippled's formats: it checks what the ledger requires for
 serialisation, which is not always what a transaction needs to be meaningful.
 
+Flags can be asked about by any of their names:
+
+```ruby
+payment.flag?(:tf_partial_payment)   # => true
+payment.flag_names                   # => ["tfPartialPayment"]
+```
+
+### Fees
+
+`autofill` sets the fee the transaction type actually needs, following the
+same rules as xrpl.js: an `EscrowFinish` pays for the size of its
+`Fulfillment`, `AccountDelete`, `AMMCreate` and `VaultCreate` cost the owner
+reserve, a `Batch` pays for its inner transactions, and multisigning adds one
+base fee per signature. Ordinary fees are capped at 2 XRP; pass
+`max_fee_drops:` to `Client.new` to change that. The rules are available on
+their own as `XRPL::Fee.calculate`.
+
+## Ledger entries
+
+The objects that make up the ledger's state - `AccountRoot`, `RippleState`,
+`Offer`, `Escrow` and the rest - have models too, generated from
+`LEDGER_ENTRY_FORMATS` the same way:
+
+```ruby
+node  = client.request_with_retry('ledger_entry', account_root: address).dig('result', 'node')
+entry = XRPL::LedgerEntry.from(node)
+
+entry.class                       # => XRPL::LedgerEntry::AccountRoot
+entry.balance                     # => "370000000"
+entry.flag?(:lsf_default_ripple)  # => true
+entry.flag_names                  # => ["lsfDefaultRipple", "lsfDisableMaster"]
+entry.index                       # the entry's hash, as rippled reports it
+```
+
+Every flag rippled defines is a constant on its type, e.g.
+`XRPL::LedgerEntry::AccountRoot::LSF_DEPOSIT_AUTH`.
+
+## Payment channel claims
+
+A claim is signed off-ledger and redeemed later with a `PaymentChannelClaim`
+transaction. Amounts are in drops:
+
+```ruby
+signature = wallet.sign_payment_channel_claim(channel_id, '1000000')
+
+# On the receiving side, against the channel's PublicKey:
+Wallet::Wallet.verify_payment_channel_claim(channel_id, '1000000', signature, public_key)
+```
+
 The client is silent by default. To see diagnostic output, pass a logger:
 
 ```ruby

data/lib/binary-codec/binary_codec.rb

@@ -6,7 +6,15 @@ module BinaryCodec
     transaction_sig: 0x53545800, # 'STX\0'
     transaction_multi_sig: 0x534D5400, # 'SMT\0'
     validation: 0x56414C00, # 'VAL\0'
-    proposal: 0x50525000 # 'PRP\0'
+    proposal: 0x50525000, # 'PRP\0'
+    payment_channel_claim: 0x434C4D00, # 'CLM\0'
+    batch: 0x42434800, # 'BCH\0'
+    # Role-specific prefixes from fixCleanup3_4_0, so a signature made for
+    # one role cannot be replayed as another.
+    counterparty_sig: 0x43505400, # 'CPT\0'
+    counterparty_multi_sig: 0x43504D00, # 'CPM\0'
+    sponsor_sig: 0x53504E00, # 'SPN\0'
+    sponsor_multi_sig: 0x53504D00 # 'SPM\0'
   }.freeze
 
   # from here: https://github.com/XRPLF/xrpl.js/blob/main/packages/ripple-binary-codec/src/binary.ts
@@ -38,6 +46,19 @@ module BinaryCodec
       st_object.from(json).to_hex
     end
 
+    # The bytes a payment channel claim is signed over: the 'CLM\0' prefix,
+    # the channel ID and the amount in drops. Same as xrpl.js
+    # encodeForSigningClaim.
+    #
+    # @param channel [String] the channel ID, 64 hex characters
+    # @param amount [String, Integer] the amount in drops
+    # @return [Array<Integer>] the signing data
+    def signing_claim_data(channel:, amount:)
+      int_to_bytes(HASH_PREFIX[:payment_channel_claim], 4) +
+        Hash256.from(channel).to_bytes +
+        Uint64.from(Integer(amount)).to_bytes
+    end
+
     # Generates signing data for a transaction.
     # @param transaction [Hash] The transaction to serialize.
     # @param prefix [Integer] The prefix to add to the serialized data.