ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-20 03:35:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

Start fixing up Permission Delegation docs

Browse Source
This commit is contained in:
mDuo13
2025-07-23 16:48:23 -07:00
parent 30b5ba68f1
commit a2d754b40f
5 changed files with 139 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
docs/concepts/accounts/deleting-accounts.md
View File

@@ -19,14 +19,22 @@ After an account has been deleted, it can be re-created in the ledger through th
To be deleted, an account must meet the following requirements:
- The account's `Sequence` number plus 256 must be less than the current [Ledger Index][].
- The account must not be linked to any of the following types of [ledger entries](../../references/protocol/ledger-data/ledger-entry-types/index.md) (as a sender or receiver):
- `Escrow`
- `PayChannel`
- `RippleState`
- `Check`
- The account must not have any "deletion blockers" in its owner directory. This includes cases where the account is a sender _or_ receiver of funds. See below for a full list of deletion blockers.
- The account must own fewer than 1000 objects in the ledger.
- The transaction must pay a special [transaction cost][] equal to at least the [owner reserve](reserves.md) for one item (currently {% $env.PUBLIC_OWNER_RESERVE %}).
### Deletion Blockers
The following [ledger entry types](../../references/protocol/ledger-data/ledger-entry-types/index.md) are deletion blockers:
- `Escrow`
- `PayChannel`
- `RippleState` (trust line)
- `Check`
- `PermissionedDomain` _(Requires the [PermissionedDomains amendment][] {% not-enabled /%})_
Any other types of ledger entries that an account owns are automatically deleted along with the account.
## Cost of Deleting
{% admonition type="danger" name="Warning" %}The [AccountDelete transaction][]'s transaction cost always applies when the transaction is included in a validated ledger, even if the transaction failed because the account does not meet the requirements to be deleted. To greatly reduce the chances of paying the high transaction cost if the account cannot be deleted, use the `fail_hard` option when submitting an AccountDelete transaction.{% /admonition %}

68
docs/references/protocol/data-types/permission-values.md Normal file
View File

