Address-bound Soroban address credentials

CAP: 0071-02
Title: Address-bound Soroban address credentials
Working Group:
    Owner: Dmytro Kozhevin <@dmkozh>
    Authors: Dmytro Kozhevin <@dmkozh>
    Consulted: 
Status: Final
Created: 2026-04-27
Discussion: https://github.com/orgs/stellar/discussions/1899
Protocol version: 27

Simple Summary

Add SOROBAN_CREDENTIALS_ADDRESS_V2 so non-delegated address credentials can use the address-bound Soroban authorization payload.

Working Group

As specified in the Preamble.

Motivation

The signature payload for SOROBAN_CREDENTIALS_ADDRESS does not include the signer's address. This is not a problem for most of the common use cases, as the invocation payload typically includes the signer's address. Even when it does not, the signature is still cryptographically bound to the credentials owner. However, in the rare case that multiple accounts share the same private keys and the invocation payload does not otherwise bind the signer address, using the legacy ENVELOPE_TYPE_SOROBAN_AUTHORIZATION payload would allow potential replay attacks between accounts sharing the same keys.

This CAP introduces a new credential type that fixes the issue by adding the address to the default signature payload, so that there is no way to ever reuse a signature across accounts, even if the invocation payload does not bind the signer address and the keys are shared.

Goals Alignment

This CAP is aligned with the following Stellar Network Goals:

- The Stellar Network should be secure and reliable.

Abstract

SOROBAN_CREDENTIALS_ADDRESS_V2 is introduced in order to allow address credentials to use the ENVELOPE_TYPE_SOROBAN_AUTHORIZATION_WITH_ADDRESS signature payload.

The semantics of the new credential type are the same as for the existing SOROBAN_CREDENTIALS_ADDRESS, with the only difference being the signature payload it uses.

Specification

XDR changes

The final cumulative XDR diff for CAP-71 is in CAP-71. The XDR change relevant to this sub-CAP is the introduction of SOROBAN_CREDENTIALS_ADDRESS_V2.

Semantics

SOROBAN_CREDENTIALS_ADDRESS_V2 credential type

SOROBAN_CREDENTIALS_ADDRESS_V2 credential type is introduced in order to allow using ENVELOPE_TYPE_SOROBAN_AUTHORIZATION_WITH_ADDRESS signature payload for non-delegation cases.

The semantics of the new credential type are the same as for the existing SOROBAN_CREDENTIALS_ADDRESS, with the only difference being that the signature payload is SHA-256 hash of HashIDPreimage XDR with ENVELOPE_TYPE_SOROBAN_AUTHORIZATION_WITH_ADDRESS variant.

Design Rationale

New credentials type

It would be possible to make a 'hard' switch to the new signature payload preimage at protocol boundary, i.e. with the protocol 27 upgrade the required signature payload would be using ENVELOPE_TYPE_SOROBAN_AUTHORIZATION_WITH_ADDRESS preimage variant. However, this would make the upgrade disruptive for users, as it would effectively invalidate any client that hasn't managed to update to the new preimage type. The migration itself would also be tricky as clients would need to track the protocol version in order to make a decision on which preimage type to use.

Thus, in order to reduce disruption and simplify the migration, we introduce a new credential type, so that clients can explicitly choose to use the new preimage type at any point in time after protocol 27 upgrade.

No deprecation of SOROBAN_CREDENTIALS_ADDRESS

The existing SOROBAN_CREDENTIALS_ADDRESS credential type is safe for the overwhelming majority of use cases, and as described in the previous section, the hard switch to the new preimage type would be too disruptive. Thus, we keep the existing credential type and preimage type valid, so that clients can choose to switch to the new preimage type at their own pace, and there is no rush to update clients immediately after protocol 27 upgrade.

However, in the future protocol (28 or later) we may want to consider deprecating the old credential type and preimage type, given that the clients will have had enough time to migrate to the new credentials and preimage type.

Protocol Upgrade Transition

The new credential type will only be available starting from protocol 27. Including it into a transaction before protocol 27 will invalidate the transaction.

Backwards Incompatibilities

This CAP does not introduce any backward incompatibilities. However, the old credential type may be considered deprecated in the future.

Resource Utilization

There is no significant impact on resource utilization. The new credential type is slightly larger than the old one and the preimage is slightly more expensive to hash, but the difference is negligible in the context of typical transaction sizes.

Security Concerns

This CAP improves replay protection for non-delegated address credentials in shared-key scenarios.

Test Cases

TBD

Implementation

TBD