Руководство по протоколу кредитования (XLS-66d)

Данное руководство описывает использование протокола кредитования XRPL с SDK XrplCSharp. Протокол обеспечивает обеспеченное кредитование на уровне реестра через кредитных брокеров и хранилища.

Примечание: Протокол кредитования требует поправки LendingProtocol (XLS-66d). Функция находится в статусе черновика и может быть изменена. Требуется rippled 3.1.0+.

Содержание

  • Обзор
  • Ключевые концепции
  • Типы транзакций
  • Пошаговая настройка кредитного брокера
  • Создание и управление кредитом
  • CounterpartySignature (совместная подпись LoanSet)
  • Объекты реестра
  • Тип Number
  • Типичные ошибки
  • Лучшие практики

Обзор

Протокол кредитования XRPL реализует обеспеченное кредитование на уровне реестра:

Брокер (Кредитор)                       Заёмщик
┌──────────────────────┐              ┌──────────────────────┐
│                      │   LoanSet    │                      │
│  Vault ◄── Депозит   │ ◄──────────► │  Получает основную   │
│  Cover ◄── Депозит   │ (совместная  │  сумму               │
│  LoanBroker ── Loan  │  подпись)    │  Погашает LoanPay    │
└──────────────────────┘              └──────────────────────┘

Брокер (кредитор) создаёт хранилище для активов, настраивает кредитного брокера с параметрами кредитования и выдаёт кредиты заёмщикам. Заёмщик совместно подписывает кредитное соглашение и погашает долг периодическими платежами.


Ключевые концепции

Хранилище (Vault)

Хранилище содержит активы, доступные для кредитования. Создаётся через VaultCreate, хранит XRP или IOU-токены. Перед созданием кредитного брокера необходимо создать и пополнить хранилище.

С поправкой LendingProtocolV1_1 кредитного брокера можно привязать только к закрытому (closed-ended) хранилищу; LoanBrokerSet на открытом завершается с tecNO_PERMISSION. Закрытое хранилище проходит три фазы, зафиксированные при создании, и депозиты, вывод и выдача кредитов привязаны к фазам:

Фаза Длится Допускается
Subscription до SubscriptionDate VaultDeposit, VaultWithdraw
Investment от SubscriptionDate до RedemptionDate LoanSet; VaultDeposit завершается с tecEXPIRED, VaultWithdraw — с tecTOO_SOON
Redemption с RedemptionDate VaultWithdraw; LoanSet завершается с tecEXPIRED

Создание брокера и внесение покрытия к фазе не привязаны. Ограничения на даты описаны в разделе «Вид vault (LendingProtocolV1_1)» руководства по Vault. В сети без этой поправки хранилище создаётся без VaultKind, SubscriptionDate и RedemptionDate: нода, не знающая поправку, эти поля отклоняет.

Кредитный брокер (LoanBroker)

LoanBroker — объект реестра, представляющий кредитную организацию. Ссылается на хранилище и определяет параметры кредитования: ставки покрытия, комиссии за управление и лимиты долга. Создаётся через LoanBrokerSet.

Покрытие (Cover)

Брокер должен внести покрытие (залог со стороны брокера) в кредитного брокера. Покрытие защищает заёмщиков и обеспечивает участие брокера в рисках. Управляется через LoanBrokerCoverDeposit и LoanBrokerCoverWithdraw.

Кредит (Loan)

Loan — объект реестра, представляющий активный кредит между брокером и заёмщиком. Создаётся через LoanSet (требует совместной подписи обеих сторон). Отслеживает основную сумму, процентные ставки, график платежей и остатки.

CounterpartySignature

LoanSet — особая транзакция, требующая двух подписей: брокер (отправитель) подписывает транзакцию обычным способом, а заёмщик (контрагент) предоставляет CounterpartySignature. Обе подписывают одну и ту же транзакцию, но каждая под своим hash-префиксом, начиная с fixCleanup3_4_0 в rippled.

Тип Number

Числовые поля кредитования (например, PrincipalRequested, DebtMaximum) используют тип Number XRPL — 12-байтовый формат из 8-байтовой знаковой мантиссы и 4-байтовой знаковой экспоненты. Это отличается от стандартного типа Amount.


Типы транзакций

Транзакция Назначение Кто отправляет
LoanBrokerSet Создать или обновить кредитного брокера Брокер
LoanBrokerDelete Удалить кредитного брокера Брокер
LoanBrokerCoverDeposit Внести покрытие в брокера Брокер
LoanBrokerCoverWithdraw Вывести покрытие из брокера Брокер
LoanBrokerCoverClawback Возврат покрытия от держателя Брокер
LoanSet Создать новый кредит (совместная подпись) Брокер + Заёмщик
LoanDelete Удалить полностью погашенный кредит Брокер
LoanManage Управление состоянием кредита (дефолт/ухудшение) Брокер
LoanPay Внести платёж по кредиту Заёмщик

