From 44529d51dcec1d237ef814050a2bf27f671d9bb9 Mon Sep 17 00:00:00 2001 From: mDuo13 Date: Fri, 27 Jan 2017 15:34:51 -0800 Subject: [PATCH] ticksize - reference docs --- concept-amendments.html | 2 +- content/reference-ledger-format.md | 1 + content/reference-transaction-format.md | 24 ++++++++++++++++------ reference-ledger-format.html | 6 ++++++ reference-transaction-format.html | 27 ++++++++++++++++++++----- 5 files changed, 48 insertions(+), 12 deletions(-) diff --git a/concept-amendments.html b/concept-amendments.html index 6b4e9636e7..effd24998f 100644 --- a/concept-amendments.html +++ b/concept-amendments.html @@ -321,7 +321,7 @@ TrustSetAuth -

Adds conditional payments that are directly compatible with the Interledger Protocol Crypto-Conditions specification.

+

Adds conditional payments that are directly compatible with the Interledger Protocol Crypto-Conditions specification.

Caution: This amendment is still in development.

FeeEscalation

diff --git a/content/reference-ledger-format.md b/content/reference-ledger-format.md index a4df9eab01..9416440cf2 100644 --- a/content/reference-ledger-format.md +++ b/content/reference-ledger-format.md @@ -114,6 +114,7 @@ The `AccountRoot` node has the following fields: | WalletLocator | String | Hash256 | (Optional) **DEPRECATED**. Do not use. | | WalletSize | Number | UInt32 | (Optional) **DEPRECATED**. Do not use. | | MessageKey | String | VariableLength | (Optional) A public key that may be used to send encrypted messages to this account. In JSON, uses hexadecimal. No more than 33 bytes. | +| TickSize | Number | UInt8 | (Optional) How many significant digits to use for exchange rates of Offers involving currencies issued by this address. Valid values are `3` to `15`, inclusive. _(Requires the [TickSize amendment](concept-amendments.html#ticksize).)_ | | TransferRate | Number | UInt32 | (Optional) A [transfer fee](https://ripple.com/knowledge_center/transfer-fees/) to charge other users for sending currency issued by this account to each other. | | Domain | String | VariableLength | (Optional) A domain associated with this account. In JSON, this is the hexadecimal for the ASCII representation of the domain. | diff --git a/content/reference-transaction-format.md b/content/reference-transaction-format.md index 00382530a5..3e5211af4d 100644 --- a/content/reference-transaction-format.md +++ b/content/reference-transaction-format.md @@ -406,6 +406,7 @@ Example AccountSet: | MessageKey | String | PubKey | (Optional) Public key for sending encrypted messages to this account. Conventionally, it should be a secp256k1 key, the same encryption that is used by the rest of Ripple. | | [SetFlag](#accountset-flags) | Unsigned Integer | UInt32 | (Optional) Integer flag to enable for this account. | | [TransferRate](#transferrate) | Unsigned Integer | UInt32 | (Optional) The fee to charge when users transfer this account's issuances, represented as billionths of a unit. Use `0` to set no fee. | +| [TickSize](#ticksize) | Unsigned Integer | UInt8 | (Optional) Tick size to use for offers involving a currency issued by this address. The exchange rates of those offers is rounded to this many significant digits. Valid values are `3` to `15` inclusive, or `0` to disable. _(Requires the [TickSize amendment](concept-amendments.html#ticksize).)_ | | WalletLocator | String | Hash256 | (Optional) Not used. | | WalletSize | Unsigned Integer | UInt32 | (Optional) Not used. | @@ -541,14 +542,14 @@ An offer in the ledger can be fulfilled either by additional OfferCreate transac You can create an offer so long as you have at least some (any positive, nonzero amount) of the currency specified by the `TakerGets` parameter of the offer. The offer sells as much of the currency as you have, up to the `TakerGets` amount, until the `TakerPays` amount is satisfied. An offer cannot place anyone in debt. -It is possible for an offer to become temporarily or permanently *unfunded*: +It is possible for an offer to become temporarily or permanently _unfunded_: * If the creator no longer has any of the `TakerGets` currency. - * The offer becomes funded again when the creator obtains more of that currency. + * The offer becomes funded again when the creator obtains more of that currency. * If the currency required to fund the offer is held in a [frozen trust line](concept-freeze.html). - * The offer becomes funded again when the trust line is no longer frozen. + * The offer becomes funded again when the trust line is no longer frozen. * If the creator does not have enough XRP for the reserve amount of a new trust line required by the offer. (See [Offers and Trust](#offers-and-trust).) - * The offer becomes funded again when the creator obtains more XRP, or the reserve requirements decrease. + * The offer becomes funded again when the creator obtains more XRP, or the reserve requirements decrease. * If the Expiration time included in the offer is before the close time of the most recently-closed ledger. (See [Expiration](#expiration).) An unfunded offer can stay on the ledger indefinitely, but it does not have any effect. The only ways an offer can be *permanently* removed from the ledger are: @@ -576,9 +577,20 @@ A trust line indicates an issuer you trust enough to accept their issuances as p ### Offer Preference ### -Existing offers are grouped by "quality", which is measured as the ratio between `TakerGets` and `TakerPays`. Offers with a higher quality are taken preferentially. (That is, the person accepting the offer receives as much as possible for the amount of currency they pay out.) Offers with the same quality are taken on the basis of which offer was placed in the earliest ledger version. +Existing offers are grouped by exchange rate (sometimes called "offer quality"), which is measured as the ratio between `TakerGets` and `TakerPays`. Offers with a higher exchange rate are taken preferentially. (That is, the person accepting the offer receives as much as possible for the amount of currency they pay out.) Offers with the same exchange rate are taken on the basis of which offer was placed in the earliest ledger version. + +When offers of the same exchange rate are placed in the same ledger version, the order in which they are taken is determined by the [canonical order](https://github.com/ripple/rippled/blob/release/src/ripple/app/misc/CanonicalTXSet.cpp "Source: Transaction ordering") in which the transactions were [applied to the ledger](https://github.com/ripple/rippled/blob/5425a90f160711e46b2c1f1c93d68e5941e4bfb6/src/ripple/app/consensus/LedgerConsensus.cpp#L1435-L1538 "Source: Applying transactions"). This behavior is designed to be deterministic, efficient, and hard to game. + +#### TickSize + +_Requires the [TickSize amendment](concept-amendments.html#ticksize)._ + +When an Offer is placed into an order book, its exchange rate is truncated based on the `TickSize` values set by the issuers of the currencies involved in the Offer. When a trader offers to exchange XRP and an issued currency, the `TickSize` from the issuer of the currency applies. When a trader offers to exchange two issued currencies, the offer uses the smaller `TickSize` value (that is, the one with fewer significant digits). If neither currency has a `TickSize` set, the default behavior applies. + +The `TickSize` value truncates the number of _significant digits_ in the exchange rate of an offer when it gets placed in an order book. Issuers can set `TickSize` to an integer from `3` to `15` using an [AccountSet transaction](#accountset). The exchange rate is represented as a number of significant digits plus an exponent; the `TickSize` does not affect the exponent. This allows the Ripple Consensus Ledger to represent exchange rates between assets that value greatly in absolute amounts (for example, a hyperinflated currency compared to a rare commodity). The lower the `TickSize` an issuer sets, the larger the increment traders must offer to be considered a higher exchange rate than the existing Offers. + +The `TickSize` does not affect the portion of an Offer that can be executed immediately. (For that reason, OfferCreate transactions with `tfImmediateOrCancel` are unaffected by `TickSize` values.) If the Offer cannot be fully executed, the transaction processing engine calculates the exchange rate and truncates it based on `TickSize`. Then, the engine rounds the remaining amount of the Offer from the "less important" side to match the truncated exchange rate. For a default OfferCreate transaction (a "buy" Offer), the `TakerGets` amount (the amount being bought) gets rounded. If the `tfSell` flag is enabled (a "sell" Offer) the `TakerPays` amount (the amount being sold) gets rounded. -When offers of the same quality are placed in the same ledger version, the order in which they are taken is determined by the [canonical order](https://github.com/ripple/rippled/blob/f65cea66ef99b1de149c02c15f06de6c61abf360/src/ripple/app/misc/CanonicalTXSet.cpp "Source: Transaction ordering") in which the transactions were [applied to the ledger](https://github.com/ripple/rippled/blob/5425a90f160711e46b2c1f1c93d68e5941e4bfb6/src/ripple/app/consensus/LedgerConsensus.cpp#L1435-L1538 "Source: Applying transactions"). This behavior is designed to be deterministic, efficient, and hard to game. ### Expiration ### diff --git a/reference-ledger-format.html b/reference-ledger-format.html index 5b896bf92f..30717f9a4c 100644 --- a/reference-ledger-format.html +++ b/reference-ledger-format.html @@ -394,6 +394,12 @@ + + + + + + diff --git a/reference-transaction-format.html b/reference-transaction-format.html index d84eed9094..829dd4debf 100644 --- a/reference-transaction-format.html +++ b/reference-transaction-format.html @@ -703,6 +703,12 @@ + + + + + + @@ -941,12 +947,18 @@

You can create an offer so long as you have at least some (any positive, nonzero amount) of the currency specified by the TakerGets parameter of the offer. The offer sells as much of the currency as you have, up to the TakerGets amount, until the TakerPays amount is satisfied. An offer cannot place anyone in debt.

It is possible for an offer to become temporarily or permanently unfunded:

An unfunded offer can stay on the ledger indefinitely, but it does not have any effect. The only ways an offer can be permanently removed from the ledger are:

@@ -967,8 +979,13 @@

However, holding non-XRP balances still requires a trust line to the address issuing those balances. When an offer is taken, it automatically creates any necessary trust lines, setting their limits to 0. Because trust lines increase the reserve an account must hold, any offers that would require a new trust line also require the address to have enough XRP to meet the reserve for that trust line.

A trust line indicates an issuer you trust enough to accept their issuances as payment, within limits. Offers are explicit instructions to acquire certain issuances, so they are allowed to go beyond those limits.

Offer Preference

-

Existing offers are grouped by "quality", which is measured as the ratio between TakerGets and TakerPays. Offers with a higher quality are taken preferentially. (That is, the person accepting the offer receives as much as possible for the amount of currency they pay out.) Offers with the same quality are taken on the basis of which offer was placed in the earliest ledger version.

-

When offers of the same quality are placed in the same ledger version, the order in which they are taken is determined by the canonical order in which the transactions were applied to the ledger. This behavior is designed to be deterministic, efficient, and hard to game.

+

Existing offers are grouped by exchange rate (sometimes called "offer quality"), which is measured as the ratio between TakerGets and TakerPays. Offers with a higher exchange rate are taken preferentially. (That is, the person accepting the offer receives as much as possible for the amount of currency they pay out.) Offers with the same exchange rate are taken on the basis of which offer was placed in the earliest ledger version.

+

When offers of the same exchange rate are placed in the same ledger version, the order in which they are taken is determined by the canonical order in which the transactions were applied to the ledger. This behavior is designed to be deterministic, efficient, and hard to game.

+

TickSize

+

Requires the TickSize amendment.

+

When an Offer is placed into an order book, its exchange rate is truncated based on the TickSize values set by the issuers of the currencies involved in the Offer. When a trader offers to exchange XRP and an issued currency, the TickSize from the issuer of the currency applies. When a trader offers to exchange two issued currencies, the offer uses the smaller TickSize value (that is, the one with fewer significant digits). If neither currency has a TickSize set, the default behavior applies.

+

The TickSize value truncates the number of significant digits in the exchange rate of an offer when it gets placed in an order book. Issuers can set TickSize to an integer from 3 to 15 using an AccountSet transaction. The exchange rate is represented as a number of significant digits plus an exponent; the TickSize does not affect the exponent. This allows the Ripple Consensus Ledger to represent exchange rates between assets that value greatly in absolute amounts (for example, a hyperinflated currency compared to a rare commodity). The lower the TickSize an issuer sets, the larger the increment traders must offer to be considered a higher exchange rate than the existing Offers.

+

The TickSize does not affect the portion of an Offer that can be executed immediately. (For that reason, OfferCreate transactions with tfImmediateOrCancel are unaffected by TickSize values.) If the Offer cannot be fully executed, the transaction processing engine calculates the exchange rate and truncates it based on TickSize. Then, the engine rounds the remaining amount of the Offer from the "less important" side to match the truncated exchange rate. For a default OfferCreate transaction (a "buy" Offer), the TakerGets amount (the amount being bought) gets rounded. If the tfSell flag is enabled (a "sell" Offer) the TakerPays amount (the amount being sold) gets rounded.

Expiration

Since transactions can take time to propagate and confirm, the timestamp of a ledger is used to determine offer validity. An offer only expires when its Expiration time is before the most-recently validated ledger. In other words, an offer with an Expiration field is still considered "active" if its expiration time is later than the timestamp of the most-recently validated ledger, regardless of what your local clock says.

You can determine the final disposition of an offer with an Expiration as soon as you see a fully-validated ledger with a close time equal to or greater than the expiration time.

(Optional) A public key that may be used to send encrypted messages to this account. In JSON, uses hexadecimal. No more than 33 bytes.
TickSizeNumberUInt8(Optional) How many significant digits to use for exchange rates of Offers involving currencies issued by this address. Valid values are 3 to 15, inclusive. (Requires the TickSize amendment.)
TransferRate Number UInt32(Optional) The fee to charge when users transfer this account's issuances, represented as billionths of a unit. Use 0 to set no fee.
TickSizeUnsigned IntegerUInt8(Optional) Tick size to use for offers involving a currency issued by this address. The exchange rates of those offers is rounded to this many significant digits. Valid values are 3 to 15 inclusive, or 0 to disable. (Requires the TickSize amendment.)
WalletLocator String Hash256