Add smart account support for OpenZeppelin contracts#208
Merged
Conversation
Adds the protocol-agnostic smart-account package: signer types (delegated and external WebAuthn / Ed25519), the sealed exception hierarchy, and public-key size constants. Adds the OpenZeppelin contract identification constants used by future OpenZeppelin-specific layers. Also adds a public pollTransaction helper on SorobanServer for polling RPC transaction results.
Adds the platform-agnostic WebAuthn provider abstraction along with the registration and authentication result types and the AllowCredential type for restricting credential discovery during authentication.
Adds the OpenZeppelin Smart Account integration in smartaccount/oz/ (signer types, signature wrappers, auth payload codec, auth-digest builder, and signer and policy builders) and the supporting WebAuthn cryptographic primitives in smartaccount/core/ (DER signature parser with low-S normalization, COSE-to-SEC1 public key extractor, secp256r1 on-curve validation, and credential-derived contract address derivation). Adds Data extensions for base64url encoding and constant-time byte comparison, an SCValXDR.i128 factory for stroop amounts, a String overload for Operation.toXDRAmount, and ledger and stroop constants on StellarProtocolConstants.
Adds six golden-vector tests asserting byte-level output of buildAuthDigest, the OZ AuthPayload codec, and OZWebAuthnSignature ScVal serialization for a canonical fixture set. The hex outputs are pinned to specific values across the four buildAuthDigest fixtures (empty, single, unsorted, and long signaturePayload boundary) plus one AuthPayload and one WebAuthnSignature wire-shape fixture, providing a byte-identical reference for cross-SDK verification.
Adds OZSmartAccountConfig with a chainable builder, input validation on required fields, and a deterministic default deployer derivation. Adds a StorageAdapter protocol with an actor-isolated InMemoryStorageAdapter, the credential and session data structures used by every adapter implementation, and the ExternalWalletAdapter protocol for delegating signing to external wallet bridges. Adds internal JSON serialization helpers that persistent adapters will reuse to round-trip credentials and sessions through encoded form.
Adds SmartAccountEvent (sealed event hierarchy), SmartAccountEventEmitter (typed and untyped subscribe / unsubscribe, isolated error handler, snapshot-then-dispatch under a serial lock), internal validation helpers for contract addresses, Stellar accounts and localhost URLs, and the OZ context-rule builders including the sealed ContextRuleType and ParsedContextRule data classes that the context-rule manager will consume.
Adds OZIndexerClient (credential / address / contract / stats / health lookups) and OZRelayerClient (sponsored transaction submission) on URLSession, with HTTPS-only allowlist, no-redirect delegate, and response body-size caps. Centralises the default-indexer-URL lookup behind OZIndexerClient.getDefaultUrl.
Adds OZTransactionOperations (transfer, contractCall, executeAndSubmit, submit, fundWallet) and OZWalletOperations (createWallet, connectWallet, authenticatePasskey, deployPendingCredential), with simulate / sign / re-simulate / submit pipeline, deterministic deployer keypair flow, HTTPS-only allowlist preserved, and config bounds on signature expiration and timeout. Backed by a forward-reference protocol the smart-account kit will conform to.
Adds OZSignerManager, OZPolicyManager, OZContextRuleManager, OZCredentialManager, OZMultiSignerManager, and OZExternalSignerManager covering signer/policy/context-rule/credential CRUD over the smart-account contract surface, multi-signer auth-entry pipeline, and Ed25519/external-wallet signer routing. Backed by additive extensions to the Phase 6 forward-reference protocols and a shared submission router.
Splits OZContextRuleManager parsing into a dedicated extension, tightens External-signer verifier parsing to contract-only, gates keypair signing on private-seed availability, renames the connected- wallet storage key for namespace clarity, and adds cancellation, read-side, amountToStroops, and cloneAuthEntry tests. Switches the Phase 7 test placeholder URL to the immediate-fail loopback.
Adds OZSmartAccountKit, the top-level class that composes the OZ smart-account managers and exposes them along with the event emitter, indexer client, and relayer client. Gives SorobanServer an owned URLSession with an idempotent close() so the kit can release the shared RPC transport.
Adds AppleWebAuthnProvider (ASAuthorization-based, iOS 16+/macOS 13+), KeychainStorageAdapter, and UserDefaultsStorageAdapter conforming to the existing storage protocol. Introduces SecItemShim, a small indirection that makes Keychain failure modes injectable from tests.
Replaces the placeholder XCTSkip tests with real assertions that exercise OZSmartAccountKit's session lifecycle through the public factory, covering disconnect side effects, session/credential storage orthogonality, and the requireConnected throw paths.
Adds optional maxScanId parameters to OZContextRuleManager's getAllContextRules and listContextRules so callers can override the configured scan cap on a per-call basis without reconfiguring the kit. Adds a new SmartAccountEventCredentialSyncFailed event emitted when OZCredentialManager.sync cannot reach the RPC, giving consumers a signal to react to sync failures alongside the existing boolean return.
…nto Data extension
… the strict CBOR parser
…ant wallet-connection storage
…rs and spending limits
…ager and keychain API
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
2 participants
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.
Description
Add passkey-based smart account support to the iOS/macOS Stellar SDK, targeting OpenZeppelin stellar-contracts v0.7.1.
SDK
Two-layer architecture under
stellarsdk/stellarsdk/smartaccount/.Core layer (contract-agnostic):
WebAuthnProviderprotocol andAppleWebAuthnProvider, an AuthenticationServices-backed implementation providing passkey registration and assertion for iOS 16+ and macOS 13+SmartAccountException) with families for configuration, wallet, credential, WebAuthn, transaction, signer, validation, storage, session, and indexer errorsOZ layer (OpenZeppelin-specific):
OZSmartAccountKit: wallet creation (passkey registration + contract deployment), wallet connection (session restore + fresh authentication), token transfers, and arbitrary Soroban invocationsSDK core additions (outside the smartaccount package, additive only):
Dataextensions: base64url encode/decode and constant-time comparisonSorobanServer: transaction polling and resource cleanupStellarProtocolConstants: stroop and ledger conversion constantsDocumentation
Under
docs/smart-accounts/:An agent skill under
skills/stellar-ios-mac-sdk/with curated references and a generated API signature index.Tests
Unit tests covering COSE public key extraction, signer and signature encoding, contract address derivation, DER signature normalization, auth payload construction, policy SCVal encoding, storage adapters, credential management, the event system, error mapping, and exception factories.