Пошаговая настройка кредитного брокера

1. Создание хранилища

Брокер создаёт закрытое хранилище для хранения активов кредитования:

using Xrpl.Models.Transactions;
using Xrpl.Models.Common;
using Xrpl.Models.Ledger;   // VaultKind, LedgerIndexType
using Xrpl.Models.Methods;
using Xrpl.Sugar;
using static Xrpl.Models.Common.Common;

// Phase dates are compared with the ledger's close time, not the machine clock
LOLedger ledger = await client.Ledger(
    new LedgerRequest { LedgerIndex = new LedgerIndex(LedgerIndexType.Validated) }).Typed();
DateTime now = ((LedgerEntity)ledger.LedgerEntity).CloseTime.Value;

VaultCreate vaultTx = new VaultCreate
{
    Account = walletBroker.ClassicAddress,
    Asset = new IssuedCurrency { Currency = "XRP" },
    VaultKind = (uint)VaultKind.ClosedEnded,
    SubscriptionDate = now.AddHours(1),   // the deposit in step 2 must happen before this
    RedemptionDate = now.AddDays(90),     // every loan must be repaid 60 s before this
};
vaultTx = await client.Autofill(vaultTx);
TransactionSummary vaultResult = await client.SubmitAndWait(vaultTx, walletBroker, true);

// Извлечение VaultID из метаданных
string vaultId = GetCreatedObjectId(vaultResult, LedgerEntryType.Vault);

2. Пополнение хранилища

Внесение активов в хранилище для кредитования. Депозит принимается только в фазе subscription, до SubscriptionDate:

VaultDeposit depositTx = new VaultDeposit
{
    Account = walletBroker.ClassicAddress,
    VaultID = vaultId,
    Amount = new Currency { Value = "100000000", CurrencyCode = "XRP" }, // 100 XRP
};
depositTx = await client.Autofill(depositTx);
await client.SubmitAndWait(depositTx, walletBroker, true);

3. Создание кредитного брокера

Создание брокера, ссылающегося на пополненное хранилище. Три ставки необязательны; брокер без ставок создаётся без этих полей:

LoanBrokerSet brokerTx = new LoanBrokerSet
{
    Account = walletBroker.ClassicAddress,
    VaultID = vaultId,
    // Optional rates, fixed at creation. All are in 1/10th of a basis point: 100000 = 100%
    CoverRateMinimum = 15000,        // 15% of outstanding debt must be covered by first-loss capital
    CoverRateLiquidation = 12000,    // 12% of the minimum cover is moved to the vault on a default
    ManagementFeeRate = 100,         // 0.1% management fee
};
brokerTx = await client.Autofill(brokerTx);
TransactionSummary brokerResult = await client.SubmitAndWait(brokerTx, walletBroker, true);

string brokerId = GetCreatedObjectId(brokerResult, LedgerEntryType.LoanBroker);

Задать ставки можно только здесь. LoanBrokerSet, изменяющий существующего брокера, несёт LoanBrokerID и не может включать эти поля: rippled отклоняет такую транзакцию с temINVALID.

CoverRateMinimum и CoverRateLiquidation принимают значения от 0 до 100000 и должны быть либо оба нулевыми, либо оба ненулевыми. ManagementFeeRate принимает значения от 0 до 10000 (10%).

4. Внесение покрытия

Депозит покрытия для возможности выдачи кредитов:

LoanBrokerCoverDeposit coverTx = new LoanBrokerCoverDeposit
{
    Account = walletBroker.ClassicAddress,
    LoanBrokerID = brokerId,
    Amount = new Currency { Value = "50000000", CurrencyCode = "XRP" }, // 50 XRP
};
coverTx = await client.Autofill(coverTx);
await client.SubmitAndWait(coverTx, walletBroker, true);

Владелец может вывести покрытие только до минимума: CoverRateMinimum от DebtTotal брокера с округлением вверх. LoanBrokerCoverWithdraw, который оставил бы меньше, завершается с tecINSUFFICIENT_FUNDS, а комиссия всё равно списывается. Округление минимума изменилось с fixCleanup3_2_0, поэтому рекомендуется рассчитывать его через LoanBrokerCover, а не вручную. MaxWithdrawable возвращает наибольший вывод, который примет нода, в единицах самого актива (drops для XRP):