@@ -0,0 +1,68 @@
---
seo:
description: Format for permissions that can be granted to other accounts.
label:
- Permissions
---
# Permission Values
The Permission Delegation amendment {% not-enabled /%} defines permissions that can be granted to other accounts. These permissions fall into three categories:
- **Full Permissions** - Permission to send transactions of any type.
- **Transaction Type Permissions** - Permission to send transactions with the specified [transaction type](../transactions/types/index.md).
- **Granular Permissions** - Permission to send transactions with a specific subset of functionality.
## Numeric and String Values
In the [canonical binary format](../binary-format.md) for transactions and ledger data, permission values are stored in a numeric form (specifically, as a 32-bit unsigned integer). However, in JSON they can be specified and returned in string format for convenience, similar to how transaction type names (`TransactionType` fields) work.
When specifying a permission value in JSON, you can use either the numeric value or the string value. When serving data,
The numeric value `0` is reserved for "full permissions", meaning permission to send transactions of all types. ***TODO: but can you actually delegate full permissions?***
## Transaction Type Permissions
Transaction Type Permissions have numeric values from 1 to 65536 (2<sup>16</sup>), inclusive. They correspond with known transaction types, except you add 1 when specifying a transaction type as a permission value. For example, the string `"Payment"` corresponds to a `TransactionType` value of `0`, but a `PermissionValue` type of `1`. To grant permissions to make Payment transactions, you can specify either `"PermissionValue": "Payment"` or `"PermissionValue": 1`.
For a mapping of transaction types known by a server and their corresponding numeric transaction type values, check the `TRANSACTION_TYPES` field in the [server_definitions method][].
### List of Non-Delegatable Permissions
Some transaction types are not delegatable. If you attempt to grant these permissions to a delegate, the transaction fails with a [result code](../transactions/transaction-results/) such as `tecNO_PERMISSION`. This includes all transaction types that can be used to grant other permissions to different key pairs or accounts. Additionally, all [pseudo-transaction types](/docs/references/protocol/transactions/pseudo-transaction-types/pseudo-transaction-types) are not delegatable since they are not meant to be sent by normal accounts anyway.
The following permissions cannot be delegated:
| Transaction Type | Permission Value |
|:--------------------|:-----------------|
| [AccountSet][] | `4` |
| [SetRegularKey][] | `6` |
| [SignerListSet][] | `13` |
| [AccountDelete][] | `22` |
| [LedgerStateFix][] | `54` |
| [DelegateSet][] | `65` |
| [EnableAmendment][] | `101` |
| [SetFee][] | `102` |
| [UNLModify][] | `103` |
## Granular Permissions
[[Source]](https://github.com/XRPLF/rippled/blob/master/include/xrpl/protocol/detail/permissions.macro "Source")
Granular Permissions have numeric types of 65537 and up, corresponding to specific names of permissions. Values that are not defined are not allowed. Each granular permission is a subset of a single transaction type's functionality.
| Numeric Value | Name | Transaction Type | Description |
|:--------------|:-------------------------|:-----------------------|:------------|
| `65537` | `TrustlineAuthorize` | [TrustSet][] | Can [authorize individual trust lines](/docs/concepts/tokens/fungible-tokens/authorized-trust-lines). |
| `65538` | `TrustlineFreeze` | [TrustSet][] | Can [freeze individual trust lines](/docs/concepts/tokens/fungible-tokens/freezes). |
| `65539` | `TrustlineUnfreeze` | [TrustSet][] | Can [unfreeze individual trust lines](/docs/concepts/tokens/fungible-tokens/freezes). |
| `65540` | `AccountDomainSet` | [AccountSet][] | Can set the `Domain` field of the account. |
| `65541` | `AccountEmailHashSet` | [AccountSet][] | Can set the `EmailHash` field of the account. |
| `65542` | `AccountMessageKeySet` | [AccountSet][] | Can set the `MessageKey` field of the account. |
| `65543` | `AccountTransferRateSet` | [AccountSet][] | Can set the [transfer fee of fungible tokens issued by the account](/docs/concepts/tokens/transfer-fees). |
| `65544` | `AccountTickSizeSet` | [AccountSet][] | Can set the [tick size of fungible tokens issued by the account](/docs/concepts/tokens/decentralized-exchange/ticksize). |
| `65545` | `PaymentMint` | [Payment][] | Can send payments that mint new fungible tokens. ***TODO: Or MPTs? What about indirectly?*** |
| `65546` | `PaymentBurn` | [Payment][] | Can send payments that burn fungible tokens. ***TODO: Or MPTs? More clarification needed.*** |
| `65547` | `MPTokenIssuanceLock` | [MPTokenIssuanceSet][] | Can lock the balances of a particular MPT issued by the account. _(Requires the [MPTokensV1 amendment][] {% not-enabled /%}.)_ |
| `65548` | `MPTokenIssuanceUnlock` | [MPTokenIssuanceSet][] | Can unlock the balances of a particular MPT issued by the account. _(Requires the [MPTokensV1 amendment][] {% not-enabled /%}.)_ |
{% raw-partial file="/docs/_snippets/common-links.md" /%}

52
docs/references/protocol/ledger-data/ledger-entry-types/delegate.md Normal file
View File

@@ -0,0 +1,52 @@
---
seo:
description: A record of which permissions have been granted to another account.
labels:
- Accounts
- Permissions
---
# Delegate
[[Source]](https://github.com/XRPLF/rippled/blob/1e01cd34f7a216092ed779f291b43324c167167a/include/xrpl/protocol/detail/ledger_entries.macro#L475-L482 "Source")
A `Delegate` ledger entry stores a set of permissions that an account has delegated to another account. You create a `Delegate` entry by sending a [DelegateSet transaction][].
_(Requires the [PermissionDelegation amendment][] {% not-enabled /%}.)_
## Example {% $frontmatter.seo.title %} JSON
```json
TODO
```
## {% $frontmatter.seo.title %} Fields
In addition to the [common fields](../common-fields.md), {% code-page-name /%} entries have the following fields:
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:--------------------|:---------------------|:------------------|:----------|:-------------|
| `Account` | String - [Address][] | AccountID | Yes | The account delegating permissions to another, also called the _delegating account_. |
| `Authorize` | String - [Address][] | AccountID | Yes | The account receiving permissions, also called the _delegate account_. |
| `Permissions` | Array | Array | Yes | A list of permissions granted, with at least 1 and at most 10 items. Each item in the list is a [Permission Object](#permissions-objects). |
| `OwnerNode` | String - Hexadecimal | UInt64 | Yes | A hint indicating which page of the delegating account's owner directory links to this object, in case the directory consists of multiple pages.
| `PreviousTxnID` | String - Hexadecimal | UInt256 | Yes | The identifying hash of the transaction that most recently modified this object. |
| `PreviousTxnLgrSeq` | Number | UInt32 | Yes |The [index of the ledger][Ledger Index] that contains the transaction that most recently modified this object. |
### Permissions Objects
Each item in the `Permissions` array is an inner object with the following nested fields:
| Field | JSON Type | [Internal Type][] | Required? | Description |
|:------------------|:---------------------|:------------------|:----------|:----------------|
| `PermissionValue` | String | UInt32 | Yes | A permission that has been delegated to this account, which can be either a transaction type or a granular permission. See ***TODO: link*** for a full list. |
## {% $frontmatter.seo.title %} Flags
There are no flags defined for {% code-page-name /%} entries.
## {% $frontmatter.seo.title %} Reserve
{% code-page-name /%} entries count as one item towards the owner reserve of the delegating account, as long as the entry is in the ledger, regardless of how many permissions are delegating. Removing all permissions deletes the entry and frees up the reserve.
{% code-page-name /%} entries are not deletion blockers. If the owner (delegating) account is deleted, all such ledger entries are deleted along with them. However, the `Authorize`
{% raw-partial file="/docs/_snippets/common-links.md" /%}

39
docs/references/protocol/transactions/common-fields.md
View File

@@ -62,43 +62,14 @@ The [`Paths` field](types/payment.md#paths) of the [Payment transaction][] type
## Delegate
The `Delegate` ledger object stores a set of permissions that an XRPL account has delegated to another account. You create `Delegate` objects using the [`DelegateSet`](./types/delegateset.md) transaction.
If the `Delegate` field is provided, this transaction is being sent by a different account on behalf of the account in the `Account` field. The account in the `Account` is the _delegating account_ and the account in the `Delegate` field is the _delegate_ account. The transaction functions as if it was sent by the delegating account, with the following exceptions:
### Structure
- The signature must be valid for the delegate account. (It can by signed with a master key, regular key, or multi-signing list that is authorized by the delegate.)
- The transaction cost (in the `Fee` field) is paid by the delegate account.
A `Delegate` object has the following fields:
Sending a transaction this way is only possible if the delegating account has granted the appropriate transaction permissions to the delegate account.
| Field Name | Required? | JSON Type | Internal Type | Description |
|------------|-----------|-----------|---------------|-------------|
| `LedgerIndex` | ✔️ | string | Hash256 | The unique ID of the ledger object. |
| `LedgerEntryType` | ✔️ | string | UInt16 | The ledger object's type (`Delegate`) |
| `Account` | ✔️ | string | AccountID | The account that delegates permissions to another account. |
| `Authorize` | ✔️ | string | AccountID | The account to which permissions are delegated. |
| `Permissions` | ✔️ | string | STArray | The transaction permissions that the `Authorize` account has been granted. |
| `OwnerNode` | ✔️ | string | UInt64 | A hint indicating which page of the sender's owner directory links to this object, in case the directory consists of multiple pages. |
| `PreviousTxnID` | ✔️ | string | Hash256 | The identifying hash of the transaction that most recently modified this object. |
| `PreviousTxnLgrSeqNumber`| ✔️ | number | UInt32 |The index of the ledger that contains the transaction that most recently modified this object. |
### Retrieving Delegate Objects
You can retrieve `Delegate` ledger objects using the `ledger_entry` RPC method. The unique ID of a `Delegate` object is a hash of the `Account` and `Authorize` fields, combined with the unique space key for Delegate objects.
### Account Deletion
A `Delegate` object is not a deletion blocker. This means that deleting an account removes any `Delegate` objects associated with it.
### Example Delegate JSON
This sample `Delegate` object shows that the _rISAAC_ account has delegated `TrustLineAuthorize` permission to the _rKYLIE_ account.
```json
{
"LedgerEntryType": "Delegate",
"Account": "rISAAC......",
"Authorize": "rKYLIE......",
"Permissions": [{"Permission": {"PermissionValue": "TrustlineAuthorize"}}],
}
```
_(Requires the [PermissionDelegation amendment][] {% not-enabled /%}.)_
## Flags Field

1
sidebars.yaml
View File

@@ -350,6 +350,7 @@
- page: docs/references/protocol/ledger-data/ledger-entry-types/bridge.md
- page: docs/references/protocol/ledger-data/ledger-entry-types/check.md
- page: docs/references/protocol/ledger-data/ledger-entry-types/credential.md
- page: docs/references/protocol/ledger-data/ledger-entry-types/delegate.md
- page: docs/references/protocol/ledger-data/ledger-entry-types/depositpreauth.md
- page: docs/references/protocol/ledger-data/ledger-entry-types/did.md
- page: docs/references/protocol/ledger-data/ledger-entry-types/directorynode.md