{"id":31817659,"url":"https://github.com/crossmint/stellar-smart-account","last_synced_at":"2026-07-29T20:31:34.756Z","repository":{"id":304687515,"uuid":"1011764729","full_name":"Crossmint/stellar-smart-account","owner":"Crossmint","description":null,"archived":false,"fork":false,"pushed_at":"2025-10-03T14:31:31.000Z","size":18998,"stargazers_count":0,"open_issues_count":10,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-03T16:28:34.911Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Crossmint.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"security/scout-report.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-01T10:00:01.000Z","updated_at":"2025-10-03T14:31:33.000Z","dependencies_parsed_at":"2025-07-14T20:05:05.181Z","dependency_job_id":"5ca72190-6b94-49b4-b3eb-a000280a8bee","html_url":"https://github.com/Crossmint/stellar-smart-account","commit_stats":null,"previous_names":["crossmint/stellar-smart-account"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/Crossmint/stellar-smart-account","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Crossmint%2Fstellar-smart-account","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Crossmint%2Fstellar-smart-account/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Crossmint%2Fstellar-smart-account/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Crossmint%2Fstellar-smart-account/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Crossmint","download_url":"https://codeload.github.com/Crossmint/stellar-smart-account/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Crossmint%2Fstellar-smart-account/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279006851,"owners_count":26084204,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-11T10:23:02.798Z","updated_at":"2026-07-29T20:31:34.344Z","avatar_url":"https://github.com/Crossmint.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Stellar Smart Account\n\n[![Rust](https://img.shields.io/badge/rust-1.75+-orange.svg)](https://www.rust-lang.org)\n[![Soroban SDK](https://img.shields.io/badge/soroban--sdk-22.0.0-blue.svg)](https://soroban.stellar.org/)\n[![Test Status](https://github.com/Crossmint/stellar-smart-account/workflows/Test/badge.svg)](https://github.com/Crossmint/stellar-smart-account/actions)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n\nA comprehensive smart contract system for Stellar/Soroban that provides enterprise-grade account management with multi-signature support, role-based access control, and policy-based authorization. Designed for both human users and AI agents requiring sophisticated permission systems.\n\n## 🌟 Features\n\n- **🔐 Multi-Signature Account**: Advanced smart account with customizable authentication\n- **🏭 Contract Factory**: Permissionless deployment system with deterministic addresses\n- **🎯 Role-Based Permissions**: Admin and Standard signer roles with optional policies\n- **📋 Policy System**: External delegation, token spending limits with reset windows and recipient allowlists, and extensible policies\n- **🔌 Plugin System**: Extensible architecture with install/uninstall lifecycle and authorization hooks\n- **🌐 External Delegation**: Delegate authorization decisions to external policy contracts\n- **🤖 AI Agent Ready**: Built for both human users and automated systems\n- **⚡ Soroban Native**: Leverages Stellar's smart contract platform capabilities\n- **🔄 Upgradeable**: Built-in contract upgrade support with permission controls\n- **🔀 V1→V2 Migration**: Built-in migration system for upgrading from v1 contracts\n\n## 🏗️ Architecture\n\nThe system consists of multiple smart contracts and shared libraries:\n\n```\nstellar-smart-account/\n├── contracts/\n│   ├── smart-account/              # Multi-signature account contract with plugin support\n│   ├── smart-account-interfaces/   # Shared types and trait definitions\n│   ├── contract-factory/           # Permissionless contract deployment factory\n│   ├── examples/\n│   │   ├── plugin-policy-example/          # Example plugin+policy contract\n│   │   └── plugin-policy-example-reverts/  # Example plugin that reverts on uninstall\n│   ├── initializable/              # Contract initialization utilities\n│   ├── storage/                    # Storage management utilities\n│   ├── testing/                    # Shared test utilities\n│   ├── upgradeable/                # Contract upgrade utilities\n│   └── web-auth/                   # WebAuthn verification utilities\n```\n\n### Smart Account Contract\n\nThe core smart account provides:\n\n- **Multiple Signature Schemes**: Ed25519, Secp256r1, WebAuthn (passkeys), and Multisig (M-of-N threshold), extensible to others\n- **Flexible Authorization**: Role-based access with policy enforcement\n- **Multi-Signature Support**: Customizable authorization logic\n- **Plugin Architecture**: Extensible functionality through installable plugins\n- **External Delegation**: Delegate authorization to external policy contracts\n- **Soroban Integration**: Native account interface implementation\n\n### Contract Factory\n\nPermissionless deployment system featuring:\n\n- **Open Deployment**: Anyone can deploy smart account contracts\n- **Deterministic Addresses**: Predictable contract addresses using salt values\n- **Idempotent Deploys**: Safe re-deployment attempts return existing addresses\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Rust 1.75+ with `wasm32-unknown-unknown` target\n- [Stellar CLI](https://soroban.stellar.org/docs/getting-started/setup)\n\n### Installation\n\n1. **Clone the repository**:\n```bash\ngit clone https://github.com/Crossmint/stellar-smart-account.git\ncd stellar-smart-account\n```\n\n2. **Build the contracts**:\n```bash\nstellar contract build\n```\n\n3. **Run tests**:\n```bash\ncargo test\n```\n\n## 🔑 Authentication \u0026 Permissions\n\n### Signer Roles\n\n| Role | Capabilities | Use Cases |\n|------|-------------|-----------|\n| **Admin** | Full access, can upgrade contracts | System administrators, emergency access |\n| **Standard** | Normal operations, cannot modify signers, optional policy restrictions | Regular users, application accounts, AI agents with policies |\n\n### Policy Types\n\n- **External Delegation**: Delegate authorization decisions to external policy contracts\n- **Token Transfer Policy**: Restrict signers to specific token transfers with cumulative spending limits, reset windows, recipient allowlists, and per-policy expiration\n- **Extensible**: Add custom policies by implementing the `AuthorizationCheck` and `PolicyCallback` traits\n\n### Signer Expiration\n\nStandard signers can have an expiration timestamp. Once the ledger timestamp exceeds the expiration, the signer is rejected. A value of `0` means no expiration.\n\n### Example: Expiring AI Agent Signer\n\n```rust\n// Create an AI agent with time-limited access using signer expiration\nlet ai_signer = Signer::Ed25519(\n    Ed25519Signer::new(ai_agent_pubkey),\n    SignerRole::Standard(None, end_timestamp) // expires at end_timestamp, 0 = no expiration\n);\n```\n\n### Example: External Policy Delegation\n\n```rust\n// Delegate authorization to an external policy contract\nlet external_policy = ExternalPolicy {\n    policy_address: deny_list_contract_address,\n};\n\nlet restricted_signer = Signer::Ed25519(\n    Ed25519Signer::new(signer_pubkey),\n    SignerRole::Standard(\n        Some(vec![SignerPolicy::ExternalPolicy(external_policy)]),\n        0, // 0 = no expiration\n    )\n);\n```\n\n### Example: Plugin Installation\n\n```rust\n// Initialize smart account with plugins\nSmartAccount::__constructor(\n    env,\n    vec![admin_signer],\n    vec![analytics_plugin_address, logging_plugin_address]\n);\n\n// Install additional plugins after deployment\nSmartAccount::install_plugin(\u0026env, new_plugin_address)?;\n```\n\n## 🧪 Testing\n\nRun the full test suite:\n\n```bash\n# Run all tests\ncargo test\n\n# Run with coverage\ncargo install cargo-tarpaulin\ncargo tarpaulin --out Html\n```\n\n## 💾 Soroban Storage Strategy and Costs\n\nFor optimal performance and cost on Soroban, this project uses storage types deliberately:\n- Persistent storage: durable, TTL-based entries with rent; best for long-lived, potentially larger datasets\n- Instance storage: bundled with the contract entry, automatically loaded each call; best for small data needed on most calls\n- Temporary storage: short TTL and cheaper rent; not used here for critical state\n\nApplied to the Smart Account:\n- Signers (SignerKey -\u003e Signer): Persistent\n- Admin count (ADMIN_COUNT_KEY): Persistent\n- Plugins registry (PLUGINS_KEY): Instance (invoked on every __check_auth)\n- Migration flag (MIGRATING): Instance\n\nWhy this mapping:\n- Plugins are accessed on every call in __check_auth, so keeping the plugin registry in Instance storage avoids separate persistent reads on each invocation.\n- Signers and admin count are long-lived and can grow; storing them in Persistent avoids growing the contract instance entry and respects durability expectations.\n\nNotes:\n- Instance storage is limited by the ledger entry size limit (approximately 128 KB for the contract entry), so only small, frequently accessed data should be kept there.\n- Persistent entries accrue rent over time and can be restored after archival if TTL expires by paying a fee.\n\nPotential future optimizations (not implemented here):\n- Skip plugin callbacks when auth contexts are clearly unrelated\n- Maintain a fast “has_plugins” indicator to early-exit\n- Track a subset of “auth-hook” plugins to invoke only those on __check_auth\n\nThe project maintains 80%+ test coverage with comprehensive integration tests.\n\n## 🔧 Development\n\n### Adding New Signer Types\n\n1. Define the signer struct in `contracts/smart-account-interfaces/src/auth/types.rs`\n2. Implement the `SignatureVerifier` trait in `contracts/smart-account/src/auth/signers/`\n3. Add variants to `SignerKey` and `Signer` enums in the interfaces crate, and `SignerProof` in `contracts/smart-account/src/auth/proof.rs`\n4. Add a `From\u003cNewSigner\u003e for SignerKey` implementation\n5. Update match statements in `contracts/smart-account/src/auth/signer.rs` and `contracts/smart-account/src/auth/core/authorizer.rs`\n\n### Adding New Policies\n\n1. Create the policy struct in `contracts/smart-account-interfaces/src/auth/types.rs`\n2. Implement `AuthorizationCheck` and `PolicyCallback` traits in `contracts/smart-account/src/auth/policy/`\n   - `AuthorizationCheck::is_authorized(\u0026self, env, signer_key, contexts) -\u003e bool`\n   - `PolicyCallback::on_add(\u0026self, env, signer_key) -\u003e Result\u003c(), SmartAccountError\u003e`\n   - `PolicyCallback::on_revoke(\u0026self, env, signer_key) -\u003e Result\u003c(), SmartAccountError\u003e`\n3. Add a variant to the `SignerPolicy` enum in the interfaces crate\n4. Update match arms in `contracts/smart-account/src/auth/permissions.rs`\n\nSee the [Smart Account Architecture Documentation](contracts/smart-account/README.md) for detailed extension guides.\n\n## 🌐 Network Support\n\nThe contracts are designed for deployment on:\n\n- **Stellar Testnet**: For development and testing\n- **Stellar Futurenet**: For experimental features\n- **Stellar Mainnet**: For production deployments\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Make your changes and add tests\n4. Ensure tests pass: `cargo test`\n5. Commit your changes: `git commit -m 'Add amazing feature'`\n6. Push to the branch: `git push origin feature/amazing-feature`\n7. Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"https://www.crossmint.com/assets/crossmint/logo.png\" alt=\"Crossmint Logo\" width=\"120\" /\u003e\n\n### Built with ❤️ by **Crossmint**\n\n*The enterprise infrastructure powering the next generation of cross-chain applications*\n\n**[🚀 Explore Crossmint Wallets](https://docs.crossmint.com/wallets/overview)** | **[🌐 Visit Crossmint.com](https://crossmint.com/)**\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrossmint%2Fstellar-smart-account","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcrossmint%2Fstellar-smart-account","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrossmint%2Fstellar-smart-account/lists"}