0075 XLS-75d: Account Permission Delegation

[mvadari]

Title:       Account Permission Delegation
Revision:    1 (2024-08-21)

Author:      Mayukha Vadari

Affiliation: Ripple

Account Permission Delegation

Abstract

This proposal introduces a delegated authorization mechanism to enhance the flexibility and usability of XRPL accounts.

Currently, critical issuer actions, such as authorizing trustlines, require direct control by the account's keys, hindering operational efficiency and complex use cases. By empowering account holders to selectively delegate specific permissions to other accounts, this proposal aims to enhance account usability without compromising security. This mechanism will unlock new possibilities for XRPL applications, such as multi-party workflows and advanced account management strategies.

1. Overview

We propose:

• Creating a AccountPermission ledger object.
• Creating a AccountPermissionSet transaction type.

We also propose modifying the transaction common fields.

This feature will require an amendment, tentatively titled AccountPermission.

1.1. Terminology

• Delegating account: The main account, which is delegating permissions to another account.
• Delegated account: The account that is having permissions delegated to it.

1.2. Basic Flow

Isaac, a token issuer, wants to set up his account to follow security best practices and separation of responsibilities. He wants Alice to manage token issuing and Bob to manage trustlines. He is also working with Kylie, a KYC provider, who he wants to be able to authorize trustlines but not have any other permissions (as she is an external party).

He can authorize:

• Alice's account for the Payment transaction permission.
• Bob's account for the TrustSet transaction permission.
• Kylie's account for the TrustlineAuthorize granular permission.

The full set of available permissions is listed in XLS-74d, Account Permissions

2. On-Ledger Object: AccountPermission

This object represents a set of permissions that an account has delegated to another account, and is modeled to be similar to DepositPreauth objects.

2.1. Fields

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 (AccountPermission)
Account	✔️	string	AccountID	The account that wants to authorize another account.
Authorize	✔️	string	AccountID	The authorized account.
Permissions	✔️	string	STArray	The transaction permissions that the account has access to.
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.

2.1.1. Object ID

The ID of this object will be a hash of the Account and Authorize fields, combined with the unique space key for AccountPermission objects, which will be defined during implementation.

2.1.2. Permissions

This field is an array of permissions to delegate to the account, as listed in XLS-74d, Account Permissions. The array will have a maximum length of 10.

2.2. Account Deletion

The AccountPermission object is not a deletion blocker.

3. Transaction: AccountPermissionSet

This object represents a set of permissions that an account has delegated to another account, and is modeled to be similar to the DepositPreauth transaction type.

3.1. Fields

Field Name	Required?	JSON Type	Internal Type	Description
TransactionType	✔️	string	UInt16	The transaction type (AccountPermissionSet).
Account	✔️	string	AccountID	The account that wants to authorize another account.
Authorize	✔️	string	AccountID	The authorized account.
Permissions	✔️	string	STArray	The transaction permissions that the account has been granted.

3.1.1. Permissions

This transaction works slightly differently from the DepositPreauth transaction type. Instead of using an Unauthorize field, an account is unauthorized by using an empty Permissions list.

3.2. Failure Conditions

• Permissions is too long (the limit is 10), or includes duplicates.
• Any of the specified permissions are invalid.
• The account specified in Authorize doesn't exist.

3.3. State Changes

A AccountPermission object will be created, modified, or deleted based on the provided fields.

4. Transactions: Common Fields

4.1. Fields

As a reference, here are the fields that all transactions currently have.

We propose these modifications:

Field Name	Required?	JSON Type	Internal Type	Description
OnBehalfOf		string	AccountID	The account that the transaction is being sent on behalf of.

4.2. Failure Conditions

• The OnBehalfOf account doesn't exist.
• The OnBehalfOf account hasn't authorized the transaction's Account to send transactions on behalf of it.
• The OnBehalfOf account hasn't authorized the transaction's Account to send this particular transaction type/granular permission on behalf of it.

4.3. State Changes

The transaction succeeds as if the transaction was sent by the OnBehalfOf account.

5. Examples

5.1. Payment Permission

In this example, Isaac is delegating the Payment permission to Alice.

5.1.1. AccountPermissionSet Transaction

{
    TransactionType: "AccountPermissionSet",
    Account: "rISAAC......",
    Authorize: "rALICE......",
    Permissions: [{Permission: {PermissionValue: "Payment"}}],
}

