P27 guide - #1440
Merged
Merged
Conversation
There was a problem hiding this comment.
Pull request overview
Adds documentation to help SDK users migrate Soroban authorization signing logic for Protocol 27 (CAP-71), especially for callers that hand-build SorobanAuthorizationEntry values or compute signature payloads themselves.
Changes:
- Adds a new guide explaining the P27 address-bound authorization preimage,
ADDRESS_V2, and delegated signing. - Links the new guide from the LLM-oriented docs index (
docs/llms.txt). - Includes the new guide content in the full LLM bundle (
docs/llms-full.txt).
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| docs/llms.txt | Adds the new P27 guide to the Guides index. |
| docs/llms-full.txt | Inlines the new P27 guide into the full documentation bundle. |
| docs/guides/01-protocol-27-soroban-auth.md | New migration guide covering P27 auth payload changes and recommended SDK helpers. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ## Guides | ||
|
|
||
| - [Versioning & Compatibility](guides/00-versioning) | ||
| - ["Protocol 27: Soroban authorization migration"](guides/01-protocol-27-soroban-auth) |
| `SOROBAN_CREDENTIALS_ADDRESS` type and its non-address-bound payload still exist | ||
| for backwards compatibility, but new entries should use `ADDRESS_V2`. | ||
|
|
||
| ## The three credential types |
Contributor
There was a problem hiding this comment.
Agree, the title and the table contradict each other.
| `SOROBAN_CREDENTIALS_ADDRESS` type and its non-address-bound payload still exist | ||
| for backwards compatibility, but new entries should use `ADDRESS_V2`. | ||
|
|
||
| ## The three credential types |
quietbits
approved these changes
Jun 5, 2026
| `SOROBAN_CREDENTIALS_ADDRESS` type and its non-address-bound payload still exist | ||
| for backwards compatibility, but new entries should use `ADDRESS_V2`. | ||
|
|
||
| ## The three credential types |
Contributor
There was a problem hiding this comment.
Agree, the title and the table contradict each other.
|
|
||
| ## New: delegated signing (`ADDRESS_WITH_DELEGATES`) | ||
|
|
||
| CAP-71 also adds delegated authorization: an account can authorize an invocation |
Contributor
There was a problem hiding this comment.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 8ab88d2154
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| function signAuthEntry(entry, keypair, validUntil, networkPassphrase) { | ||
| // P27 entries carry the same SorobanAddressCredentials struct, but on the | ||
| // ADDRESS_V2 arm — read it with `.addressV2()`, not `.address()` | ||
| const addressCreds = entry.credentials().addressV2(); |
There was a problem hiding this comment.
For callers following this section with an SOROBAN_CREDENTIALS_ADDRESS_WITH_DELEGATES entry, this accessor throws because the delegates variant stores the same SorobanAddressCredentials under credentials().addressWithDelegates().addressCredentials(), not the addressV2 arm (the later helper in this guide handles that distinction). As written, the example is advertised for both ADDRESS_V2 and ADDRESS_WITH_DELEGATES, but delegated hand-rolled signers would fail before building the preimage or writing any signature.
Useful? React with 👍 / 👎.
Merged
Ryang-21
added a commit
that referenced
this pull request
Jun 5, 2026
* [Modernization] Make fetch default (#1394) * Replace __USE_AXIOS__ dynamic require with static fetch default * Add babel and webpack aliasing to emit axios variant from shared source * Flip package.json exports: fetch default, /axios opt-in, drop /no-axios * Update eventsource and remove no-eventsource build (#1395) * update eventsource to v4.1.0 and remove conditional import of eventsource * remove the dom-monkeypatch as its now included in the tsconfig lib field * build and export cjs and esm build varients, remove export of umd bundles * Base Migration (#1399) * move stellar-base src under src/base * migrate from classic yarn to pnpm (#1400) * remove randomBytes for universal crypto.getRandomValues * replace sha.js with noble/hashes and update to version 2.2.0 * update BigNumber to v11.0.0 * replace noble/curves with noble/ed25519 for reduced bundle size * replace toml with smol-toml * replace URI for native URL (#1402) * refactor: replace URI usage for native URL + URLSearchParam objects * allow expandUriTemplate to handle relative templated links * Tooling modernization: Node 22, husky v9, pnpm minimumReleaseAge, drop nyc (#1408) * Update husky config + remove nyc * Root .nvmrc + bump Node to v22 * pnpm minimumReleaseAge config * Use pnpm workspace (#1417) * New docs (#1413) * TypeDoc setup * P27 updates (#1429) * Update XDR base URLs and improve Makefile for TypeScript definitions * pull and regenerate xdr definitions for p27 * handle signing the new SorobanCredential varients * add CAP-71 delegate-credential signing helpers - buildAuthorizationEntryPreimage: expose the signature payload (authorizeEntry now builds its preimage through it) - buildWithDelegatesEntry: wrap ADDRESS/ADDRESS_V2 into ADDRESS_WITH_DELEGATES, sorting + de-duping delegates; top-level signature defaults to Void - authorizeEntry: optional forAddress to fill a specific node (top-level or a delegate) instead of always the top-level - export the new helpers + DelegateSignature/BuildWithDelegatesParams from base * Update readme + pre-push check for docs (#1430) * Pre-push hook + updated docs * Update pre-push hook * Add @stellar/stellar-base migration guide to the installation docs * Map xdr.HashIdPreimage in typedoc to fix docs:reference build --------- Co-authored-by: oceans404 <[email protected]> * Tx builder type regression (#1438) * Implement TransactionSource interface for Account and MuxedAccount classes; update TransactionBuilder to use TransactionSource * TSDoc: Replace @internal with @ignore tag (#1436) * TSDoc: Replace @internal with @ignore tag * Add friendbot call builder items * Dependency updates (#1433) * Minor: axios + bignumber.js * Patch: vitest + @vitest * Minor astro + patch @astro * Minor: esbuild to v0.27.7 (not latest v0.28.0) * Some patch + minor * Major: @rollup/plugin-commonjs * Major: cross-env + dotenv * Major: jsdom * Updated pnpm-lock * Auth flag namespace (#1441) * add back AuthFlag namespace * fix: update build types script for axios to ensure generated types are copied correctly * P27 guide (#1440) * add p27 guide * docs: add task-oriented guides (connect-and-fund, send-a-payment) + internal-link tooling (#1434) * docs: add internal-link tooling (base-prefix rewriting + dead-link validation) * docs: add connect-and-fund and send-a-payment guides * docs: add issue-an-asset guide * docs: refine issue-an-asset guide (token framing, typed helper, review fixes) * docs: add query-and-stream guide * docs: add handle-errors guide * docs: link guides 02-04 to the handle-errors guide Add error-handling pointers now that guide 05 exists (sibling-link upgrade): a primary pointer in guide 02's submit section and lighter pointers in 03/04. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> * docs: add invoke-a-contract guide (06) Teaches invoking a deployed Soroban contract from JS with contract.Client and AssembledTransaction: connect over RPC, preview a call by simulation, then sign and send a state change. Uses the increment contract; deployment is linked out to the Stellar CLI tutorial. Regenerate llms bundles. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> * docs: add contract-auth guide (07) Covers signing Soroban contract authorization for an account other than the transaction source, framed for AddressV2 (CAP-0071-02) readiness: the same code is correct on the legacy ADDRESS credential today and on AddressV2 after the Protocol 28 flip. Distinguishes envelope signing from authorization-entry signing, and gives a before/after migration for hand-rolled signers (buildAuthorizationEntryPreimage / authorizeEntry). Also upgrades the Invoke a Contract guide's closing link to point at this guide, replaces numbered guide references with named links, and regenerates the llms bundles. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> * docs: fold versioning into the home page, drop it as a guide Versioning and compatibility is reference material, not a task how-to, so it moves out of the guides nav into a 'Versioning and compatibility' section on the home page (README -> index). Repoints the agents.md reference to the new home-page anchor and regenerates index.md + llms bundles. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> * docs: add migration guide (00) A versioned breaking-changes guide for upgrading to the v16 modernization release (base fold-in, native fetch, ESM, Node 22) and Protocol 27 / 28 Soroban auth (AddressV2). Modeled on viem's migration guide: one section per version, one entry per change, with before/after diffs. Sorts first in the guides nav and opens with a pointer to the home-page versioning section. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> * docs: link API references in migration guide (00) Link the first mention of each documented symbol (Keypair, the auth helpers, contract.Client/basicNodeSigner/signAuthEntries, rpc.Server/Horizon.Server, getLatestLedger, BalanceResponse, SigningCallback) to its reference page, base-agnostic, matching guide 07. Anchors verified against the rendered reference pages; internal link check passes. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> --------- Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]> Co-authored-by: Ryan Yang <[email protected]> Co-authored-by: Iveta <[email protected]> * update package version to 16.0.0-rc.1 * fix: improve token formatting logic --------- Co-authored-by: Iveta <[email protected]> Co-authored-by: oceans404 <[email protected]> Co-authored-by: Steph <[email protected]> Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]> Co-authored-by: Iveta <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a guide for p27 auth changes