xrpl-ruby 0.6.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b0269ba7fe6c319fca687c0a063389a358260f4c84bb5ae293f1fb6f8215b0f
-  data.tar.gz: ca8099d5daaa7f3b4e3c89cd3ea13870da4f15b60cbaeb08809edb36547121f3
+  metadata.gz: cb8b3e628ddf6a9d9a7e329e6e8c51e4b0cd4f872eb609e589d78795aa9f4782
+  data.tar.gz: 2f5b18b34cb386901a8ad1a7549f7cca241facce58c0841f36a10a4c200413cc
 SHA512:
-  metadata.gz: a63151ad5c6885136417783f1234d6af8e32ea8346ce514430c8c65458dae0a0917cae0f8c2f1f7111c623e7e8098cc0b96643fbebbfd60554cd86f9c3cbd847
-  data.tar.gz: f32401a94218f1ae9621c4ba21f64c994b08f3d3128f2e2b159175c2aad195d8f7050ca094454ad084ad5c4aef80a9e71750401462a541b1f346b12bb581a05b
+  metadata.gz: f066a56166ec0aa81ec3acb34106d504962a6e1cf2cee89eb13103719467f9ded35a34d432d9901c8a81f11b7dedc93311d8ebd184dc21564585163536e18558
+  data.tar.gz: 97397fe795b08eed3c56111b876d5476da705e2577c635f12e6aeee9ebc5ef86106fd44e525dc67c3716c11472b273bd4235764d9df2b7bf8bcc3e0d152078a7

data/CHANGELOG.md

@@ -5,6 +5,161 @@ 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
+(287 cases, both directions). It previously passed none of them on decode: the
+fixtures had been vendored in `spec/binary-codec/fixtures/` for a long time
+without any spec loading them, so the suite reported green while decoding
+0 of 261 ledger objects.
+
+### Breaking
+
+- **`binary_to_json` returns different types.** UInt8/16/32 fields come back as
+  numbers instead of zero-padded hex strings (`Sequence` is `1`, not
+  `"00000001"`), and native XRP amounts come back as strings instead of
+  integers (`Balance` is `"370000000"`, not `370000000`). This is what rippled
+  itself returns; the previous output matched no implementation.
+- **`STObject#to_json` returns a Hash**, not a JSON string. The string return
+  forced every nested value through a parse on the way out, which is what
+  turned native amounts into integers.
+- **Malformed input raises.** `STObject#to_json` and `STArray#to_json` caught
+  every parser error and returned a partially decoded object. A codec that
+  silently drops fields is worse than one that fails, so the rescues are gone.
+- `tecHOOK_REJECTED` is no longer a known transaction result. It is a Xahau
+  code and never belonged in the XRP Ledger definitions.
+
+### Added
+
+- **Transaction models** — `XRPL::Transaction::Payment`, `::EscrowCreate` and
+  80 more, generated at load time from `TRANSACTION_FORMATS` so they cannot
+  drift from the definitions. Fields are written in snake_case and stored under
+  the ledger's own names; `#validate!` reports missing required fields before a
+  round trip is spent, and each type carries its flags as constants
+  (`Payment::TF_PARTIAL_PAYMENT`). A plain Hash still works everywhere a
+  transaction is accepted.
+- **`BinaryCodec::Number`** — the STNumber type (12 bytes: int64 mantissa,
+  int32 exponent). 17 serialised fields reference it — the Vault and Lending
+  Protocol amounts — and no class existed, so those fields could not be
+  encoded at all. The gap predates this release.
+- **`Issue` supports MPT** (`mpt_issuance_id`), in both directions.
+- **Conformance spec** running `codec-fixtures.json`, and a definitions spec
+  that checks every type a serialised field uses resolves to a class.
+
+### Changed
+
+- **`definitions.json` synced verbatim with XRPLF.** FIELDS 343 → 381,
+  TRANSACTION_TYPES 76 → 83, LEDGER_ENTRY_TYPES 31 → 32, TRANSACTION_RESULTS
+  189 → 195. Adds the Sponsorship and Confidential MPT fields and transactions,
+  `TakerGetsMPT`, `TakerPaysMPT` and `ReferenceHolding`. Renames `UInt384`/
+  `UInt512` to `Hash384`/`Hash512` and `MutableFlags` to `ImmutableFlags`; the
+  type map keeps the old names resolving.
+- `Client#autofill`, `#submit` and `#submit_and_wait` accept a transaction
+  model as well as a Hash.
+- The gemspec packages everything under `lib/`, not only the `.rb` files. Data
+  files previously needed an entry of their own, and a forgotten one would have
+  broken the installed gem while every local run stayed green, because the
+  working copy has the file either way. `spec/packaging_spec.rb` checks it now.
+
+### Fixed
+
+- **`Issue` read a fixed 40 bytes.** An XRP issue is 20, so the rest came out
+  of the following field: `Asset` and `Asset2` decoded as `nil` and
+  `IssuingChainDoor` as the zero account.
+- **`STArray.from_parser` dropped the ArrayEndMarker** it is meant to restore.
+  The reconstructed bytes had no terminator, so re-parsing them ran the array
+  on into the fields that followed — `AMMBid` lost `Asset` and `Asset2` into
+  `AuthAccounts`.
+- **`Currency#to_json` took no arguments** while every type is called as
+  `to_json(definitions, field_name)`. It raised `ArgumentError` for every
+  nested Currency field, which the silent rescue then swallowed — that is how
+  `BaseAsset` and `QuoteAsset` disappeared from `PriceDataSeries`.
+- **`XChainBridge` omitted the `0x14` length prefix** before each account,
+  which is why all eight XChain fixtures failed to serialise.
+- **A zero IOU rendered as `"-0"`** instead of `"0"`.
+
 ## [0.6.1] - 2026-08-12
 
 ### Added

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
 
@@ -69,6 +74,97 @@ puts result.dig('result', 'meta', 'TransactionResult') # => "tesSUCCESS"
 client.disconnect
 ```
 
+## Transactions
+
+A transaction can always be a plain Hash, as above. The transaction classes
+are an addition on top of that: they are generated from the field formats in
+`definitions.json`, so they know which fields a type accepts, which of them
+are required, and what its flags are called.
+
+```ruby
+payment = XRPL::Transaction::Payment.new(
+  account:     wallet.classic_address,
+  destination: receiver.classic_address,
+  amount:      '1000000',
+  flags:       XRPL::Transaction::Payment::TF_PARTIAL_PAYMENT
+)
+
+payment.validate!   # raises before a round trip is spent
+client.submit_and_wait(payment, wallet: wallet)
+```
+
+Fields are written in snake_case and stored under the ledger's own names, so
+`#to_h` produces exactly what the binary codec expects:
+
+```ruby
+payment.to_h
+# => {"TransactionType"=>"Payment", "Account"=>"r...", "Destination"=>"r...",
+#     "Amount"=>"1000000", "Flags"=>131072}
+```
+
+A field the type does not define is rejected when it is set, rather than by
+the server several seconds later:
+
+```ruby
+payment.limit_amount = {}   # NoMethodError
+XRPL::Transaction::Payment.new(limit_amount: {})
+# => XRPL::Transaction::ValidationError: Payment has no field LimitAmount
+```
+
+`XRPL::Transaction.from(hash)` builds the matching class from a transaction
+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.