Add useUpgradedAuth simulation flag for CAP-71 v2 address credentials (#1568)

* feat(rpc): add useUpgradedAuth flag to simulateTransaction (CAP-71)

* test(e2e): add temp CAP-71 useUpgradedAuth v2-credentials test

* ci(e2e): bump quickstart to protocol 27 / rpc 27.1.1 for useUpgradedAuth

Author: Ryang-21

.github/workflows/e2e.yml

@@ -18,17 +18,18 @@ jobs:
         job: ["test:e2e"]
     services:
       rpc:
-        # This image's core supports up to protocol 25. guides_pr.yml pins a
-        # newer digest running protocol 27 (the guides document protocol-27
-        # behavior) — when bumping either workflow's image, check the other.
-        image: stellar/quickstart:testing@sha256:e09b46445243c966557073e4947642153e515bb3fa0c8b26d92ed3b7cdce3ba2
+        # This image runs core v27.1.0 (protocol 27) and stellar-rpc 27.1.1,
+        # which supports the `useUpgradedAuth` simulation flag (CAP-71) that
+        # use-upgraded-auth.test.ts exercises. guides_pr.yml pins its own
+        # digest — when bumping either workflow's image, check the other.
+        image: stellar/quickstart:testing@sha256:c8f1a95e43f5c0ff0b3d2ce6c3db008ccb0754ffa50175c4e0ef06b9d643b490
         ports:
           - 8000:8000
         env:
           ENABLE_LOGS: true
           NETWORK: local
           ENABLE_SOROBAN_RPC: true
-          PROTOCOL_VERSION: 25
+          PROTOCOL_VERSION: 27
         options: >-
           --health-cmd "curl --no-progress-meter --fail-with-body -X POST
           \"http://localhost:8000/soroban/rpc\" -H 'Content-Type:

CHANGELOG.md

@@ -5,6 +5,7 @@ A breaking change will get clearly marked in this log.
 ## Unreleased
 
 ### Added
+- `rpc.Server.simulateTransaction` accepts an optional `useUpgradedAuth` flag, and `contract.AssembledTransaction` accepts it as a method option (`useUpgradedAuth`) or per-call (`tx.simulate({ useUpgradedAuth: true })`). When set, RPC simulation records v2 address credentials (CAP-71) instead of the legacy v1 credentials. It only affects the recording auth modes and is silently ignored on hosts that cannot emit v2 credentials. The flag is deprecated from the start: it is transitional and becomes a no-op once the network returns v2 credentials by default (protocol 28) ([#1562](https://github.com/stellar/js-stellar-sdk/issues/1562)).
 - `@stellar/stellar-sdk/base` subpath export: import offline primitives like `StrKey` and `Keypair` without loading Horizon, RPC, or the SEP helpers and their networking dependencies([#1550](https://github.com/stellar/js-stellar-sdk/pull/1550)).
 - `authorizeEntry` / `authorizeInvocation` signing callbacks now receive the 32-byte signing payload (`hash(preimage.toXDR())`) as a second argument alongside the preimage, so signers — including HSMs and remote signers that only accept a digest — never have to re-derive it. Existing single-argument callbacks are unaffected ([#1532](https://github.com/stellar/js-stellar-sdk/issues/1532)).
 - `authorizeEntry` / `authorizeInvocation` now support non-Ed25519 signers: the signing callback may return `{ signatureScVal: xdr.ScVal, address?: string }`, and the given `ScVal` is written verbatim as the credentials' signature — no Ed25519 verification, no `{public_key, signature}` map, no `scvVec` wrapping. This lets smart-wallet / custom-account contracts (whose `__check_auth` expects its own signature structure) use the helper instead of hand-rolling preimage construction and credential assembly. The optional `address` routes the signature to a specific credential node, like `forAddress` ([#1530](https://github.com/stellar/js-stellar-sdk/issues/1530)).

docs/reference/contracts-client.md

@@ -230,7 +230,7 @@ class AssembledTransaction<T> {
   sign(__namedParameters: { force?: boolean; signTransaction?: SignTransactionLike } = {}): Promise<void>;
   signAndSend(__namedParameters: { force?: boolean; signTransaction?: SignTransactionLike; watcher?: Watcher } = {}): Promise<SentTransaction<T>>;
   signAuthEntries(__namedParameters: { address?: string; authorizeEntry?: (entry: SorobanAuthorizationEntry, signer: Keypair | SigningCallback, validUntilLedgerSeq: number, networkPassphrase: string, forAddress?: string) => Promise<SorobanAuthorizationEntry>; expiration?: number | Promise<number>; signAuthEntry?: SignAuthEntryLike } = {}): Promise<void>;
-  simulate(__namedParameters: { restore?: boolean } = {}): Promise<AssembledTransaction<T>>;
+  simulate(__namedParameters: { restore?: boolean; useUpgradedAuth?: boolean } = {}): Promise<AssembledTransaction<T>>;
   toJSON(): string;
   toXDR(): string;
 }
@@ -423,23 +423,23 @@ returns `false`, then you need to call `signAndSend` on this transaction.
 readonly isReadCall: boolean;
 ```
 
-**Source:** [src/contract/assembled_transaction.ts:1108](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L1108)
+**Source:** [src/contract/assembled_transaction.ts:1117](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L1117)
 
 ### `assembledTransaction.result`
 
 ```ts
 readonly result: T;
 ```
 
-**Source:** [src/contract/assembled_transaction.ts:742](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L742)
+**Source:** [src/contract/assembled_transaction.ts:751](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L751)
 
 ### `assembledTransaction.simulationData`
 
 ```ts
 readonly simulationData: { result: SimulateHostFunctionResult; transactionData: SorobanTransactionData };
 ```
 
-**Source:** [src/contract/assembled_transaction.ts:699](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L699)
+**Source:** [src/contract/assembled_transaction.ts:708](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L708)
 
 ### `assembledTransaction.needsNonInvokerSigningBy(__namedParameters)`
 
@@ -469,7 +469,7 @@ needsNonInvokerSigningBy(__namedParameters: { includeAlreadySigned?: boolean } =
 
 - **`__namedParameters`** — `{ includeAlreadySigned?: boolean }` (optional) (default: `{}`)
 
-**Source:** [src/contract/assembled_transaction.ts:935](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L935)
+**Source:** [src/contract/assembled_transaction.ts:944](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L944)
 
 ### `assembledTransaction.restoreFootprint(restorePreamble, account)`
 
@@ -504,7 +504,7 @@ Client initialization.
 - - Throws a custom error if the
 restore transaction fails, providing the details of the failure.
 
-**Source:** [src/contract/assembled_transaction.ts:1137](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L1137)
+**Source:** [src/contract/assembled_transaction.ts:1146](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L1146)
 
 ### `assembledTransaction.send(watcher)`
 
@@ -521,7 +521,7 @@ send(watcher?: Watcher): Promise<SentTransaction<T>>;
 
 - **`watcher`** — `Watcher` (optional)
 
-**Source:** [src/contract/assembled_transaction.ts:860](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L860)
+**Source:** [src/contract/assembled_transaction.ts:869](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L869)
 
 ### `assembledTransaction.sign(__namedParameters)`
 
@@ -536,7 +536,7 @@ sign(__namedParameters: { force?: boolean; signTransaction?: SignTransactionLike
 
 - **`__namedParameters`** — `{ force?: boolean; signTransaction?: SignTransactionLike }` (optional) (default: `{}`)
 
-**Source:** [src/contract/assembled_transaction.ts:770](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L770)
+**Source:** [src/contract/assembled_transaction.ts:779](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L779)
 
 ### `assembledTransaction.signAndSend(__namedParameters)`
 
@@ -555,7 +555,7 @@ signAndSend(__namedParameters: { force?: boolean; signTransaction?: SignTransact
 
 - **`__namedParameters`** — `{ force?: boolean; signTransaction?: SignTransactionLike; watcher?: Watcher }` (optional) (default: `{}`)
 
-**Source:** [src/contract/assembled_transaction.ts:878](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L878)
+**Source:** [src/contract/assembled_transaction.ts:887](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L887)
 
 ### `assembledTransaction.signAuthEntries(__namedParameters)`
 
@@ -582,17 +582,17 @@ signAuthEntries(__namedParameters: { address?: string; authorizeEntry?: (entry:
 
 - **`__namedParameters`** — `{ address?: string; authorizeEntry?: (entry: SorobanAuthorizationEntry, signer: Keypair | SigningCallback, validUntilLedgerSeq: number, networkPassphrase: string, forAddress?: string) => Promise<SorobanAuthorizationEntry>; expiration?: number | Promise<number>; signAuthEntry?: SignAuthEntryLike }` (optional) (default: `{}`)
 
-**Source:** [src/contract/assembled_transaction.ts:996](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L996)
+**Source:** [src/contract/assembled_transaction.ts:1005](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L1005)
 
 ### `assembledTransaction.simulate(__namedParameters)`
 
 ```ts
-simulate(__namedParameters: { restore?: boolean } = {}): Promise<AssembledTransaction<T>>;
+simulate(__namedParameters: { restore?: boolean; useUpgradedAuth?: boolean } = {}): Promise<AssembledTransaction<T>>;
 ```
 
 **Parameters**
 
-- **`__namedParameters`** — `{ restore?: boolean }` (optional) (default: `{}`)
+- **`__namedParameters`** — `{ restore?: boolean; useUpgradedAuth?: boolean }` (optional) (default: `{}`)
 
 **Source:** [src/contract/assembled_transaction.ts:646](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L646)
 
@@ -825,7 +825,7 @@ _before_ transaction signing.
 const DEFAULT_TIMEOUT: number
 ```
 
-**Source:** [src/contract/types.ts:298](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/types.ts#L298)
+**Source:** [src/contract/types.ts:311](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/types.ts#L311)
 
 ## contract.KeypairSigner
 
@@ -915,7 +915,7 @@ An impossible account on the Stellar network
 const NULL_ACCOUNT: "GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF"
 ```
 
-**Source:** [src/contract/types.ts:304](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/types.ts#L304)
+**Source:** [src/contract/types.ts:317](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/types.ts#L317)
 
 ## contract.SentTransaction
 
@@ -1582,7 +1582,7 @@ basicNodeSigner(keypair: Keypair, networkPassphrase: string): { signAuthEntry: S
 type AssembledTransactionOptions<T = string> = MethodOptions & ClientOptions & { address?: string; args?: any[]; method: string; parseResultXdr: (xdr: xdr.ScVal) => T; submit?: boolean; submitUrl?: string }
 ```
 
-**Source:** [src/contract/types.ts:266](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/types.ts#L266)
+**Source:** [src/contract/types.ts:279](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/types.ts#L279)
 
 ### contract.ClientOptions
 
@@ -1633,7 +1633,7 @@ message: string;
 Options for a smart contract method invocation.
 
 ```ts
-type MethodOptions = { fee?: string; publicKey?: string; restore?: boolean; signAuthEntry?: SignAuthEntryLike; signTransaction?: SignTransactionLike; simulate?: boolean; timeoutInSeconds?: number }
+type MethodOptions = { fee?: string; publicKey?: string; restore?: boolean; signAuthEntry?: SignAuthEntryLike; signTransaction?: SignTransactionLike; simulate?: boolean; timeoutInSeconds?: number; useUpgradedAuth?: boolean }
 ```
 
 **Source:** [src/contract/types.ts:207](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/types.ts#L207)

docs/reference/network-rpc.md

@@ -110,7 +110,7 @@ class Server {
   _getTransaction(hash: string): Promise<RawGetTransactionResponse>;
   _getTransactions(request: GetTransactionsRequest): Promise<RawGetTransactionsResponse>;
   _sendTransaction(transaction: Transaction | FeeBumpTransaction): Promise<RawSendTransactionResponse>;
-  _simulateTransaction(transaction: Transaction | FeeBumpTransaction, addlResources?: ResourceLeeway, authMode?: SimulationAuthMode): Promise<RawSimulateTransactionResponse>;
+  _simulateTransaction(transaction: Transaction | FeeBumpTransaction, addlResources?: ResourceLeeway, authMode?: SimulationAuthMode, useUpgradedAuth?: boolean): Promise<RawSimulateTransactionResponse>;
   fundAddress(address: string, friendbotUrl?: string): Promise<GetSuccessfulTransactionResponse>;
   getAccount(address: string): Promise<Account>;
   getAccountEntry(address: string): Promise<AccountEntry>;
@@ -139,7 +139,7 @@ class Server {
   queryContract<T = any>(contractId: string, method: string, args: Record<string, unknown> = {}, networkPassphrase?: string): Promise<{ isReadCall: boolean; result: T }>;
   requestAirdrop(address: string | Pick<Account, "accountId">, friendbotUrl?: string): Promise<Account>;
   sendTransaction(transaction: Transaction | FeeBumpTransaction): Promise<SendTransactionResponse>;
-  simulateTransaction(tx: Transaction | FeeBumpTransaction, addlResources?: ResourceLeeway, authMode?: SimulationAuthMode): Promise<SimulateTransactionResponse>;
+  simulateTransaction(tx: Transaction | FeeBumpTransaction, addlResources?: ResourceLeeway, authMode?: SimulationAuthMode, useUpgradedAuth?: boolean): Promise<SimulateTransactionResponse>;
 }
 ```
 
@@ -236,7 +236,7 @@ _getLedgers(request: GetLedgersRequest): Promise<RawGetLedgersResponse>;
 
 - **`request`** — `GetLedgersRequest` (required)
 
-**Source:** [src/rpc/server.ts:1773](https://github.com/stellar/js-stellar-sdk/blob/main/src/rpc/server.ts#L1773)
+**Source:** [src/rpc/server.ts:1788](https://github.com/stellar/js-stellar-sdk/blob/main/src/rpc/server.ts#L1788)
 
 ### `server._getTransaction(hash)`
 
@@ -272,21 +272,22 @@ _sendTransaction(transaction: Transaction | FeeBumpTransaction): Promise<RawSend
 
 - **`transaction`** — `Transaction | FeeBumpTransaction` (required)
 
-**Source:** [src/rpc/server.ts:1409](https://github.com/stellar/js-stellar-sdk/blob/main/src/rpc/server.ts#L1409)
+**Source:** [src/rpc/server.ts:1424](https://github.com/stellar/js-stellar-sdk/blob/main/src/rpc/server.ts#L1424)
 
-### `server._simulateTransaction(transaction, addlResources, authMode)`
+### `server._simulateTransaction(transaction, addlResources, authMode, useUpgradedAuth)`
 
 ```ts
-_simulateTransaction(transaction: Transaction | FeeBumpTransaction, addlResources?: ResourceLeeway, authMode?: SimulationAuthMode): Promise<RawSimulateTransactionResponse>;
+_simulateTransaction(transaction: Transaction | FeeBumpTransaction, addlResources?: ResourceLeeway, authMode?: SimulationAuthMode, useUpgradedAuth?: boolean): Promise<RawSimulateTransactionResponse>;
 ```
 
 **Parameters**
 
 - **`transaction`** — `Transaction | FeeBumpTransaction` (required)
 - **`addlResources`** — `ResourceLeeway` (optional)
 - **`authMode`** — `SimulationAuthMode` (optional)
+- **`useUpgradedAuth`** — `boolean` (optional)
 
-**Source:** [src/rpc/server.ts:1256](https://github.com/stellar/js-stellar-sdk/blob/main/src/rpc/server.ts#L1256)
+**Source:** [src/rpc/server.ts:1269](https://github.com/stellar/js-stellar-sdk/blob/main/src/rpc/server.ts#L1269)
 
 ### `server.fundAddress(address, friendbotUrl)`
 
@@ -339,7 +340,7 @@ console.log("Contract funded! Hash:", tx.txHash);
 
 - `Friendbot docs`
 
-**Source:** [src/rpc/server.ts:1532](https://github.com/stellar/js-stellar-sdk/blob/main/src/rpc/server.ts#L1532)
+**Source:** [src/rpc/server.ts:1547](https://github.com/stellar/js-stellar-sdk/blob/main/src/rpc/server.ts#L1547)
 
 ### `server.getAccount(address)`
 
@@ -775,7 +776,7 @@ the fee stats
 
 - https://developers.stellar.org/docs/data/rpc/api-reference/methods/getFeeStats
 
-**Source:** [src/rpc/server.ts:1578](https://github.com/stellar/js-stellar-sdk/blob/main/src/rpc/server.ts#L1578)
+**Source:** [src/rpc/server.ts:1593](https://github.com/stellar/js-stellar-sdk/blob/main/src/rpc/server.ts#L1593)
 
 ### `server.getHealth()`
 
@@ -961,7 +962,7 @@ const nextPage = await server.getLedgers({
 
 - `getLedgers docs`
 
-**Source:** [src/rpc/server.ts:1757](https://github.com/stellar/js-stellar-sdk/blob/main/src/rpc/server.ts#L1757)
+**Source:** [src/rpc/server.ts:1772](https://github.com/stellar/js-stellar-sdk/blob/main/src/rpc/server.ts#L1772)
 
 ### `server.getNetwork()`
 
@@ -1049,7 +1050,7 @@ console.log(
 - - getLedgerEntries
  - https://developers.stellar.org/docs/tokens/stellar-asset-contract
 
-**Source:** [src/rpc/server.ts:1642](https://github.com/stellar/js-stellar-sdk/blob/main/src/rpc/server.ts#L1642)
+**Source:** [src/rpc/server.ts:1657](https://github.com/stellar/js-stellar-sdk/blob/main/src/rpc/server.ts#L1657)
 
 ### `server.getTransaction(hash)`
 
@@ -1180,7 +1181,7 @@ the version info
 
 - https://developers.stellar.org/docs/data/rpc/api-reference/methods/getVersionInfo
 
-**Source:** [src/rpc/server.ts:1592](https://github.com/stellar/js-stellar-sdk/blob/main/src/rpc/server.ts#L1592)
+**Source:** [src/rpc/server.ts:1607](https://github.com/stellar/js-stellar-sdk/blob/main/src/rpc/server.ts#L1607)
 
 ### `server.pollTransaction(hash, opts)`
 
@@ -1309,7 +1310,7 @@ server.sendTransaction(transaction).then(result => {
 - - module:rpc.assembleTransaction
  - `simulateTransaction docs`
 
-**Source:** [src/rpc/server.ts:1348](https://github.com/stellar/js-stellar-sdk/blob/main/src/rpc/server.ts#L1348)
+**Source:** [src/rpc/server.ts:1363](https://github.com/stellar/js-stellar-sdk/blob/main/src/rpc/server.ts#L1363)
 
 ### `server.queryContract(contractId, method, args, networkPassphrase)`
 
@@ -1417,7 +1418,7 @@ server
 - - `Friendbot docs`
  - `Friendbot.Api.Response`
 
-**Source:** [src/rpc/server.ts:1454](https://github.com/stellar/js-stellar-sdk/blob/main/src/rpc/server.ts#L1454)
+**Source:** [src/rpc/server.ts:1469](https://github.com/stellar/js-stellar-sdk/blob/main/src/rpc/server.ts#L1469)
 
 ### `server.sendTransaction(transaction)`
 
@@ -1478,15 +1479,15 @@ server.sendTransaction(transaction).then((result) => {
 - - `transaction docs`
  - `sendTransaction docs`
 
-**Source:** [src/rpc/server.ts:1403](https://github.com/stellar/js-stellar-sdk/blob/main/src/rpc/server.ts#L1403)
+**Source:** [src/rpc/server.ts:1418](https://github.com/stellar/js-stellar-sdk/blob/main/src/rpc/server.ts#L1418)
 
-### `server.simulateTransaction(tx, addlResources, authMode)`
+### `server.simulateTransaction(tx, addlResources, authMode, useUpgradedAuth)`
 
 Submit a trial contract invocation to get back return values, expected
 ledger footprint, expected authorizations, and expected costs.
 
 ```ts
-simulateTransaction(tx: Transaction | FeeBumpTransaction, addlResources?: ResourceLeeway, authMode?: SimulationAuthMode): Promise<SimulateTransactionResponse>;
+simulateTransaction(tx: Transaction | FeeBumpTransaction, addlResources?: ResourceLeeway, authMode?: SimulationAuthMode, useUpgradedAuth?: boolean): Promise<SimulateTransactionResponse>;
 ```
 
 **Parameters**
@@ -1503,6 +1504,15 @@ simulateTransaction(tx: Transaction | FeeBumpTransaction, addlResources?: Resour
      auth mode to use for simulation: `enforce` for enforcement mode,
      `record` for recording mode, or `record_allow_nonroot` for recording
      mode that allows non-root authorization
+- **`useUpgradedAuth`** — `boolean` (optional) — (optional) opt simulation into recording
+     v2 address credentials (CAP-71) instead of the legacy v1 address
+     credentials. Best-effort: it only affects the recording auth modes and
+     is silently ignored on protocol versions whose host cannot emit v2
+     credentials.
+  
+     **Deprecated**: this flag is transitional. Once the network returns v2
+     credentials by default (protocol 28), it becomes a no-op — do not rely
+     on omitting it to keep receiving the legacy v1 format.
 
 **Returns**
 
@@ -1544,7 +1554,7 @@ server.simulateTransaction(transaction).then((sim) => {
  - module:rpc.Server#prepareTransaction
  - module:rpc.assembleTransaction
 
-**Source:** [src/rpc/server.ts:1246](https://github.com/stellar/js-stellar-sdk/blob/main/src/rpc/server.ts#L1246)
+**Source:** [src/rpc/server.ts:1255](https://github.com/stellar/js-stellar-sdk/blob/main/src/rpc/server.ts#L1255)
 
 ## rpc.assembleTransaction