Rippling and authorized lines

Say you and a friend both hold FOO from the same issuer. You send your friend 20 FOO. The tokens do not jump straight from your line to theirs. Your balance with the issuer goes down by 20. Your friend's balance with the issuer goes up by 20. The issuer's total stays the same. This is rippling.

Rippling is what lets holders pay each other, so issuers need it on.

Ordinary holders usually want it off. If your lines allow rippling, other people's payments can pass through your account. Rippling can swap tokens that share a currency code, even from different issuers. Your USD from one issuer could turn into USD from another, on a payment you had nothing to do with.

Two switches control this:

• Default Ripple is an account setting. Issuers turn it on so their token can move between holders. It starts off for new accounts.
• No Ripple is a setting on each trust line. Because Default Ripple starts off, a new holder's lines get No Ripple automatically.

Some issuers also need to know who holds their token. A stablecoin issuer that checks identity first is one example. It turns on Require Auth. After that, a holder's line can carry the token only once the issuer approves it. This is called authorized trust lines.

An approval cannot be taken back. The issuer can still freeze the line.

Rippling applies to any payment of trust line tokens, except a direct exchange between an issuer and a holder.

Default Ripple

• Set with AccountSet SetFlag: 8 (asfDefaultRipple). Stored as lsfDefaultRipple.
• It affects only lines that others open to your account. Existing lines keep their settings until changed with TrustSet.
• AMMCreate fails with terNO_RIPPLE if a pool token's issuer has not enabled it.

No Ripple

• TrustSet flags: tfSetNoRipple (0x00020000) and tfClearNoRipple (0x00040000).
• It blocks rippling between two of your lines only when both have it on.
• You can turn it on only when your balance on that line is zero or positive.
• Before rippled 0.27.3 in March 2015, all trust lines allowed rippling by default.
• account_lines shows no_ripple for your side and no_ripple_peer for the other side.

Authorized trust lines

• The issuer sets AccountSet SetFlag: 2 (asfRequireAuth), stored as lsfRequireAuth. It can do this only while it has no trust lines and no offers.
• To approve a holder, the issuer sends TrustSet with the holder as LimitAmount.issuer, a value of 0 and the tfSetfAuth flag (0x00010000).
• The holder's TrustSet and the issuer's approval can come in either order.
• Each currency code needs its own approval.
• Approval cannot be revoked. It resets only if the line is deleted.
• account_lines shows peer_authorized: true once the issuer has approved your line.

account_info reports both account settings in account_flags as defaultRipple and requireAuthorization.