// broker and vault: the LoanBroker and Vault entries, read with ledger_entry
LedgerRules rules = await LedgerRules.FromNodeAsync(client);
decimal withdrawable = LoanBrokerCover.MaxWithdrawable(broker, vault, rules);
decimal minimum = LoanBrokerCover.MinimumCover(broker, vault, rules);

LoanBrokerCoverWithdraw withdrawTx = new LoanBrokerCoverWithdraw
{
    Account = walletBroker.ClassicAddress,
    LoanBrokerID = brokerId,
    Amount = new Currency { Value = withdrawable.ToString(CultureInfo.InvariantCulture), CurrencyCode = "XRP" },
};
TransactionPreview<LoanBrokerCoverOutcome> preview = await client.PreviewLoanBrokerCoverWithdraw(withdrawTx, rules);
// preview.Outcome.CoverBefore, CoverAfter, MinimumCover, MaxWithdrawable

LoanBrokerCover.CheckDeposit, CheckWithdraw и CheckClawback возвращают LoanBrokerCoverQuote с суммой, которая переместится, покрытием до и после и отказом (Refusal), который вернёт нода. При fixCleanup3_2_0 депозит округляется вниз до масштаба CoverAvailable, поэтому покрытие может увеличиться меньше, чем на отправленный Amount. PreviewLoanBrokerCoverDeposit и PreviewLoanBrokerCoverClawback дают превью двух других транзакций.


Создание и управление кредитом

1. Создание кредита (LoanSet)

LoanSet требует совместной подписи брокера и заёмщика. Подробности в разделе CounterpartySignature.

Кредит можно выдать только в фазе investment: после SubscriptionDate (до неё — tecTOO_SOON) и до RedemptionDate (после неё — tecEXPIRED). Последний платёж по кредиту должен приходиться не позже чем за 60 секунд до RedemptionDate, иначе LoanSet завершается с tecNO_PERMISSION.

LoanSet loanTx = new LoanSet
{
    Account = walletBroker.ClassicAddress,
    LoanBrokerID = brokerId,
    Counterparty = walletBorrower.ClassicAddress,
    PrincipalRequested = 10000000,  // Тип Number (не drops)
};

// Требуется специальная совместная подпись — см. раздел CounterpartySignature
TransactionSummary result = await SubmitLoanSetWithCounterpartySig(
    client, loanTx, walletBroker, walletBorrower);

string loanId = GetCreatedObjectId(result, LedgerEntryType.Loan);

Условия и график до подписи заёмщика

PreviewLoanSet прогоняет LoanSet через simulate до того, как стороны подпишут транзакцию. Подпись заёмщика не нужна: превью отправляет пустой CounterpartySignature, который simulate принимает без проверки. Результат содержит точные условия, с которыми нода создала бы займ:

TransactionPreview<LoanSetOutcome> preview = await client.PreviewLoanSet(loanTx);
if (preview.WouldSucceed)
{
    LoanSetOutcome terms = preview.Outcome;
    // terms.Loan.PeriodicPayment, terms.Loan.TotalValueOutstanding, terms.BorrowerReceives,
    // terms.InterestTotal, terms.ServiceFeesTotal, terms.TotalToRepay
}

LoanOrigination.Compute рассчитывает те же условия без ноды — по транзакции и объектам vault и брокера. Метод вычисляет то, что сохранит LoanSet (PeriodicPayment, TotalValueOutstanding, ManagementFeeOutstanding, LoanScale), и повторяет проверки, которые зависят от сумм: свободные активы vault, значение, которое актив не может хранить или которое точнее шкалы займа, и ограничения амортизации. Полной проверкой остаётся превью: лимиты, покрытие, резервы и авторизация офлайн не проверяются.

LoanOriginationTerms offline = LoanOrigination.Compute(loanTx, vault, broker, startDate: null, options);
if (offline.IsAccepted)
{
    // offline.Loan: объект Loan, который создал бы LoanSet
}
else
{
    // offline.Refusal: "tecPRECISION_LOSS" или "tecINSUFFICIENT_FUNDS"; offline.RefusalReason объясняет причину
}

LoanSchedule.Project строит по этим условиям или по Loan, прочитанному из леджера, полный график регулярных платежей, повторяя для каждого периода computePaymentComponents из rippled. Ставка комиссии за управление берётся из LoanBroker, а LedgerRules.FromNodeAsync читает амендменты, которые влияют на округление:

LedgerRules options = await LedgerRules.FromNodeAsync(client);
IReadOnlyList<LoanScheduleRow> schedule = LoanSchedule.Project(
    terms.Loan, terms.Asset, broker.ManagementFeeRate ?? 0, options);

