protocol 27 - V2 credential opt in (#1450)

* make V2 credential usage opt-in

Author: Ryang-21

CHANGELOG.md

@@ -6,6 +6,25 @@ A breaking change will get clearly marked in this log.
 
 ## Unreleased
 
+### Changed
+
+- Soroban auth defaults back to the legacy `SOROBAN_CREDENTIALS_ADDRESS` (V1)
+  credential, with the CAP-71 `SOROBAN_CREDENTIALS_ADDRESS_V2` credential now
+  available behind an opt-in instead of forced on. `ADDRESS_V2` is only valid on
+  networks that have activated CAP-71, so emitting it before activation would
+  fail submission; the opt-in keeps the default safe while letting you exercise
+  V2 against networks that already support it. The default will flip to V2 once
+  the protocol makes it mandatory. ([#1450](https://github.com/stellar/js-stellar-sdk/pull/1450))
+  - `rpc.Server.simulateTransaction` gained a 4th optional argument,
+    `authV2` (default `false`). When `true`, the `authV2` request flag is sent so
+    simulation returns `ADDRESS_V2` auth entries; otherwise the flag is omitted
+    and legacy `ADDRESS` entries are returned.
+  - `authorizeInvocation` gained an optional `authV2` field on its params object
+    (default `false`) selecting between `ADDRESS` and `ADDRESS_V2` credentials.
+  - `contract.Client` / `AssembledTransaction` accept `authV2` in
+    `MethodOptions`, threaded through to simulation.
+
+
 ## v16.0.0-rc.1
 
 There are a few major updates in this release:

docs/guides/00-migration.md

@@ -381,37 +381,57 @@ If your code reached through the SDK for any of these, declare them yourself now
 Protocol 27 ([CAP-71](https://github.com/stellar/stellar-protocol/blob/master/core/cap-0071.md))
 adds two address-bound Soroban credential types, `AddressV2` and
 `AddressWithDelegates`. This only affects code that signs Soroban authorization
-entries or inspects their credential arms. Depending on the network and RPC
-simulation behavior, authorization entries may contain either the legacy
-`ADDRESS` credential or the newer `ADDRESS_V2` credential. Both are valid for SDK
-signing flows that use the helpers below.
+entries or inspects their credential arms.
+
+By default the SDK still uses the legacy `ADDRESS` credential: simulation is
+asked for `ADDRESS` entries and `authorizeInvocation` builds them. `ADDRESS_V2`
+is only valid on networks that have upgraded to protocol 27, so it is **opt-in** until
+ protocol 28 makes it mandatory (at which point the default flips). Opt in with
+the `authV2` flag — on
+`rpc.Server.simulateTransaction`,
+on `authorizeInvocation`'s params, or via `authV2` in
+[`contract.Client`](/reference/contracts-client/#contractclient) /
+`MethodOptions` — when your target network supports it.
 
 SDK-driven signing ([`contract.Client`](/reference/contracts-client/#contractclient),
 [`basicNodeSigner`](/reference/contracts-client/#contractbasicnodesigner),
 [`authorizeEntry`](/reference/core-soroban-primitives/#authorizeentry),
 [`signAuthEntries`](/reference/contracts-client/#contractassembledtransaction)) is
-forward-compatible with no code change: it signs whichever credential simulation
-returns. The entries below break only code that reads the credential arm or
-builds the signature payload by hand.
+forward-compatible with no code change: it signs whichever credential the entry
+carries, `ADDRESS` or `ADDRESS_V2`. The entries below break only code that reads
+the credential arm or builds the signature payload by hand.
 
 For the full walkthrough of signing Soroban authorization entries, see
 [Authorize a Contract Call](/guides/07-contract-auth/).
 
-### Auth: `authorizeInvocation` now returns `AddressV2`
+### Auth: `authorizeInvocation` takes a params object
 
 [`authorizeInvocation`](/reference/core-soroban-primitives/#authorizeinvocation) now
-takes a single params object and builds `SOROBAN_CREDENTIALS_ADDRESS_V2` entries
-instead of legacy `ADDRESS`. Read the
-result with `.addressV2()`.
+takes a single params object instead of positional arguments. It still builds a
+legacy `SOROBAN_CREDENTIALS_ADDRESS` entry by default, so keep reading the result
+with `.address()`.
 
-```ts del={1-4} ins={5-8}
+```ts del={1-4} ins={5-7}
 const entry = await authorizeInvocation(
   signer, validUntilLedgerSeq, invocation, publicKey, networkPassphrase,
 )
-const addr = entry.credentials().address()
 const entry = await authorizeInvocation({
   signer, validUntilLedgerSeq, invocation, networkPassphrase, publicKey,
 })
+const addr = entry.credentials().address()
+```
+
+To build a CAP-71 `ADDRESS_V2` entry instead, pass `authV2: true` and read the
+result with `.addressV2()`. Only do this on networks that have upgraded to protocol 27.
+
+```ts ins={6}
+const entry = await authorizeInvocation({
+  signer,
+  validUntilLedgerSeq,
+  invocation,
+  networkPassphrase,
+  authV2: true,
+})
 const addr = entry.credentials().addressV2()
 ```
 
@@ -471,15 +491,6 @@ and rejects duplicates, as the protocol requires), then route each signer's
 signature with `forAddress`. Every signer signs the same payload, bound to the
 top-level address.
 
-### Auth: closed export surface
-
-The auth module's wildcard re-export was replaced with an explicit allow-list. The
-package root now exports exactly `authorizeEntry`, `authorizeInvocation`,
-`buildAuthorizationEntryPreimage`, `buildWithDelegatesEntry`, and the types
-`SigningCallback`, `AuthorizeInvocationParams`, `DelegateSignature`,
-`BuildWithDelegatesParams`. Anything else imported from the auth module (notably
-`getAddressCredentials`, now internal) no longer resolves.
-
 ### Earlier 15.x deprecation: `BalanceResponse.revocable`
 
 On [`BalanceResponse`](/reference/network-rpc/#rpcapibalanceresponse), use

docs/reference/contracts-client.md

@@ -423,23 +423,23 @@ returns `false`, then you need to call `signAndSend` on this transaction.
 readonly isReadCall: boolean;
 ```
 
-**Source:** [src/contract/assembled_transaction.ts:1089](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L1089)
+**Source:** [src/contract/assembled_transaction.ts:1094](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L1094)
 
 ### `assembledTransaction.result`
 
 ```ts
 readonly result: T;
 ```
 
-**Source:** [src/contract/assembled_transaction.ts:738](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L738)
+**Source:** [src/contract/assembled_transaction.ts:743](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L743)
 
 ### `assembledTransaction.simulationData`
 
 ```ts
 readonly simulationData: { result: SimulateHostFunctionResult; transactionData: SorobanTransactionData };
 ```
 
-**Source:** [src/contract/assembled_transaction.ts:695](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L695)
+**Source:** [src/contract/assembled_transaction.ts:700](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L700)
 
 ### `assembledTransaction.needsNonInvokerSigningBy(__namedParameters)`
 
@@ -469,7 +469,7 @@ needsNonInvokerSigningBy(__namedParameters: { includeAlreadySigned?: boolean } =
 
 - **`__namedParameters`** — `{ includeAlreadySigned?: boolean }` (optional) (default: `{}`)
 
-**Source:** [src/contract/assembled_transaction.ts:924](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L924)
+**Source:** [src/contract/assembled_transaction.ts:929](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L929)
 
 ### `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:1118](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L1118)
+**Source:** [src/contract/assembled_transaction.ts:1123](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L1123)
 
 ### `assembledTransaction.send(watcher)`
 
@@ -521,7 +521,7 @@ send(watcher?: Watcher): Promise<SentTransaction<T>>;
 
 - **`watcher`** — `Watcher` (optional)
 
-**Source:** [src/contract/assembled_transaction.ts:853](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L853)
+**Source:** [src/contract/assembled_transaction.ts:858](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L858)
 
 ### `assembledTransaction.sign(__namedParameters)`
 
@@ -536,7 +536,7 @@ sign(__namedParameters: { force?: boolean; signTransaction?: SignTransaction } =
 
 - **`__namedParameters`** — `{ force?: boolean; signTransaction?: SignTransaction }` (optional) (default: `{}`)
 
-**Source:** [src/contract/assembled_transaction.ts:766](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L766)
+**Source:** [src/contract/assembled_transaction.ts:771](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L771)
 
 ### `assembledTransaction.signAndSend(__namedParameters)`
 
@@ -555,7 +555,7 @@ signAndSend(__namedParameters: { force?: boolean; signTransaction?: SignTransact
 
 - **`__namedParameters`** — `{ force?: boolean; signTransaction?: SignTransaction; watcher?: Watcher }` (optional) (default: `{}`)
 
-**Source:** [src/contract/assembled_transaction.ts:871](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L871)
+**Source:** [src/contract/assembled_transaction.ts:876](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L876)
 
 ### `assembledTransaction.signAuthEntries(__namedParameters)`
 
@@ -582,7 +582,7 @@ 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?: SignAuthEntry }` (optional) (default: `{}`)
 
-**Source:** [src/contract/assembled_transaction.ts:985](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L985)
+**Source:** [src/contract/assembled_transaction.ts:990](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/assembled_transaction.ts#L990)
 
 ### `assembledTransaction.simulate(__namedParameters)`
 
@@ -791,7 +791,7 @@ _before_ transaction signing.
 const DEFAULT_TIMEOUT: number
 ```
 
-**Source:** [src/contract/types.ts:292](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/types.ts#L292)
+**Source:** [src/contract/types.ts:302](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/types.ts#L302)
 
 ## contract.NULL_ACCOUNT
 
@@ -801,7 +801,7 @@ An impossible account on the Stellar network
 const NULL_ACCOUNT: "GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF"
 ```
 
-**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:308](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/types.ts#L308)
 
 ## contract.SentTransaction
 
@@ -1341,7 +1341,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:260](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/types.ts#L260)
+**Source:** [src/contract/types.ts:270](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/types.ts#L270)
 
 ### contract.ClientOptions
 
@@ -1392,7 +1392,7 @@ message: string;
 Options for a smart contract method invocation.
 
 ```ts
-type MethodOptions = { fee?: string; publicKey?: string; restore?: boolean; signAuthEntry?: SignAuthEntry; signTransaction?: SignTransaction; simulate?: boolean; timeoutInSeconds?: number }
+type MethodOptions = { authV2?: boolean; fee?: string; publicKey?: string; restore?: boolean; signAuthEntry?: SignAuthEntry; signTransaction?: SignTransaction; simulate?: boolean; timeoutInSeconds?: number }
 ```
 
 **Source:** [src/contract/types.ts:203](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/types.ts#L203)