xrpl.js icon indicating copy to clipboard operation
xrpl.js copied to clipboard
verified publisher icon XRPLF

Add support for lending protocol xls-66d

Open Patel-Raj11 opened this issue 1 month ago • 1 comments

High Level Overview of Change

Add support for Lending Protocol XLS-66d.

Context of Change

Type of Change

  • [ ] Bug fix (non-breaking change which fixes an issue)
  • [x] New feature (non-breaking change which adds functionality)
  • [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • [ ] Refactor (non-breaking change that only restructures code)
  • [x] Tests (You added tests for code that already exists, or your new feature included in this PR)
  • [ ] Documentation Updates
  • [ ] Release

Did you update HISTORY.md?

  • [x] Yes
  • [ ] No, this change does not impact library users

Test Plan

Added unit and integration tests

Patel-Raj11 avatar Dec 03 '25 22:12 Patel-Raj11

Walkthrough

This pull request introduces comprehensive Lending Protocol support to the XRPL JavaScript libraries, adding nine new transaction types (LoanSet, LoanPay, LoanDelete, LoanManage, LoanBrokerSet, LoanBrokerDelete, LoanBrokerCoverDeposit, LoanBrokerCoverWithdraw, LoanBrokerCoverClawback), two new ledger entry types (Loan, LoanBroker), validators, hash utilities, and integration tests. Additionally, codec support for multisigning with non-empty SigningPubKey is enabled, and amendment configuration is updated.

Changes

Cohort / File(s) Summary
Amendment Configuration
\.ci-config/rippled\.cfg		 Added LendingProtocol and PermissionDelegationV1_1 to the [features] amendments list
Release Notes
packages/ripple-binary-codec/HISTORY\.md, packages/xrpl/HISTORY\.md		 Updated HISTORY files to document new Lending Protocol support and Vault field optionality changes
Binary Codec Definitions
packages/ripple-binary-codec/src/enums/definitions\.json		 Removed 13 deprecated transaction result codes (tecXCHAIN_\, tefPAST_SEQ, tefTOO_BIG, tefWRONG_PRIOR, telNO_DST_PARTIAL, telWRONG_NETWORK, temXCHAIN_\, terPRE_TICKET, terQUEUED, terRETRY)
Ledger Entry Types
packages/xrpl/src/models/ledger/Loan\.ts, packages/xrpl/src/models/ledger/LoanBroker\.ts		 Added Loan ledger entry with comprehensive fields and LoanFlags enum; added LoanBroker ledger entry with debt and cover management fields
Ledger Entry Registration
packages/xrpl/src/models/ledger/LedgerEntry\.ts, packages/xrpl/src/models/ledger/index\.ts		 Extended LedgerEntry and LedgerEntryFilter unions to include Loan and LoanBroker types; exported new types from index
Transaction Type: LoanSet
packages/xrpl/src/models/transactions/loanSet\.ts		 Added LoanSet transaction model with CounterpartySignature interface, LoanSetFlags enum, and comprehensive validation for loan origination parameters and bounds checking
Transaction Types: LoanBroker Operations
packages/xrpl/src/models/transactions/loanBroker(Set|Delete|CoverDeposit|CoverWithdraw|CoverClawback)\.ts		 Added five loan broker transaction models (LoanBrokerSet, LoanBrokerDelete, LoanBrokerCoverDeposit, LoanBrokerCoverWithdraw, LoanBrokerCoverClawback) with validators enforcing ledger entry ID format and amount/field constraints
Transaction Types: Loan Management
packages/xrpl/src/models/transactions/loan(Delete|Manage|Pay)\.ts		 Added three loan management transaction models (LoanDelete, LoanManage with LoanManageFlags enum, LoanPay) with validators ensuring valid LoanID format and flag mutual exclusivity where applicable
Transaction Utilities
packages/xrpl/src/models/transactions/common\.ts		 Added validation helpers (isTokenAmount, isLedgerEntryId, validateHexMetadata) and constant SHA_512_HALF_LENGTH for ledger entry validation
Transaction Registration
packages/xrpl/src/models/transactions/index\.ts, packages/xrpl/src/models/transactions/transaction\.ts		 Exported all new loan transaction types and their validators; extended SubmittableTransaction union and validation switch to handle nine new transaction types
Hash Utilities
packages/xrpl/src/utils/hashes/ledgerSpaces\.ts, packages/xrpl/src/utils/hashes/index\.ts, packages/xrpl/src/utils/index\.ts		 Added three new hash functions (hashVault, hashLoanBroker, hashLoan) and corresponding ledger space mappings (vault: 'V', loanBroker: 'l', loan: 'L')
Codec Multisigning
packages/ripple-binary-codec/src/index\.ts		 Removed runtime validation check preventing encodeForMultisigning from working with non-empty SigningPubKey fields
Sugar Functions & Utilities
packages/xrpl/src/sugar/autofill\.ts, packages/xrpl/src/models/utils/flags\.ts		 Added counterparty signer count retrieval for LoanSet autofill fee calculation; integrated LoanManageFlags into transaction-to-flags mapping
Unit Tests: Transaction Validation
packages/xrpl/test/models/loanBroker(CoverClawback|CoverDeposit|CoverWithdraw|Delete|Set)\.test\.ts, packages/xrpl/test/models/loan(Delete|Manage|Pay)\.test\.ts		 Added comprehensive validation tests for all nine new transaction types, verifying field presence, format constraints, and error messaging
Unit Tests: Hash Utilities
packages/xrpl/test/utils/hashes\.test\.ts, packages/ripple-binary-codec/test/signing-data-encoding\.test\.ts		 Added test cases for new hash functions (hashVault, hashLoanBroker, hashLoan) and multisigning with non-empty SigningPubKey
Integration Tests
packages/xrpl/test/integration/transactions/lendingProtocol\.test\.ts		 Added comprehensive end-to-end test covering vault creation, MPT issuance, loan broker setup, multi-signed LoanSet, loan payments, and lifecycle operations (cover deposits/withdrawals, impairment, deletion)
Vault & Amendment Tests
packages/xrpl/test/integration/requests/vaultInfo\.test\.ts, packages/xrpl/test/integration/transactions/singleAssetVault\.test\.ts, packages/xrpl/test/integration/transactions/delegateSet\.test\.ts, packages/xrpl/test/client/autofill\.test\.ts		 Updated vault tests to handle optional AssetsTotal/AssetsAvailable; removed explicit Fee fields; removed amendment checks and updated error codes for delegateSet; added LoanSet autofill test

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45–60 minutes

Areas requiring extra attention:

  • LoanSet validator and multisigning flow: Complex validation with 20+ numeric range checks, required/optional field combinations, and PaymentInterval/GracePeriod constraints; interaction with CounterpartySignature and encodeForMultisigning changes requires careful verification
  • Transaction union expansion and validator dispatch: Nine new transaction types added to SubmittableTransaction union and validation switch; ensure all types are correctly routed to validators and no conflicts with existing types
  • Hash utility implementations: New hash functions for vault, loan broker, and loan entries must follow ledger space semantics correctly (ledger space prefixes concatenated with address/ID and padded sequence)
  • Integration test multisigning assembly: Multi-signer sorting, signature assembly, and counterparty validation logic in lendingProtocol.test.ts is intricate and critical for correctness
  • Codec breaking change: Removal of SigningPubKey validation in encodeForMultisigning enables LoanSet multisigning but must not inadvertently break other transaction types

Possibly related PRs

  • XRPLF/xrpl.js#3153: Marks AssetsAvailable, AssetsTotal, and LossUnrealized as optional on Vault objects, directly related to vault field handling in this PR
  • XRPLF/xrpl.js#3128: Updates amendment configuration (LendingProtocol, PermissionDelegationV1_1) mirroring .ci-config/rippled.cfg changes
  • XRPLF/xrpl.js#2690: Refactors transaction type generation and SubmittableTransaction updates, providing foundational patterns for nine new transaction type additions

Suggested reviewers

  • achowdhry-ripple
  • ckeshava
  • khancode
  • mvadari

Poem

🐰 A rabbit's ode to lending dreams,
With brokers, loans, and ledger schemes,
From vaults of hash to signatures so keen,
The Lending Protocol is here—a lending machine!
Multi-signers hopping in a row,
Watching assets ebb and flow! 🌙✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly and concisely summarizes the main change: adding support for the lending protocol XLS-66d, which is the primary objective of this pull request.
Description check ✅ Passed The description follows the template structure with High Level Overview, Context, Type of Change selections, and HISTORY.md confirmation. However, the Context section is empty and Test Plan section only contains minimal information.
Docstring Coverage ✅ Passed Docstring coverage is 92.59% which is sufficient. The required threshold is 80.00%.
✨ Finishing touches
  • [ ] 📝 Generate docstrings
🧪 Generate unit tests (beta)
  • [ ] Create PR with unit tests
  • [ ] Post copyable unit tests in a comment
  • [ ] Commit unit tests in branch lending-protocol-xls-66d
📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 091680c7d1f7d8e2df467d84bf64177bd637b874 and ef9328ea19039f385e6768e6224ae27854d218b4.

📒 Files selected for processing (2)
  • .ci-config/rippled.cfg (1 hunks)
  • packages/xrpl/test/integration/transactions/delegateSet.test.ts (2 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
  • .ci-config/rippled.cfg
🧰 Additional context used
🧠 Learnings (6)
📓 Common learnings 
Learnt from: ckeshava
Repo: XRPLF/xrpl.js PR: 2874
File: packages/xrpl/test/integration/transactions/permissionedDomain.test.ts:25-80
Timestamp: 2025-01-08T02:12:28.489Z
Learning: The rippled C++ implementation (PR #5161) includes comprehensive test coverage for PermissionedDomain (XLS-80d) error cases. The JS SDK tests focus on the happy path since the error cases are already validated at the rippled level, following the principle of not duplicating complex validation testing across SDK implementations.

Learnt from: shawnxie999
Repo: XRPLF/xrpl.js PR: 2661
File: packages/xrpl/test/integration/transactions/mptokenAuthorize.test.ts:29-118
Timestamp: 2024-12-06T19:25:15.376Z
Learning: In the XRPLF/xrpl.js TypeScript client library, when writing tests (e.g., in `packages/xrpl/test/integration/transactions/`), we generally do not need to test rippled server behaviors, because those behaviors are covered by rippled's own integration and unit tests.

Learnt from: ckeshava
Repo: XRPLF/xrpl.js PR: 2873
File: packages/xrpl/test/integration/transactions/trustSet.test.ts:0-0
Timestamp: 2025-01-31T17:46:25.375Z
Learning: For the XRPL implementation, extensive test cases for deep freeze behavior (high/low side interactions, clearing flags, etc.) are maintained in the C++ implementation and don't need to be duplicated in the JavaScript implementation.
📚 Learning: 2024-12-06T18:44:55.095Z 
Learnt from: shawnxie999
Repo: XRPLF/xrpl.js PR: 2661
File: packages/xrpl/test/models/MPTokenAuthorize.test.ts:60-71
Timestamp: 2024-12-06T18:44:55.095Z
Learning: In the XRPL.js library's TypeScript test file `packages/xrpl/test/models/MPTokenAuthorize.test.ts`, negative test cases for invalid `Account` address format, invalid `Holder` address format, invalid `MPTokenIssuanceID` format, and invalid flag combinations are not necessary.

Applied to files:

  • packages/xrpl/test/integration/transactions/delegateSet.test.ts
📚 Learning: 2024-12-06T19:25:15.376Z 
Learnt from: shawnxie999
Repo: XRPLF/xrpl.js PR: 2661
File: packages/xrpl/test/integration/transactions/mptokenAuthorize.test.ts:29-118
Timestamp: 2024-12-06T19:25:15.376Z
Learning: In the XRPLF/xrpl.js TypeScript client library, when writing tests (e.g., in `packages/xrpl/test/integration/transactions/`), we generally do not need to test rippled server behaviors, because those behaviors are covered by rippled's own integration and unit tests.

Applied to files:

  • packages/xrpl/test/integration/transactions/delegateSet.test.ts
📚 Learning: 2024-12-06T19:27:11.147Z 
Learnt from: shawnxie999
Repo: XRPLF/xrpl.js PR: 2661
File: packages/xrpl/test/integration/transactions/clawback.test.ts:165-178
Timestamp: 2024-12-06T19:27:11.147Z
Learning: In the integration tests for `clawback.test.ts`, it's acceptable to use `ts-expect-error` to bypass type checking when verifying ledger entries, and no additional type safety improvements are needed.

Applied to files:

  • packages/xrpl/test/integration/transactions/delegateSet.test.ts
📚 Learning: 2025-01-08T02:12:28.489Z 
Learnt from: ckeshava
Repo: XRPLF/xrpl.js PR: 2874
File: packages/xrpl/test/integration/transactions/permissionedDomain.test.ts:25-80
Timestamp: 2025-01-08T02:12:28.489Z
Learning: The rippled C++ implementation (PR #5161) includes comprehensive test coverage for PermissionedDomain (XLS-80d) error cases. The JS SDK tests focus on the happy path since the error cases are already validated at the rippled level, following the principle of not duplicating complex validation testing across SDK implementations.

Applied to files:

  • packages/xrpl/test/integration/transactions/delegateSet.test.ts
📚 Learning: 2025-01-31T17:46:25.375Z 
Learnt from: ckeshava
Repo: XRPLF/xrpl.js PR: 2873
File: packages/xrpl/test/integration/transactions/trustSet.test.ts:0-0
Timestamp: 2025-01-31T17:46:25.375Z
Learning: For the XRPL implementation, extensive test cases for deep freeze behavior (high/low side interactions, clearing flags, etc.) are maintained in the C++ implementation and don't need to be duplicated in the JavaScript implementation.

Applied to files:

  • packages/xrpl/test/integration/transactions/delegateSet.test.ts
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (8)
  • GitHub Check: integration (22.x)
  • GitHub Check: unit (24.x)
  • GitHub Check: unit (22.x)
  • GitHub Check: integration (24.x)
  • GitHub Check: integration (20.x)
  • GitHub Check: unit (20.x)
  • GitHub Check: browser (24.x)
  • GitHub Check: semgrep-cloud-platform/scan
🔇 Additional comments (2)
packages/xrpl/test/integration/transactions/delegateSet.test.ts (2)

18-18: Import of shared test utilities is appropriate and fully used

generateFundedWallet and testTransaction are both used below and match existing integration-test patterns in this repo; no issues here.

91-98: Updated expected engine result code to terNO_DELEGATE_PERMISSION is consistent

The comment and the testTransaction expectation now both target terNO_DELEGATE_PERMISSION, and the call pattern (with undefined for the callback slot) matches other tests using this helper. Looks correct and keeps the test aligned with current rippled behavior.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

coderabbitai[bot] avatar Dec 03 '25 22:12 coderabbitai[bot]

Note: You need to enable the PermDelegation amendment in the config file: https://github.com/XRPLF/xrpl.js/actions/runs/20116926294/job/57728468166#step:9:119

ckeshava avatar Dec 11 '25 22:12 ckeshava