foreach (LoanScheduleRow row in schedule)
{
    // row.DueDate, row.Principal, row.Interest, row.ManagementFee, row.ServiceFee, row.Total
}

Расчёт ведётся в арифметике самой ноды — XrplNumber с тем же округлением, что у Number в rippled, — поэтому каждая строка до последней единицы актива совпадает с суммой, которую нода спишет за регулярный платёж, внесённый вовремя; к просроченному платежу добавляются проценты за просрочку и LatePaymentFee. В тестовом Blazor-клиенте Tests/TestsClients/Blazor-WebAssembly есть вкладка Loan preview, которая показывает условия и график для брокера на любой ноде.

2. Внесение платежа по кредиту

Заёмщик вносит платежи по кредиту:

LoanPay payTx = new LoanPay
{
    Account = walletBorrower.ClassicAddress,
    LoanID = loanId,
    Amount = new Currency { Value = "10000000", CurrencyCode = "XRP" },
};
payTx = await client.Autofill(payTx);
TransactionSummary result = await client.SubmitAndWait(payTx, walletBorrower, true);

Сколько платить

LoanPayments.RegularPaymentCap читает объект Loan и возвращает сумму, которой всегда хватает на ближайший регулярный платёж, в единицах актива (для XRP это drops). Для последнего платежа сумма точная: TotalValueOutstanding плюс LoanServiceFee. Для остальных платежей это PeriodicPayment, округлённый вверх по активу, плюс LoanServiceFee. Нода списывает столько, сколько требует график амортизации, а это может быть на одну единицу округления меньше. Весь Amount при этом не списывается, только нужная сумма.

Чтобы заранее узнать, что именно сделает платёж, его можно отправить на превью. PreviewLoanPay выполняет autofill, прогоняет транзакцию через simulate и читает разбивку платежа из метаданных:

LOLoan loan = (LOLoan)(await client.LedgerEntry(new LedgerEntryRequest { Index = loanId }).Typed()).Node;
// null, если в объекте нет данных о платеже или значение не помещается в decimal: тогда сумму
// нужно выбрать самостоятельно, а превью ниже покажет, сколько возьмёт нода.
if (LoanPayments.RegularPaymentCap(loan, new IssuedCurrency { Currency = "XRP" }) is not decimal cap)
    return;

LoanPay payTx = new LoanPay
{
    Account = walletBorrower.ClassicAddress,
    LoanID = loanId,
    Amount = new Currency { Value = cap.ToString(CultureInfo.InvariantCulture), CurrencyCode = "XRP" },
};

TransactionPreview<LoanPaymentOutcome> preview = await client.PreviewLoanPay(payTx);
if (preview.WouldSucceed)
{
    LoanPaymentOutcome outcome = preview.Outcome;
    // outcome.PrincipalPaid, outcome.InterestToVault, outcome.PaidToBroker, outcome.TotalPaid,
    // outcome.PaymentsMade, outcome.LoanAfter
    await client.SubmitAndWait(preview.Transaction, walletBorrower, false);
}

LoanPaymentOutcome.FromMetadata читает ту же разбивку из метаданных уже проведённой транзакции. Разбивка строится по движению средств: vault получает основной долг и проценты, брокер получает всё остальное (комиссию за управление, сервисный сбор, штраф за просрочку и сбор за досрочное погашение). LoanPayments.IsPaymentLate показывает, будет ли платёж просроченным, а LoanPayments.IsPastGracePeriod показывает, может ли брокер объявить дефолт. Просроченный платёж включает проценты за просрочку и LatePaymentFee сверх этой суммы.

LoanPayments.LatePaymentDue и LoanPayments.FullPaymentDue рассчитывают стоимость просроченного платежа (tfLoanLatePayment) и досрочного погашения (tfLoanFullPayment) так же, как это делает нода: регулярный платёж со штрафом и процентами за просрочку либо остаток долга с начисленными процентами, штрафом за досрочное погашение и ClosePaymentFee. Обоим методам необходимо время закрытия леджера, предшествующего тому, в который попадёт платёж, потому что проценты начисляются по это время. Обычно берут время закрытия последнего валидированного леджера; если платёж попадёт в леджер на один позже, проценты успеют начислиться ещё за несколько секунд. Оба метода возвращают null, если нода отклонит такой платёж в это время.

LedgerRules rules = await LedgerRules.FromNodeAsync(client);
DateTime at = /* время закрытия последнего валидированного леджера */;