Note: the weird format of Permissions, with needing an internal object, is due to peculiarities in the XRPL's Binary Format. It can be cleaned up/simplified in tooling.

5.1.2. AccountPermission Ledger Object

{
    LedgerEntryType: "AccountPermission",
    Account: "rISAAC......",
    Authorize: "rALICE......",
    Permissions: [{Permission: {PermissionValue: "Payment"}}],
}

5.1.3. Payment Transaction

{
    Transaction: "Payment",
    Account: "rALICE......",
    Amount: "1000000000",
    Destination: "rCHARLIE......",
    OnBehalfOf: "rISAAC......"
}

5.2. TrustSet Permission

In this example, Isaac is delegating the TrustSet permission to Bob.

5.2.1. AccountPermissionSet Transaction

{
    TransactionType: "AccountPermissionSet",
    Account: "rISAAC......",
    Authorize: "rBOB......",
    Permissions: [{Permission: {PermissionValue: "TrustSet"}}],
}

5.2.2. AccountPermission Ledger Object

{
    LedgerEntryType: "AccountPermission",
    Account: "rISAAC......",
    Authorize: "rBOB......",
    Permissions: [{Permission: {PermissionValue: "TrustSet"}}],
}

5.2.3. TrustSet Transaction

In this example, Bob is freezing a trustline from Holden, a USD.Isaac token holder.

{
    Transaction: "TrustSet",
    Account: "rBOB......",
    LimitAmount: {
        currency: "USD",
        issuer: "rHOLDEN......",
        value: "0",
    },
    Flags: 0x00100000, // tfSetFreeze
    OnBehalfOf: "rISAAC......"
}

5.3. TrustlineAuthorize Permission

In this example, Isaac is delegating the TrustlineAuthorize permission to Kylie.

5.3.1. AccountPermissionSet Transaction

{
    TransactionType: "AccountPermissionSet",
    Account: "rISAAC......",
    Authorize: "rKYLIE......",
    Permissions: [{Permission: {PermissionValue: "TrustlineAuthorize"}}],
}

5.3.2. AccountPermission Object

{
    LedgerEntryType: "AccountPermission",
    Account: "rISAAC......",
    Authorize: "rKYLIE......",
    Permissions: [{Permission: {PermissionValue: "TrustlineAuthorize"}}],
}

5.3.3. TrustSet Transaction

In this example, Kylie is authorizing Holden's trustline.

{
    Transaction: "TrustSet",
    Account: "rBOB......",
    LimitAmount: {
        currency: "USD",
        issuer: "rHOLDEN......",
        value: "0",
    },
    Flags: 0x00010000, // tfSetfAuth
    OnBehalfOf: "rISAAC......"
}

Note that this transaction will fail if:

• The trustline with Holden doesn't exist.
• Kylie tries to change any trustline setting that isn't just the tfSetfAuth flag.

6. Invariants

An account should never be able to send a transaction on behalf of another account without a valid AccountPermission object.

7. Security

Delegating permissions to other accounts requires a high degree of trust, especially when the delegated account can potentially access funds (Payments) or charge reserves (any transaction that can create objects). In addition, any account that has access to the entire AccountSet, SetRegularKey, SignerListSet, or AccountPermissionSet transactions can give themselves any permissions even if this was not originally part of the intention. Authorizing users for those transactions should have heavy warnings associated with it in tooling and UIs.

All tooling indicating whether an account has been blackholed will need to be updated to also check if AccountSet, SetRegularKey, SignerListSet, or AccountPermissionSet permissions have been delegated.

On the other hand, this mechanism also offers a granular approach to authorization, allowing accounts to selectively grant specific permissions without compromising overall account control. This approach provides a balance between security and usability, empowering account holders to manage their assets and interactions more effectively.

Appendix

Appendix A: Comparing with XLS-49d, Multiple Signer Lists

In XLS-49d:

• There is multisign support by default.
• The signer list is controlled by the delegating account.
• There may be at most one list per permission, with a maximum of 32 signers.
• There is a total of one reserve per signer list.
• The delegating account pays the fees.

In this proposal:

