CAP-0071: Authentication delegation and address-bound Soroban credentials

CAP: 0071
Title: Authentication delegation and address-bound Soroban credentials
Working Group:
        Owner: Dmytro Kozhevin <@dmkozh>
        Authors: Dmytro Kozhevin <@dmkozh>
        Consulted: 
Status: Final
Created: 2025-09-10
Discussion: https://github.com/orgs/stellar/discussions/1784
Protocol version: 27

Simple Summary

Split CAP-71 into a delegation-focused sub-CAP and a follow-on sub-CAP for SOROBAN_CREDENTIALS_ADDRESS_V2.

Working Group

As specified in the Preamble.

Motivation

CAP-71 covers two closely related changes to Soroban authorization:

delegated authentication for custom accounts; and
an address-bound credential type for non-delegated address authorization.

Both changes rely on the same address-bound authorization payload format, but they solve different protocol problems and are easier to review separately.

Goals Alignment

This CAP is aligned with the following Stellar Network Goals: - The Stellar Network should be secure and reliable. - The Stellar Network should make it easy for developers of Stellar projects to create highly usable products

Abstract

This CAP is an overview of two related Soroban authorization changes. CAP-71-01 specifies authentication delegation for custom accounts. CAP-71-02 specifies SOROBAN_CREDENTIALS_ADDRESS_V2, which allows non-delegated address credentials to use the same address-bound authorization payload.

Specification

The detailed specifications are split into the following sub-CAPs:

XDR changes

This is the final cumulative XDR diff for the CAP-71 split, based on the XDR files in commit cff714a5ebaaaf2dac343b3546c2df73f0b7a36e of stellar-xdr.

diff --git a/Stellar-ledger-entries.x b/Stellar-ledger-entries.x
index b9a9a16..348311c 100644
--- a/Stellar-ledger-entries.x
+++ b/Stellar-ledger-entries.x
@@ -664,7 +664,8 @@ enum EnvelopeType
    ENVELOPE_TYPE_OP_ID = 6,
    ENVELOPE_TYPE_POOL_REVOKE_OP_ID = 7,
    ENVELOPE_TYPE_CONTRACT_ID = 8,
-    ENVELOPE_TYPE_SOROBAN_AUTHORIZATION = 9
+    ENVELOPE_TYPE_SOROBAN_AUTHORIZATION = 9,
+    ENVELOPE_TYPE_SOROBAN_AUTHORIZATION_WITH_ADDRESS = 10
 };
 
 enum BucketListType
diff --git a/Stellar-transaction.x b/Stellar-transaction.x
index c22f5b4..e6c3b10 100644
--- a/Stellar-transaction.x
+++ b/Stellar-transaction.x
@@ -569,10 +569,24 @@ struct SorobanAddressCredentials
    SCVal signature;
 };
 
+struct SorobanDelegateSignature {
+    SCAddress address;
+    SCVal signature;
+    SorobanDelegateSignature nestedDelegates<>;
+};
+
+struct SorobanAddressCredentialsWithDelegates
+{
+    SorobanAddressCredentials addressCredentials;
+    SorobanDelegateSignature delegates<>;
+};
+
 enum SorobanCredentialsType
 {
    SOROBAN_CREDENTIALS_SOURCE_ACCOUNT = 0,
-    SOROBAN_CREDENTIALS_ADDRESS = 1
+    SOROBAN_CREDENTIALS_ADDRESS = 1,
+    SOROBAN_CREDENTIALS_ADDRESS_V2 = 2,
+    SOROBAN_CREDENTIALS_ADDRESS_WITH_DELEGATES = 3
 };
 
 union SorobanCredentials switch (SorobanCredentialsType type)
@@ -581,6 +595,10 @@ case SOROBAN_CREDENTIALS_SOURCE_ACCOUNT:
    void;
 case SOROBAN_CREDENTIALS_ADDRESS:
    SorobanAddressCredentials address;
+case SOROBAN_CREDENTIALS_ADDRESS_V2:
+    SorobanAddressCredentials addressV2;
+case SOROBAN_CREDENTIALS_ADDRESS_WITH_DELEGATES:
+    SorobanAddressCredentialsWithDelegates addressWithDelegates;
 };
 
 /* Unit of authorization data for Soroban.
@@ -731,6 +749,15 @@ case ENVELOPE_TYPE_SOROBAN_AUTHORIZATION:
        uint32 signatureExpirationLedger;
        SorobanAuthorizedInvocation invocation;
    } sorobanAuthorization;
+case ENVELOPE_TYPE_SOROBAN_AUTHORIZATION_WITH_ADDRESS:
+    struct
+    {
+        Hash networkID;
+        int64 nonce;
+        uint32 signatureExpirationLedger;
+        SCAddress address;
+        SorobanAuthorizedInvocation invocation;
+    } sorobanAuthorizationWithAddress;
 };
 
 enum MemoType

Protocol Upgrade Transition

The changes described by the sub-CAPs become available in protocol 27.

Backwards Incompatibilities

See the sub-CAPs.

Resource Utilization

See the sub-CAPs.

Security Concerns

See the sub-CAPs.

Test Cases

See the sub-CAPs.

Implementation

TBD