LoanPaymentDue late = LoanPayments.LatePaymentDue(loan, asset, broker.ManagementFeeRate ?? 0, at, rules);
LoanPaymentDue full = LoanPayments.FullPaymentDue(loan, asset, broker.ManagementFeeRate ?? 0, at, rules);
// late.Total, full.Total: сумма к оплате; .Principal, .InterestToVault, .PaidToBroker: разбивка

LoanPayments.PaymentForAmount рассчитывает, что регулярный платёж сделает с заданной суммой Amount. Нода проводит столько регулярных платежей, сколько покрывает сумма, но не больше 100 за транзакцию, а с флагом tfLoanOverpayment по кредиту, созданному с этим флагом, направляет остаток на переплату. Из переплаты удерживаются OverpaymentFee и штрафные проценты по ставке OverpaymentInterestRate, остаток гасит основной долг, после чего кредит переамортизируется на оставшиеся платежи и PeriodicPayment уменьшается. Нода списывает только то, что провела: без флага, а также если переплату целиком съедают сборы, остаток суммы остаётся у плательщика.

LoanAmountPayment plan = LoanPayments.PaymentForAmount(
    loan, asset, broker.ManagementFeeRate ?? 0, amount: 25_000_000, at, overpayment: true, rules);
if (plan.IsAccepted)
{
    // plan.Due.Total: сколько спишет нода; plan.PaymentsMade; plan.IsOverpaid;
    // plan.LoanAfter.PeriodicPayment, plan.LoanAfter.PrincipalOutstanding: кредит после платежа
}
// иначе plan.Refusal: tecINSUFFICIENT_PAYMENT, tecEXPIRED, tecNO_PERMISSION, ...

3. Удаление полностью погашенного кредита

После полного погашения брокер может удалить кредит:

LoanDelete deleteTx = new LoanDelete
{
    Account = walletBroker.ClassicAddress,
    LoanID = loanId,
};
deleteTx = await client.Autofill(deleteTx);
await client.SubmitAndWait(deleteTx, walletBroker, true);

Важно: Нельзя удалить кредит с непогашенным остатком (tecHAS_OBLIGATIONS). Кредит должен быть полностью погашен.

4. Управление состоянием кредита

Брокер может отметить кредит как дефолтный, обесценённый или восстановить его:

// Отметить кредит как дефолтный
LoanManage manageTx = new LoanManage
{
    Account = walletBroker.ClassicAddress,
    LoanID = loanId,
    Flags = LoanManageFlags.tfLoanDefault,
};
manageTx = await client.Autofill(manageTx);
await client.SubmitAndWait(manageTx, walletBroker, true);

Флаги LoanManage (взаимоисключающие):

  • tfLoanDefault — отметить кредит как дефолтный
  • tfLoanImpair — отметить кредит как обесценённый
  • tfLoanUnimpair — восстановить кредит из обесценённого состояния

LoanManage без флага действия допустима и не меняет кредит.

5. Удаление кредитного брокера

Когда у брокера нет активных кредитов:

LoanBrokerDelete deleteBrokerTx = new LoanBrokerDelete
{
    Account = walletBroker.ClassicAddress,
    LoanBrokerID = brokerId,
};
deleteBrokerTx = await client.Autofill(deleteBrokerTx);
await client.SubmitAndWait(deleteBrokerTx, walletBroker, true);

CounterpartySignature (совместная подпись LoanSet)

LoanSet уникальна среди транзакций XRPL — требует двух подписей. Брокер подписывает транзакцию обычным способом (TxnSignature), а заёмщик предоставляет CounterpartySignature — внутренний STObject, содержащий SigningPubKey и TxnSignature заёмщика.

SDK предоставляет LoanSigningHelper и XrplWallet.SignAsLoanCounterparty() с тремя паттернами подписи, аналогичными Batch signing (V1/V2/V3).

Роли две: отправитель (Account) и контрагент (Counterparty, а если поле не задано — владелец LoanBroker). Один из них должен быть владельцем брокера, другой — заёмщиком, поэтому отправить транзакцию может любая сторона:

  • владелец брокера отправляет с Counterparty, равным заёмщику, и заёмщик подписывает как контрагент;
  • заёмщик отправляет, Counterparty — владелец брокера или не задан, и владелец брокера подписывает как контрагент.

Примеры ниже используют первый вариант. Для второго поменяйте кошельки местами: заёмщик готовит и отправляет транзакцию, владелец брокера подписывает как контрагент. LoanSigningHelper.SignLoanSet принимает два кошелька в любом порядке и назначает роли по Account; перегрузка с аргументом brokerOwner дополнительно проверяет контрагента, когда Counterparty не задан.

Подготовка (общая для всех паттернов)

using Xrpl.Wallet;

