diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 0000000..b1bc858 Binary files /dev/null and b/.DS_Store differ diff --git a/docs/.DS_Store b/docs/.DS_Store new file mode 100644 index 0000000..7c9d2c6 Binary files /dev/null and b/docs/.DS_Store differ diff --git a/docs/LedgerStateFix/.DS_Store b/docs/LedgerStateFix/.DS_Store new file mode 100644 index 0000000..5008ddf Binary files /dev/null and b/docs/LedgerStateFix/.DS_Store differ diff --git a/docs/LedgerStateFix/index.md b/docs/LedgerStateFix/index.md new file mode 100644 index 0000000..07cf9ce --- /dev/null +++ b/docs/LedgerStateFix/index.md @@ -0,0 +1,66 @@ +--- +seo: + description: Repair corruptions to the XRP ledger. +labels: + - Utilities, troubleshooting +--- +# LedgerStateFix +[[Source]]() + +`LedgerStateFix` is a general purpose transaction used to fix specific issues affecting the XRP ledger. You submit the transaction with the `LedgerFixType` value set to indicate the particular error state to correct. + +_(Added by the [fixNFTokenPageLinks amendment][].)_ + +## Example LedgerStateFix JSON + +```json +{ + "Account" : "", + "Fee" : "2000000", + "LedgerFixType" : 1, + "Owner" : ", + "SigningPubKey" : "", + "TransactionType" : "LedgerStateFix", + "TxnSignature" : "", +} +``` + + +| Field | Data Type | Required? | Description | +|:------|:-----------|:----------|:------------| +| `TransactionType` | uint16 | Required | Identifies this as a `LedgerStateFix` transaction. | +| `Account` | STAccount | Required | Identifies the account signing and submitting the transaction as well as paying the Fee. | +| `Fee` | STAmount | Required | This transaction is rare and potentially compute intensive. The minimum fee is the same as the fee for an AccountDelete transaction. If the transaction fails with a tec code, the fee is still charged. | +| `Flags` | uint32 | Optional | Not needed for `LedgerFixType` == _1_. Reserved for a future type of ledger fix. | +| `LedgerFixType` | uint16 | Required | Currently the only type is _1_, which fixes the NFToken directory for a single account. | +| `Owner` | STAccount | Optional | Required if `LedgerFixType` == _1_, the account ID that owns the NFToken directory that needs fixing. Need not have any relationship to Account. | + +## LedgerStateFix Flags + +Transactions of the LedgerStateFix type can support additional values in the `Flags` field. Currently, there are no flags defined. A future `LedgerFixType` might require flag settings. + +## Error Cases + +Potential errors are those that can occur for all transactions. {% $frontmatter.seo.title %}. + +## LedgerStateFix Types + +`LedgerStateFix` might sound like a general panacea for all your ledger's ills, but in practice it is a targeted solution for very rare, known, and specific issues. + +### Type 1 + +There are two different transactions that introduced corruptions to NFT directories. In both cases, the following conditions were met: + +- There were at least two NFToken pages in the directory. +- The next-to-last page was completely full, holding 32 NFTokens. +- The very last page of the directory contained only one NFToken. +- The transaction removed the last remaining token from the last page. + +When these conditions were met, the last NFToken page was removed and the next-to-last page was left as the final page in the directory. + +That would be fine, except the NFToken directory has an expectation that the last page has a specific index. The page with that index was just deleted. When an NFToken is added to the directory, and that token has a high enough value that it doesn't belong on the current last page, then a new last page is created that has no links to the previous page, creating a hole in the middle of the list. + +The `fixNFTokenPageLinks` amendment modifies the NFToken page, coalescing code to notice when the very last page of the directory would be removed. In that case, it moves all of the contents of the next lower page into the last page and deletes the next-to-last page. It then fixes up the links. + +New invariant checks also validate aspects of the links on pages, so a similar corruption returns a tecINVARIANT_FAILED transaction result. That will prevent this specific type of corruption going forward. diff --git a/docs/index.md b/docs/index.md index 074fb1b..44e9e17 100644 --- a/docs/index.md +++ b/docs/index.md @@ -25,3 +25,6 @@ To learn more about the consensus process and the workflow for features to go fr - [XLS-56d Batch Transactions](xls-56d-batch-transactions/index.md) - [Reference](xls-56d-batch-transactions/reference/reference.md) + +### LedgerStateFix +- [LedgerStateFix](LedgerStateFix/index.md) diff --git a/index.mdx b/index.mdx index dbbda5e..0b08ff1 100644 --- a/index.mdx +++ b/index.mdx @@ -89,4 +89,36 @@ export default LandingContainer; - \ No newline at end of file + + + + + + + + `LedgerStateFix` is a general purpose transaction used to fix specific + issues affecting the XRP ledger. You submit the transaction with the + `LedgerFixType` set to indicate the particular error state to correct. + +
+ +
+ + + diff --git a/ledgerstatefix.md b/ledgerstatefix.md new file mode 100644 index 0000000..ff386d2 --- /dev/null +++ b/ledgerstatefix.md @@ -0,0 +1,67 @@ +--- +seo: + description: Repair corruptions to the XRP ledger. +labels: + - Utilities, troubleshooting +--- +# LedgerStateFix +[[Source]]() + +`LedgerStateFix` is a general purpose transaction used to fix specific issues affecting the XRP ledger. You submit the transaction with the `LedgerFixType` value set to indicate the particular error state to correct. + +_(Added by the [fixNFTokenPageLinks amendment][].)_ + +## Example LedgerStateFix JSON + +```json +{ + "Account" : "", + "Fee" : "2000000", + "LedgerFixType" : 1, + "Owner" : ", + "SigningPubKey" : "", + "TransactionType" : "LedgerStateFix", + "TxnSignature" : "", +} +``` + +{% raw-partial file="/docs/_snippets/tx-fields-intro.md" /%} + +| Field | Data Type | Required? | Description | +|:------|:-----------|:----------|:------------| +| `TransactionType` | uint16 | Required | Identifies this as a `LedgerStateFix` transaction. | +| `Account` | STAccount | Required | Identifies the account signing and submitting the transaction as well as paying the Fee. | +| `Fee` | STAmount | Required | This transaction is rare and potentially compute intensive. The minimum fee is the same as the fee for an AccountDelete transaction. If the transaction fails with a tec code, the fee is still charged. | +| `Flags` | uint32 | Optional | Not needed for `LedgerFixType` == _1_. Reserved for a future type of ledger fix. | +| `LedgerFixType` | uint16 | Required | Currently the only type is _1_, which fixes the NFToken directory for a single account. | +| `Owner` | STAccount | Optional | Required if `LedgerFixType` == _1_, the account ID that owns the NFToken directory that needs fixing. Need not have any relationship to Account. | + +## LedgerStateFix Flags + +Transactions of the LedgerStateFix type can support additional values in the `Flags` field. Currently, there are no flags defined. A future `LedgerFixType` might require flag settings. + +## Error Cases + +Potential errors are those that can occur for all transactions. {% $frontmatter.seo.title %}. + +## LedgerStateFix Types + +`LedgerStateFix` might sound like a general panacea for all your ledger's ills, but in practice it is a targeted solution for very rare, known, and specific issues. + +### Type 1 + +There are two different transactions that introduced corruptions to NFT directories. In both cases, the following conditions were met: + +- There were at least two NFToken pages in the directory. +- The next-to-last page was completely full, holding 32 NFTokens. +- The very last page of the directory contained only one NFToken. +- The transaction removed the last remaining token from the last page. + +When these conditions were met, the last NFToken page was removed and the next-to-last page was left as the final page in the directory. + +That would be fine, except the NFToken directory has an expectation that the last page has a specific index. The page with that index was just deleted. When an NFToken is added to the directory, and that token has a high enough value that it doesn't belong on the current last page, then a new last page is created that has no links to the previous page, creating a hole in the middle of the list. + +The `fixNFTokenPageLinks` amendment modifies the NFToken page, coalescing code to notice when the very last page of the directory would be removed. In that case, it moves all of the contents of the next lower page into the last page and deletes the next-to-last page. It then fixes up the links. + +New invariant checks also validate aspects of the links on pages, so a similar corruption returns a tecINVARIANT_FAILED transaction result. That will prevent this specific type of corruption going forward. diff --git a/sidebars.yaml b/sidebars.yaml index 92065f5..9727c29 100644 --- a/sidebars.yaml +++ b/sidebars.yaml @@ -44,3 +44,6 @@ opensource: pages: - page: docs/xls-56d-batch-transactions/reference/batch.md - page: docs/xls-56d-batch-transactions/reference/common-fields.md + - group: LedgerStateFix + page: docs/LedgerStateFix/index.md + expanded: false