0027 XLS-27d: (DEPRECATED) Token-Enabled Escrows and Payment Channels

[RichardAH]

XLS-27d Token-Enabled Escrows and Payment Channels

Deprecated in favour of XLS-34d

Introduction

The XRPL supports several types of on-ledger negotiable Instruments, namely: Escows, Payment Channels and Checks. While each of these instruments is implemented as a first-class on-ledger object, only the Check object supports the use of Trust Line balances. Payment Channels and Escrows support only the native asset XRP. This limitation is a barrier to wider-spread use of these Instruments for reasons including:

• Regulatory compliance.
• Unwillingness to hold a counter-party-free asset (i.e. XRP).
• Volatility and exchange-rate risk.

This XLS proposes to introduce an Amendment to the XRPL protocol: featurePaychanAndEscrowForTokens.

The amendment has the following goals:

• Allow Escrows to use Trust Line balances (aka Fungible Tokens).
• Allow Payment Channels to use Trust Line balances.
• Allow Issuers to retain freeze and authorization control over their Issued currencies even when they are locked into Instruments.
• Avoid unnecessary multiplication of on-ledger entities.
• Avoid unnecessarily burdening the ledger computationally.

Trust Lines

Trust Line balances are issued by users of the XRPL (called Issuers). They exist on-ledger as RippleState objects.

Each Trust Line (RippleState object) consists of:

• An Issuer,
• The account which currently owns the Issued tokens,
• A currency code,
• A balance, and
• A variety of other features not directly relevant to this discussion.

A Trust Line currency is uniquely identified by the the combination of its issuer and currency code.

Locked Balances

To facilitate locking Trust Line balances into on-ledger Instruments, an additional piece of information is added to each relevant Trust Line:

• A Locked Balance.

If all or some of the Trust Line balance is locked by a Payment Channel or an Escrow then this amount is accounted for in the Locked Balance field. The Trust Line Balance less the Locked Balance is the user's spendable balance for that asset. This may be zero if the whole balance is locked.

The rules for the Locked Balance field are as follows

• If there is no Locked Balance on the Trust Line then the Locked Balance is zero.
• If a Locked Balance reaches zero on the Trust Line then the Locked Balance field is removed from the RippleState object and no longer takes up space on the ledger.
• A Locked Balance can never exceed the amount in the Balance field.
• A Locked Balance can never be negative.

For each Instrument (e.g. Escrow, PayChan) a user holds that locks up some tokens from a Trust Line:

• Locking X tokens into the Instrument increases the Locked Balance on the Trust Line by X.
• Upon settlement of the Instrument, both the Locked Balance and the Balance of the Trust Line are together decremented by the amount of the settlement (and the Balance on the counter-party's Trust Line is incremented by the settlement amount, less transaction fees).
• If the Instrument is cancelled in whole or in part, the amount returned to the first party is decremented from the Locked Balance.
• Multiple Instruments acting on the same Trust Line accumulate toward the LockedBalance.

Settlement

An Instrument can only be created over a Trust Line balance if both parties (source and destination) are:

• Authorised to hold the Trust Line,
• Do not have a frozen Trust Line for the issuer/currency pair, and
• Can ripple the balance through its Issuer.

The destination may not have a Trust Line yet. This is not a bar to creating the Instrument provided that a hypothetical Trust Line created at the same time the Instrument is created, from the destination account to the Issuer, for the relevant currency, would meet the above requirements.

Settling an Instrument (e.g. EscrowFinish, PaymentChannelClaim) carries the same semantics as crossing an offer: If no Trust Line exists on the destination side, then a Trust Line with zero limit is created and the tokens (balance) are placed into that line. However creation of a Trust Line requires the transaction to be signed by the receiving account (because it creates an on-ledger object and increases the Owner Count and thus the XRP reserve locked by the destination account.)

Frozen Lines

It is possible an Issuer causes an Instrument that uses some of their issued tokens to become frozen. They can do this by simply freezing their side of their Trust Line with either of the parties to the Instrument. This prevents the Instrument from being resolved or cancelled until the freeze is lifted.

Escrows and Payment Channels in this or any state are a bar to account deletion. Trust Lines with LockedBalance (from any source) are also a bar to account deletion.

[JoelKatz]

The quirk with this is that the XRPL uses finite-precision math for issued asset balances. For example, X+Y-X is not guaranteed to equal Y. So while this will almost perfectly work, it can't absolutely guarantee 100% of the locked amount will be available 100% of the time. At least, I don't see how it could.

Someone could, for example, create an escrow for 10^16 of an asset and then an escrow for 1 of an asset. If they then terminate the escrow for 10^16 of the asset, the locked balance will return to zero even though 1 unit is still supposed to be locked. This will probably never matter in practice with real assets with non-malicious issuers.

[RichardAH]

While bidirectional, ripple state objects are not “full duplex”. There is only one balance and its sign indicates who “owns” the tokens and who “issued” them. Since I cannot lock tokens I don’t own, it makes sense that only one side can lock tokens in that relationship.

If the sign of the balance flips (which can only happen if LockedBalance goes to zero first) then now a reverse locked balance is possible (also with a flipped sign) and the previous owner is now the issuer and the previous issuer is now the owner. The semantics continue to work as before.

[JoelKatz]

Funny that we both said exactly the same thing at the same time.

I guess the other concern would be that imprecise math might prevent the locked balance from ever hitting zero. It may wind up stuck at some very small amount. I think that's harmless except that it may make the trustline unremovable. Maybe we also need a count of the number of items included in the locked balance so that if the number of items hits zero, we set the locked balance to exactly zero.

This may be overkill and not actually be needed.

[XChainUS]

Any update on the ability to lock xrpl tokens

[RichardAH]

Yes the amendment is enabled on our testnet https://hooks-testnet-v2.xrpl-labs.com/

[LillianDay]

@JoelKatz can a “closing argument” be added to handle when balance <= x then preform y?

I’m not a programmer, I just play one in front of my computer but it would be so valuable to have this resource for trust-less fungible token distribution and management. A fractional residual balance being the ONLY issue seems like we can resolve this with a closing argument to the trust line, therefore this would be pre-set instructions to handle the remaining balance and open up the door for more trust-less resources on the XRPL.

[RichardAH]

@JoelKatz i think the criticism that there are possible dust exploits due to loss of precision in the floating point regime are valid but I also think they must logically extend to the whole DEX. My only consideration is that a malicious user should not be able to place the ledger into a state where an assertion fails due to some precision loss exploit. That is something to consider carefully in testing.

[JoelKatz]

I believe these issues were taken into account in the design of all the other parts of the ledger and the DEX. For example, orders do not reserve funds precisely because of this issue. Escrows do not currently support issued assets primarily because of this issue.

[RichardAH]

I think the case you mentioned is technically handleable: if a transaction would result in a balance less than the locked balance (this can be checked in the transactor) then the transaction is only allowed to spend up to one fewer than the current mantissa of the Balance. This way the smallest available unit is always held over to satisfy the locked balance. This would be annoying as you might have to spend down a few times to get your balance equal to locked balance if you had a very large balance and a very small locked balance. However this is an extreme edge case almost no one doing anything honest will ever encounter. The error could be something like tecPRECISION_LOSS

[RichardAH]

Likewise trying to lock a large balance over an already locked much smaller balance could return this same error. While not an ideal solution it is a solution.

[mvadari]

@RichardAH should this spec be moved into PR for historical/record-keeping purposes?