// Autofill рассчитывает комиссию (включая overhead CounterpartySignature)
loanTx = await client.Autofill(loanTx);
// PrepareForSigning устанавливает SigningPubKey брокера и удаляет поля подписей
JsonObject prepared = LoanSigningHelper.PrepareForSigning(loanTx, brokerWallet);

V1 — Автоматический (оба ключа доступны локально)

Используйте, когда кошельки брокера и заёмщика доступны на одном устройстве:

SignatureResult result = LoanSigningHelper.SignLoanSet(prepared, brokerWallet, borrowerWallet);
await client.SubmitRequest(result.TxBlob);

V2 — Параллельный (ключи на разных устройствах, подпись независимо)

Используйте, когда брокер и заёмщик подписывают независимо, а третья сторона объединяет подписи:

// Устройство A (брокер): подписывает транзакцию обычным способом
var brokerDict = JsonSerializer.Deserialize<Dictionary<string, object>>(
    prepared.ToJsonString(), XrplJsonOptions.Default);
SignatureResult brokerSig = brokerWallet.Sign(brokerDict);

// Устройство B (заёмщик): подписывает как контрагент (независимая копия payload)
var borrowerDict = JsonSerializer.Deserialize<Dictionary<string, object>>(
    prepared.ToJsonString(), XrplJsonOptions.Default);
SignatureResult counterpartySig = borrowerWallet.SignAsLoanCounterparty(borrowerDict);

// Комбинатор: объединяет обе подписи в один blob
SignatureResult combined = LoanSigningHelper.CombineLoanSignatures(
    brokerSig.TxBlob, counterpartySig.TxBlob);
await client.SubmitRequest(combined.TxBlob);

V3 — Последовательный (заёмщик подписывает первым, передаёт брокеру)

Используйте в реальном сценарии, когда заёмщик подписывает первым и отправляет частично подписанный blob брокеру:

// Шаг 1: Заёмщик получает подготовленный JSON транзакции, подписывает как контрагент
var txDict = JsonSerializer.Deserialize<Dictionary<string, object>>(
    prepared.ToJsonString(), XrplJsonOptions.Default);
SignatureResult withCounterparty = borrowerWallet.SignAsLoanCounterparty(txDict);
// withCounterparty.TxBlob передаётся брокеру (через API, QR-код и т.д.)

// Шаг 2: Брокер получает частично подписанный blob, добавляет TxnSignature
SignatureResult fullySigned = LoanSigningHelper.SubmitterSign(
    withCounterparty.TxBlob, brokerWallet);
await client.SubmitRequest(fullySigned.TxBlob);

Важно: Не используйте brokerWallet.Sign() для частично подписанного LoanSet blob — он не обрабатывает CounterpartySignature корректно. Всегда используйте LoanSigningHelper.SubmitterSign() для паттерна V3.

Заёмщик с мультиподписью (Counterparty со SignerList)

Когда заёмщик — мультиподписной аккаунт, CounterpartySignature принимает мультиподписную форму: пустой SigningPubKey и массив Signers, который нода сверяет со SignerList контрагента под мультиподписным префиксом контрагента: начиная с fixCleanup3_4_0 это не тот префикс, что у tx.Signers. Каждый подписант из списка заёмщика подписывает стандартным вызовом мультиподписи — SDK видит, что брокер подписывает одиночно, и определяет сторону сам, — а композитор расставляет записи по секциям.

// Комиссия покрывает по одной базовой комиссии на каждого подписанта контрагента
// (rippled LoanSet::calculateBaseFee), поэтому autofill выполняется с числом подписантов до подписания
Dictionary<string, object> autofilled = await client.Autofill(loanTx.ToDictionary(), signersCount: 2);
JsonObject prepared = LoanSigningHelper.PrepareForSigning(
    JsonNode.Parse(JsonSerializer.Serialize(autofilled, XrplJsonOptions.Default)).AsObject(), brokerWallet);
var preparedDict = JsonSerializer.Deserialize<Dictionary<string, object>>(prepared.ToJsonString(), XrplJsonOptions.Default);

// Брокер: одиночная основная подпись. Подписанты заёмщика: переносимые записи мультиподписи
SignatureResult brokerPart = brokerWallet.Sign(new Dictionary<string, object>(preparedDict));
SignatureResult part1 = signer1.Sign(new Dictionary<string, object>(preparedDict), multisign: true);
SignatureResult part2 = signer2.Sign(new Dictionary<string, object>(preparedDict), multisign: true);