• There is no direct multisign support (though permissions can be delegated to an account with a multisign setup).
• The keys that have been delegated to are self-governed (i.e. the delegating account doesn't control the signer list on an account that has been delegated to).
• A permission may be delegated to as many accounts/signer lists as one is willing to pay reserve for.
• There is one reserve per delegated account.
• The delegated account pays the fees.

Both are useful for slightly different usecases; XLS-49d is more useful when you want multiple signatures to guard certain features, while this proposal is useful when you want certain parties to have access to certain features. This proposal does support XLS-49d-like usage, but it would cost more XRP, as a second account would need to be created.

Appendix B: FAQ

B.1: Who pays the transaction fees?

The account that sends the transaction pays the transaction fees (not the delegating account, but the delegated account).

B.2: How does using an NFTokenMint permission compare to using the existing NFTokenMinter account field?

Note that the NFTokenMinter field provides more permissions than just NFTokenMinting; it provides permissions over offers and burning as well (though of course multiple permissions can be delegated to one account).

The biggest advantage to using the NFTokenMint field is that it's "free" (it doesn't cost any additional reserve). Delegating a permission to an account costs one object reserve (for the AccountPermission object).

On the other hand, with this proposal, you can have as many accounts with the NFTokenMint permission as you want. The minting account can also mint NFTs directly into your account, instead of into their own account.

Given the overlap in functionality, the NFTokenMinter field could potentially be deprecated in the future.

B.3: Can a blackholed account have some permissions set?

Yes, in certain cases. For example, an account could still be considered "blackholed" if it has the AccountDomainSet permission delegated, but not if it has the SetRegularKey permission delegated. The definition of a blackholed account will need to be modified after this amendment.

B.4: Can I delegate permissions to a Batch transaction (XLS-56d)?

No, OnBehalfOf will not be allowed on Batch transactions. Instead, the inner transactions must include the OnBehalfOf field.

B.5: Why is the process of unauthorizing an account different between the DepositPreauth transaction and the AccountPermissionSet transaction?

The DepositPreauth transaction has an Unauthorize field. It seemed more confusing to use such a paradigm here, but it can be changed if there are strong objections.

[tequdev]

It must be documented about Batch transaction.

1. all transaction types are available for Inner transactions if Batch transaction type is permissioned
   OR
2. if Inner transaction transaction type is permissioned, Batch transaction is available
   OR
3. both Batch and Inner transaction types must be permissioned

[mvadari]

That's a good point. I added a section on it in XLS-74d and an FAQ question here. The OnBehalfOf field may not be used on a Batch transaction, and must be used on the inner transactions instead.

[joshuahamsa]

The ability for an issuer to “blackhole” an account (not delegating payments) while still retaining operational abilities for everything else via another account would be great! (Even greater 3 years ago but 😅 🤷🏻‍♂️)

[dangell7]

Wouldn't a TransactionTypeBitmask be better than a list? Seems like just updating the bitmask would be much easier than getting the current list and checking the list for duplicates. Also for tooling it would be easier imo.

[mvadari]

A bitmask doesn't allow for granular permissions, which are where a lot of the value comes from. See XLS-74d.

It also functionally caps the total number of transactions in rippled at 256, though I think that is a less important concern.

[yinyiqian1]

regarding 3.1 fields, do we need OwnerNode?

[mvadari]

Not on the transaction, but yes on the ledger object - good catch, just updated that.

[yinyiqian1]

Yes. my typo, it should be 2.1 fields. Thanks for updating.

[yinyiqian1]

A permission may be delegated to as many accounts/signer lists as one is willing to pay reserve for. There is one reserve per delegated account.

---

Since we use Account and Authorize as key, the key will be something like: keylet::accountPermission(account, authorize),
then the permission object on the ledger would be unique for a Account and Authorize pair.
If we wants to delegate the same permissions to two accounts, we need to create two permission objects even if sfPermissions field is the same. So a permission object can only be delegated to one account. And under this case, we can have the delegating account pay the reserve.

[mvadari]

Yes, that sounds correct.

[yinyiqian1]

Can we differentiate the transaction permission and granular permission in the json request by using TransactionPermission and GranularPermission field instead of PermissionValue so that we can parse these values easily, for example:

{
    "command": "submit",
    "tx_json" : {
      "TransactionType" : "AccountPermissionSet",
      "Account" : "rP5XKjUJk8S7fJs9F12YJFKGb8tvgwy5W",
      "Authorize" : "rGeQ2MufzFpdw8MEURxVx1DADi7BPbi9o3",
      "Permissions":[
        {"Permission": {"TransactionPermission": "TrustSet"}},
        {"Permission": {"TransactionPermission": "AMMCreate"}},
        {"Permission": {"GranularPermission": "TrustlineAuthorize"}}
      ]
   },
   "secret":"..."
}

