Add Delegate Auth example for CAP-71 delegation#2519
Open
leighmcculloch wants to merge 9 commits into
Open
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the Soroban “complex account” documentation by adding a new section describing CAP-71 auth delegation APIs introduced in soroban-sdk v27+, including guidance on a modular-account delegation flow and a representative __check_auth example.
Changes:
- Adds a new “Auth Delegation (v27+)” section between Authorization policy and Tests.
- Documents
env.custom_account().get_delegated_signers()andenv.custom_account().delegate_auth(...)and their constraints. - Includes a Rust example illustrating a delegation loop inside
__check_auth.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| - **`get_delegated_signers() -> Vec<Address>`** — Returns the list of delegate addresses that the user attached to the auth entry when building the transaction. These are user-supplied and are not sanitized by the host; the contract must verify that each address is actually a registered delegate before acting on it. | ||
|
|
||
| - **`delegate_auth(&address)`** — Forwards the current `__check_auth` authorization context to the given address. The delegate runs its own auth check for the same context. Unlike `require_auth`, this does not count as a new contract invocation and does not require a separate auth entry in the transaction. Delegation can be nested recursively. |
Comment on lines
+385
to
+409
| fn __check_auth( | ||
| env: Env, | ||
| signature_payload: Hash<32>, | ||
| signature: BytesN<64>, | ||
| auth_contexts: Vec<Context>, | ||
| ) -> Result<(), ModularAccountError> { | ||
| // Perform the account's own verification if needed. | ||
| let public_key: BytesN<32> = env.storage().instance().get(&DataKey::PublicKey).unwrap(); | ||
| env.crypto() | ||
| .ed25519_verify(&public_key, &signature_payload.into(), &signature); | ||
|
|
||
| // Retrieve the delegate addresses the user attached to the auth entry. | ||
| let delegates = env.custom_account().get_delegated_signers(); | ||
| let signers: Vec<Address> = env.storage().instance().get(&DataKey::Signers).unwrap(); | ||
|
|
||
| for delegate in delegates.iter() { | ||
| // Reject any delegate that is not registered with this account. | ||
| if !signers.contains(&delegate) { | ||
| return Err(ModularAccountError::UnknownDelegate); | ||
| } | ||
| // Forward the current authorization context to the verified delegate. | ||
| env.custom_account().delegate_auth(&delegate); | ||
| } | ||
| Ok(()) | ||
| } |
Comment on lines
+370
to
+372
| Auth delegation, introduced in soroban-sdk v27 via CAP-71, allows a custom account contract to forward its `__check_auth` verification context to other registered addresses. This enables "modular" account contracts that do not perform all authentication themselves but instead delegate to one or more external signers (either G- or C-type addresses) that carry out the actual auth logic. | ||
|
|
||
| Two new methods are available on `env.custom_account()`, and both may only be called from within `__check_auth`. Calling them outside of `__check_auth` will panic. |
|
Preview is available here: |
…ation - Add docs/build/smart-contracts/example-contracts/modular-account.mdx as a standalone example covering auth delegation (soroban-sdk v27+). - Remove the auth delegation section that was added to complex-account.mdx and replace it with a link to the new Modular Account page. - Source contract code is taken from the SDK test in soroban-sdk/src/tests/delegate_auth.rs. Claude-Session: https://claude.ai/code/session_01GgpDVzaPCuCzUVUUyvdAke
leighmcculloch
changed the title
|
Preview is available here: |
…ample - Add the modular-account route to routes.txt (build job). - Remove the extra blank line in complex-account.mdx (mdx-format job). - Point the page at the new runnable modular_account example in soroban-examples, adding a "Run the Example" section and source-file titles on the code blocks. - Correct the DelegateAccount error type to soroban_sdk::Error and note it is defined as a test fixture (a single Wasm exports one __check_auth). - Explain the record_authorized_calls test-observability helper. Claude-Session: https://claude.ai/code/session_01EgjfKqQ1RMvtwQUSx3iDzh
|
Preview is available here: |
leighmcculloch
force-pushed
the
claude/awesome-gates-ildx8c
branch
from
e9be6e4 to
2c839a0
Compare
|
Preview is available here: |
…mples PR #407 - Rename modular-account.mdx → delegate-auth.mdx (title: "Delegate Auth") - Rewrite code section to use the canonical lib.rs from soroban-examples PR #407: #![no_std], mod test; split, inline comments matching the example repo - Add Run the Example section pointing to soroban-examples/modular_account - Add Build the Contract section with expected wasm output path - Update complex-account.mdx Further Reading link to new filename Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GgpDVzaPCuCzUVUUyvdAke
leighmcculloch
changed the title
|
Preview is available here: |
|
Preview is available here: |
|
Preview is available here: |
|
Preview is available here: |
leighmcculloch
changed the title
|
Preview is available here: |
leighmcculloch
changed the title
Update delegate-auth.mdx to match the canonical example in stellar/soroban-examples#407 rather than the SDK unit test: - type Signature = () — account carries no own signature, relies entirely on delegates - Per-signer persistent storage (Signer(Address) key) instead of a stored Vec<Address> - Constructor takes only signers, no public key - Two-pass __check_auth: validate all delegates first, then forward - Test section updated to match the simpler DelegateAccount fixture (Signature = (), always approves, stores ApprovedContexts) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GgpDVzaPCuCzUVUUyvdAke
|
Preview is available here: |
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.
What
Add a Delegate Auth example page documenting the CAP-71 auth delegation APIs introduced in soroban-sdk v27, mirroring the runnable
modular_accountcrate in stellar/soroban-examples#407. TheModularAccountcontract verifies no signature of its own and forwards its__check_authcontext to registered delegate signers viaget_delegated_signersanddelegate_auth; the page walks through the storage layout, constructor, the get/verify/forward delegation flow, and theset_auths+SorobanAddressCredentialsWithDelegatestesting pattern. The new page is linked from the Complex Account example and registered inroutes.txt.Why
soroban-sdk v27 ships auth delegation, and the modular account pattern is distinct enough from the multisig and spend-limit accounts in
complex-account.mdxto warrant its own example page rather than a subsection. It pairs with the companion stellar/soroban-examples#407, which provides the runnable crate the page points to.