// По данным реестра: композитор находит подписантов в SignerList контрагента
// и заранее проверяет кворум по весам
SignatureResult composed = await client.ComposeSignatures(new[] { brokerPart.TxBlob, part1.TxBlob, part2.TxBlob });

// Оффлайн: подписанты заёмщика перечисляются явно
SignatureResult offline = LoanSigningHelper.CombineLoanSignatures(
    new[] { brokerPart.TxBlob, part1.TxBlob, part2.TxBlob },
    new[] { signer1.ClassicAddress, signer2.ClassicAddress });

await client.SubmitRequest(composed.TxBlob);

Подписант, входящий более чем в один SignerList (брокера, спонсора, заёмщика), для композитора по данным реестра является ошибкой; в таком случае необходимо собирать подписи оффлайн с явным указанием сторон.

Ключевые моменты

  • Обе стороны подписывают одну и ту же транзакцию (сериализованную для подписи, без полей подписей), каждая под hash-префиксом своей роли
  • Прообраз подписи использует SigningPubKey брокера (отправляющий аккаунт)
  • CounterpartySignature — это STObject с isSigningField = false — он исключён из прообраза подписи
  • Autofill автоматически рассчитывает корректную комиссию для LoanSet (включая overhead CounterpartySignature ~150 байт)

Объекты реестра

Протокол кредитования создаёт следующие объекты реестра:

Объект Описание Создаётся транзакцией
Vault Хранит активы для кредитования VaultCreate
LoanBroker Кредитная организация с параметрами и покрытием LoanBrokerSet
Loan Активный кредит между брокером и заёмщиком LoanSet

Поля LoanBroker

Поле Тип Описание
Owner AccountID Владелец брокера — аккаунт, отправивший создающий LoanBrokerSet
Account AccountID Псевдоаккаунт брокера
VaultID Hash256 Хранилище, из которого брокер выдаёт кредиты
LoanSequence UInt32 Порядковый номер, который получит следующий кредит
OwnerCount UInt32 Количество кредитов брокера
CoverAvailable Number Доступный капитал первого убытка
DebtTotal Number Общий непогашенный долг
DebtMaximum Number Максимально допустимый долг
CoverRateMinimum UInt32 Доля долга, которую должно покрывать покрытие, в десятых долях базисного пункта (15000 = 15%)
CoverRateLiquidation UInt32 Доля минимального покрытия, переводимая в хранилище при дефолте, в десятых долях базисного пункта
ManagementFeeRate UInt16 Комиссия за управление в десятых долях базисного пункта (0-10000, до 10%)

Поля Loan

Поле Тип Описание
Borrower AccountID Аккаунт заёмщика
LoanBrokerID Hash256 Ссылка на кредитного брокера
LoanSequence UInt32 Порядковый номер в рамках брокера
PrincipalOutstanding Number Остаток основной суммы
TotalValueOutstanding Number Общая задолженность
PeriodicPayment Number Сумма платежа за интервал
InterestRate UInt32 Годовая процентная ставка в десятых долях базисного пункта (5000 = 5%)
PaymentInterval UInt32 Интервал между платежами (секунды)
GracePeriod UInt32 Отсрочка до начисления пеней (секунды)
PaymentRemaining UInt32 Оставшиеся платежи
StartDate UInt32 Начало кредита (Ripple epoch)

Counterparty, PrincipalRequested и PaymentTotal — поля транзакции LoanSet, а не объекта Loan. Запрошенную сумму rippled записывает в PrincipalOutstanding, поэтому у ledger-объекта поля PrincipalRequested нет — как нет его и у LOLoan.

Запрос состояния кредита

Используйте account_objects для получения кредитов аккаунта:

using Xrpl.Models.Methods;

var request = new AccountObjectsRequest(walletBorrower.ClassicAddress);
var response = await client.AccountObjects(request);

foreach (var obj in response.AccountObjectList)
{
    if (obj.LedgerEntryType == LedgerEntryType.Loan)
    {
        Console.WriteLine($"Кредит: {obj}");
    }
}

Тип Number

Поля кредитования используют тип Number XRPL вместо Amount. Тип Number — 12-байтовый формат:

  • 8 байт — знаковая int64 мантисса (big-endian)
  • 4 байта — знаковая int32 экспонента (big-endian)

Фактическое значение = мантисса × 10^экспонента.

Нормализация

Ненулевые значения нормализуются так, чтобы мантисса была в диапазоне [10^18, long.MaxValue]. Ноль представляется как мантисса=0, экспонента=Int32.MinValue.

Пример

Значение 10000000000000 (10^13) нормализуется до:

  • Мантисса: 1000000000000000000 (10^18)
  • Экспонента: -5
  • Бинарное представление: 0x0DE0B6B3A7640000 FFFFFFFB (12 байт)