[mvadari]

It doesn't feel very user-friendly to need different names depending on what type of value it is.

[yinyiqian1]

from code perspective, we are binding the field with the field type. You can refer to SFields.macro. It's better to define two types in the SFields.macro for Transaction level and Granular level permission object.
Otherwise, we need to use one type object of type UINT32 for both of them, and then do a cast in the STParsedJSON.cpp. To keep the code consistent and clean, it's better to have two type fields for them.

from user perspective, it's reasonable for them to have the knowledge that Permission type is different beforehand. These two object types have different field type (uint32 and uint16), it's normal that we give different field name for different object type in JSON.

[mvadari]

I think the Permission type should be UInt32 regardless of if it's granular or not. It'll also be easier to parse that way when you need to determine if someone has the right permissions to execute a transaction.

[ximinez]

@yinyiqian1

"secret":[....]

I hope this secret isn't used anywhere with real money. If it is, you need to rekey immediately.

[yinyiqian1]

No real money. just test in standalone mode. But I'll update that comment. Thanks for reminding.

[yinyiqian1]

Can we simplify the permission Permissions: [{Permission: {PermissionValue: "TrustlineAuthorize"}}] to Permissions: [{Permission: "TrustlineAuthorize"}]. for example:

"Permissions":[
        {"Permission": "TrustSet"},
        {"Permission": "AMMCreate"},
        {"Permission": "TrustlineAuthorize"}
      ]

[mvadari]

That's not possible. An STArray must contain STObjects, and an STObject must be represented as shown.

[yinyiqian1]

Should AccountPermissionSet transaction be banned from being delegated to other accounts?

[mvadari]

I would put it in the same category as AccountSet/SignerListSet/SetRegularKey.

[gregtatcam]

Permissions is an array of strings, which is pretty inefficient to store in the object. Should it be an array of UINT32 instead? I understand that we want to have a user-friendly permissions but UI can taker care of this.

[mvadari]

The intent was for them to be stored as UInt32s and converted to strings in the JSON representation (like TransactionType).

[gregtatcam]

You meant to say from strings, right? So we are going to use it sort of like enum and we can pass a string in UINT32, which if Permission is converted to UINT32. It doesn't feel right having arbitrary strings parsed as UINT32. Maybe it's better to have its own STI_PERMISSION type instead?

[mvadari]

It's not arbitrary strings, it's very specific values - just like how TransactionType is displayed as a string in the JSON representation, but is encoded as a UInt16 internally.

[gregtatcam]

arbitrary is wrong word. An enum name perhaps. TransactionType does set a precedent.

[mvadari]

I'm not opposed to adding a new SType for this, but it just seems like overkill to me.

[gregtatcam]

Shouldn't there be a transaction to delete AccountPermission?

[mvadari]

I was thinking an empty array would delete. If you'd rather have that be a separate transaction that's fine by me though.

[gregtatcam]

Either way is fine with me but I think we generally have a separate tx to delete.

[gregtatcam]

The first failure condition in 4.2. Failure Conditions is The OnBehalfOf account doesn't exist. but OnBehalfOf is an optional field.

[yinyiqian1]

I think it means when the OnBehalfOf is given, and it does not exist. Then give the failure.

[mvadari]

Yes, exactly.

[yinyiqian1]

there should be an RPC call like account_permission, right? Shall we add it in the spec?

[mvadari]

Why is that necessary? Easy enough to just look it up via ledger_entry, right?

[yinyiqian1]

can we also add it in the spec as well so that the users know the parameters? for example:

{
  "method": "ledger_entry",
  "params" : [
    {
      "account_permission": {
      "account": "...",
      "authorize": "..."
    },
    "ledger_index": "validated"
    }
  ]
}

[mvadari]

Per the XLS Contributing process, it is my opinion that we have reached a "well-refined standard."

As such, I propose that we move this discussion to a file (via #257) and work on final changes using additional PRs, for better change-tracking.

Please comment here if you would like to object to moving this spec/discussion forward in the process into a DRAFT spec.

(Note that per the Contributing guidelines, moving a spec into the DRAFT state does not mean any kind of endorsement, nor does it mean that this specification will become adopted. It is solely meant as a mechanism to enable better change tracking using PRs.)