protocol 27 - V2 credential opt in

[Ryang-21]

What

Soroban auth now defaults to the legacy SOROBAN_CREDENTIALS_ADDRESS (V1) credential, with CAP-71 SOROBAN_CREDENTIALS_ADDRESS_V2 available behind an opt-in instead of forced on. Three opt-in points, all defaulting to false:

• rpc.Server.simulateTransaction gains a 4th optional arg, authV2. The authV2 request flag is now omitted from the JSON-RPC
  body unless set, so simulation returns legacy ADDRESS entries by default and ADDRESS_V2 only when opted in. (Previously authV2: true was hardcoded.)
• authorizeInvocation gains an authV2 field on its params object, selecting between building ADDRESS and ADDRESS_V2
  credentials. (Previously it always built ADDRESS_V2.)
• MethodOptions.authV2 is threaded through AssembledTransaction.simulate(), so high-level contract.Client users can opt in
  too — not just direct RPC callers.

The V2 signing/handling path is unchanged: authorizeEntry and buildAuthorizationEntryPreimage already select the correct (legacy vs. address-bound) preimage off whichever credential the entry carries, so the SDK still consumes V2 transparently. Only emission is gated.

Includes test updates (default-path assertions flipped to V1, new authV2: true coverage, and a simulate request-body test), a CHANGELOG entry, and migration-guide + regenerated reference-doc updates.

Why

p27 adds the ability to submit ADDRESS_V2; p28 makes it mandatory. But V2 credentials are not valid on-network until p27 activates, so anything the SDK emits as V2 before activation fails submission. The branch currently forces V2 everywhere with no escape hatch, which means users on any not-yet-activated network — and testnet/futurenet/mainnet activate at different times — would hit failed submissions without a way to fall back.

Defaulting to V1 keeps the SDK valid on every network regardless of activation state and matches upstream's posture (RPC simulation and the sibling SDKs default to V1 with V2 opt-in); a client shouldn't emit a stricter default than its own upstream. The opt-in still lets early adopters exercise V2 against networks that already support it.

The default will flip to V2 at p28 when it becomes mandatory — a mechanical change (flip the two defaults; the opt-in params stay so anyone on a pre-p28 network can pin to V1 during the transition)

[quietbits]

Should we mention that Protocol 28 will make this mandatory and not the current Protocol 27 (if I understood it correctly)?

[Copilot]

Pull request overview

This PR makes Soroban auth credential emission default back to legacy SOROBAN_CREDENTIALS_ADDRESS (V1), with CAP-71 SOROBAN_CREDENTIALS_ADDRESS_V2 available only via an explicit opt-in, keeping SDK behavior compatible with networks that haven’t activated protocol 27 yet.

Changes:

• Add an authV2 opt-in to rpc.Server.simulateTransaction and omit authV2 from the JSON-RPC request unless enabled.
• Add authV2 to authorizeInvocation params to choose between emitting V1 vs V2 credentials.
• Thread MethodOptions.authV2 through contract.Client/AssembledTransaction.simulate(), and update tests + docs + changelog accordingly.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
test/unit/server/soroban/simulate_transaction.test.ts	Updates auth entry construction to V1 and adds coverage asserting authV2 is omitted by default / sent when opted in.
test/unit/base/auth.test.ts	Updates default credential expectations to V1 and adds explicit authV2: true coverage for V2 emission.
src/rpc/server.ts	Adds authV2 param (default false) and conditionally includes the JSON-RPC authV2 request flag.
src/contract/types.ts	Introduces MethodOptions.authV2 for higher-level contract client users.
src/contract/assembled_transaction.ts	Threads options.authV2 into server.simulateTransaction(...).
src/base/auth.ts	Adds AuthorizeInvocationParams.authV2 and switches emission default to legacy ADDRESS credentials.
docs/reference/network-rpc.md	Regenerated reference docs reflecting the new authV2 argument on simulation methods.
docs/reference/core-soroban-primitives.md	Regenerated reference docs describing authorizeInvocation and new authV2 param.
docs/reference/contracts-client.md	Regenerated reference docs reflecting MethodOptions.authV2.
docs/guides/00-migration.md	Updates migration guidance for protocol 27 defaults and opt-in usage.
CHANGELOG.md	Adds an Unreleased entry documenting the default flip to V1 and the new opt-in points.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.