В моделях транзакций

Поля типа Number представлены в C#-моделях типом XrplNumber? (пространство имён Xrpl.BinaryCodec.Numbers). int преобразуется неявно (PrincipalRequested = 10000000); остальные значения получаются через XrplNumber.Parse("1.5") или явное приведение из long или decimal. Бинарный кодек автоматически выполняет нормализацию и сериализацию.

Значение, которое леджер не может хранить точно (больше 19 значащих цифр), отклоняется с FormatException (при приведении типа - с OverflowException), а не округляется: так же его отклоняет rippled в JSON. Такое значение необходимо округлить самостоятельно до присваивания.

Поля, прочитанные из леджера, приходят в том виде, в каком их пишет rippled, например "1e13" для 10^13. Сравнивать их рекомендуется по значению (==, <), а не как текст; для арифметики на decimal используется TryToDecimal.


Типичные ошибки

Код ошибки Причина Решение
tecINSUFFICIENT_FUNDS В хранилище брокера недостаточно средств Внесите больше активов через VaultDeposit
tecHAS_OBLIGATIONS Нельзя удалить кредит с непогашенным остатком Полностью погасите кредит через LoanPay
tecNO_ENTRY LoanBrokerID или LoanID не найден Проверьте корректность ID
tecNO_PERMISSION Действие не разрешено: брокер на открытом хранилище, кредит, заканчивающийся менее чем за 60 с до RedemptionDate, переплата без флага Используйте закрытое хранилище; сократите срок кредита; проверьте права аккаунта
tecTOO_SOON LoanSet в фазе subscription, VaultWithdraw в фазе investment Дождитесь SubscriptionDate (для вывода — RedemptionDate)
tecEXPIRED VaultDeposit после SubscriptionDate, LoanSet после RedemptionDate Вносите депозит в фазе subscription, выдавайте кредиты в фазе investment
tecINSUFFICIENT_PAYMENT Сумма платежа слишком мала Увеличьте сумму платежа
temBAD_SIGNER Отсутствует или некорректна CounterpartySignature Убедитесь, что заёмщик совместно подписал LoanSet
telINSUF_FEE_P Комиссия слишком низкая после добавления CounterpartySignature Повторно вызовите Autofill или увеличьте комиссию перед отправкой
invalid SerialIter geti32 Ошибка кодирования типа Number Убедитесь, что поля Number — 12 байт (8 мантисса + 4 экспонента)

Лучшие практики

  1. Пополните хранилище перед выдачей кредитов — создайте хранилище, внесите активы (VaultDeposit), создайте брокера (LoanBrokerSet), внесите покрытие (LoanBrokerCoverDeposit), затем создавайте кредиты. Депозит в хранилище относится к фазе subscription, выдача кредитов — к фазе investment.

  2. Autofill учитывает LoanSet fee — Autofill автоматически рассчитывает корректную комиссию, включая overhead CounterpartySignature. Ручная корректировка комиссии не требуется.

  3. Фильтруйте по LedgerEntryType при извлечении ID — GetCreatedObjectId должен фильтровать по конкретному типу (LedgerEntryType.Vault, LedgerEntryType.LoanBroker, LedgerEntryType.Loan), чтобы не захватить DirectoryNode.

  4. Полностью погасите перед удалением — LoanDelete возвращает tecHAS_OBLIGATIONS, если остаток не нулевой. Используйте LoanPay для погашения.

  5. Используйте разумные значения PrincipalRequested — убедитесь, что в хранилище достаточно активов для запрашиваемой суммы.

  6. Проверяйте все результаты — всегда проверяйте TransactionResult:

    if (result.Meta?.TransactionResult != "tesSUCCESS")
        throw new Exception($"Транзакция не удалась: {result.Meta?.TransactionResult}");
    
  7. Флаги LoanManage взаимоисключающие — устанавливайте не более одного из tfLoanDefault, tfLoanImpair или tfLoanUnimpair.

  8. Флаги LoanPay взаимоисключающие — tfLoanOverpayment, tfLoanFullPayment и tfLoanLatePayment нельзя комбинировать. tfLoanOverpayment может требовать специальной настройки брокера/кредита.

  9. Тестирование на standalone — поправка LendingProtocol должна быть включена на rippled 3.1.0+:

    { "command": "feature", "feature": "LendingProtocol", "vetoed": false }
    

Связанные ресурсы

  • Спецификация XLS-66d
  • Спецификация Vault (XLS-65d)
  • Документация XRPL
  • Edit this page
In this article
Back to top Generated by DocFX