feat: Propose project structure with access control core module

.github/workflows/CI.yaml

@@ -0,0 +1,45 @@
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  fmt:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install Aptos CLI
+        run: |
+          set -euo pipefail
+          curl -fsSL "https://aptos.dev/scripts/install_cli.py" | python3
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - name: Install Aptos Move fmt
+        run: |
+          aptos update movefmt
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+          echo "FORMATTER_EXE=$HOME/.local/bin/movefmt" >> $GITHUB_ENV
+
+      - name: Format Check
+        run: |
+          aptos move fmt
+          git diff --exit-code
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install Aptos CLI
+        run: |
+          set -euo pipefail
+          curl -fsSL "https://aptos.dev/scripts/install_cli.py" | python3
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - name: Run Aptos Move Tests
+        run: aptos move test --dev
+
+      - name: Run Aptos Move Linter
+        run: aptos move lint --dev

.gitignore

@@ -0,0 +1,3 @@
+.aptos/
+build/
+.coverage_map*

Move.toml

@@ -0,0 +1,17 @@
+[package]
+name = "aptos-movekit"
+version = "1.0.0"
+authors = []
+
+[addresses]
+movekit = "_"
+
+[dev-addresses]
+movekit = "0xCAFE"
+
+[dependencies.AptosFramework]
+git = "https://github.com/aptos-labs/aptos-framework.git"
+rev = "mainnet"
+subdir = "aptos-framework"
+
+[dev-dependencies]

sources/access_control/ARCHITECTURE.md

@@ -0,0 +1,194 @@
+# Access Control Architecture
+
+## Overview
+
+The Aptos MoveKit Access Control system provides secure, type-safe role-based access control (RBAC) for smart contracts. It consists of two core modules that work together to manage admin privileges and role assignments.
+
+## Core Components
+
+### Modules
+
+1. **`access_control_admin_registry`** - Manages admin transfers using a secure two-step process
+2. **`access_control_core`** - Coordinates role management and delegates admin operations
+
+### Data Structures
+
+```mermaid
+classDiagram
+    class AdminRegistry {
+        +address current_admin
+        +Option pending_admin
+    }
+
+    class RoleRegistry {
+        +Table roles
+    }
+
+    class Admin {
+        <<phantom type>>
+    }
+
+    AdminRegistry -- RoleRegistry : synchronized
+    RoleRegistry -- Admin : manages
+```
+
+## System Architecture
+
+```mermaid
+graph TB
+    subgraph "Access Control Core"
+        Core[access_control_core]
+        Registry[access_control_admin_registry]
+
+        Core --> Registry
+    end
+
+    subgraph "Storage"
+        AdminReg[(AdminRegistry)]
+        RoleReg[(RoleRegistry)]
+    end
+
+    subgraph "External"
+        Client[Client Contracts]
+        Admin[Admin Users]
+    end
+
+    Core --> RoleReg
+    Registry --> AdminReg
+    Client --> Core
+    Admin --> Core
+
+    Core -.->|Events| EventSystem[Event System]
+```
+
+## Admin Transfer Flow
+
+The system uses a secure two-step transfer process to prevent accidental admin loss:
+
+```mermaid
+sequenceDiagram
+    participant CurrentAdmin
+    participant AdminRegistry
+    participant RoleRegistry
+    participant NewAdmin
+
+    CurrentAdmin->>AdminRegistry: transfer_admin(new_admin)
+    AdminRegistry->>AdminRegistry: Set pending_admin
+    AdminRegistry-->>CurrentAdmin: AdminTransferProposed event
+
+    Note over AdminRegistry: Pending state
+
+    NewAdmin->>AdminRegistry: accept_pending_admin()
+    AdminRegistry->>AdminRegistry: Update current_admin
+    AdminRegistry->>RoleRegistry: Synchronize Admin role
+    RoleRegistry->>RoleRegistry: Grant Admin to new_admin
+    RoleRegistry->>RoleRegistry: Revoke Admin from old_admin
+    AdminRegistry-->>NewAdmin: AdminTransferCompleted event
+    RoleRegistry-->>NewAdmin: AdminRoleTransferred event
+```
+
+## Role Management Flow
+
+```mermaid
+sequenceDiagram
+    participant Admin
+    participant Core
+    participant Registry as AdminRegistry
+    participant RoleRegistry
+    participant Target
+
+    Admin->>Core: grant_role<T>(target)
+    Core->>Core: assert_not_admin_role<T>()
+    Core->>Registry: require_admin(admin)
+    Core->>RoleRegistry: Check !has_role<T>(target)
+    Core->>RoleRegistry: grant_role_internal<T>(target)
+    Core-->>Admin: RoleGranted<T> event
+
+    Note over Core: Similar flow for revoke_role<T>
+```
+
+## Security Model
+
+### Protection Mechanisms
+
+1. **Admin Role Protection** - Admin role cannot be manually granted/revoked
+2. **Two-Step Transfer** - Prevents accidental admin loss
+3. **Authorization Checks** - All operations validate admin permissions
+4. **Type Safety** - Phantom types ensure compile-time role verification
+5. **State Validation** - Prevents duplicate assignments and missing roles
+
+### Access Control Matrix
+
+```mermaid
+graph LR
+    subgraph "Permissions"
+        Admin[Admin Role]
+        CustomRole[Custom Roles]
+    end
+
+    subgraph "Operations"
+        Transfer[Admin Transfer]
+        Grant[Grant Roles]
+        Revoke[Revoke Roles]
+        Query[Query Functions]
+    end
+
+    Admin --> Transfer
+    Admin --> Grant
+    Admin --> Revoke
+    Admin --> Query
+    CustomRole --> Query
+```
+
+## Event System
+
+All operations emit events for audit trails:
+
+- `AdminTransferProposed` - Admin transfer initiated
+- `AdminTransferCompleted` - Admin transfer completed
+- `AdminTransferCanceled` - Admin transfer canceled
+- `AdminRoleTransferred` - Admin role synchronized in RoleRegistry
+- `RoleGranted<T>` - Custom role granted
+- `RoleRevoked<T>` - Custom role revoked
+
+## Usage Patterns
+
+### Role Definition
+```move
+struct Treasurer has copy, drop {}
+struct Manager has copy, drop {}
+```
+
+### Permission Checks
+```move
+public entry fun sensitive_operation(account: &signer) {
+    access_control_core::require_role<Treasurer>(account);
+    // operation logic
+}
+```
+
+### Admin Operations
+```move
+// Grant role (admin only)
+access_control_core::grant_role<Treasurer>(admin, target_address);
+
+// Transfer admin (two-step)
+access_control_core::transfer_admin(admin, new_admin_address);
+access_control_core::accept_pending_admin(new_admin);
+```
+
+## Design Principles
+
+1. **Separation of Concerns** - Admin management separate from role management
+2. **Fail-Safe Defaults** - Graceful handling of uninitialized states
+3. **Atomic Operations** - State changes are consistent across registries  
+4. **Storage Efficiency** - Cleanup of empty role maps
+5. **Auditability** - Comprehensive event emission
+
+## Integration Points
+
+External contracts integrate through:
+- `require_role<T>()` for permission checks
+- `has_role<T>()` for conditional logic
+- View functions for role queries
+- Event listening for audit systems

sources/access_control/README.md

@@ -0,0 +1,78 @@
+# Access Control System
+
+Role-based access control (RBAC) for Aptos Move contracts using phantom types.
+
+## Architecture
+
+Two modules:
+- `access_control_admin_registry` - Manages admin transfers with two-step verification
+- `access_control_core` - Handles role assignments and authorization
+
+## Usage
+
+### Define Roles
+```move
+struct Treasurer has copy, drop {}
+struct Manager has copy, drop {}
+```
+
+### Protect Functions
+```move
+public entry fun withdraw(account: &signer, amount: u64) {
+    access_control_core::require_role<Treasurer>(account);
+    // protected logic
+}
+```
+
+### Manage Roles (Admin Only)
+```move
+// Grant role
+access_control_core::grant_role<Treasurer>(admin, user_address);
+
+// Revoke role
+access_control_core::revoke_role<Treasurer>(admin, user_address);
+
+// Check role
+let has_role = access_control_core::has_role<Treasurer>(user_address);
+```
+
+### Transfer Admin
+```move
+// Step 1: Current admin proposes transfer
+access_control_core::transfer_admin(admin, new_admin_address);
+
+// Step 2: New admin accepts
+access_control_core::accept_pending_admin(new_admin);
+```
+
+## Key Functions
+
+| Function | Description |
+|----------|-------------|
+| `require_role<T>(account)` | Assert account has role T |
+| `has_role<T>(address)` | Check if address has role T |
+| `grant_role<T>(admin, target)` | Grant role T to target |
+| `revoke_role<T>(admin, target)` | Revoke role T from target |
+| `get_roles(address)` | Get all roles for address |
+| `transfer_admin(admin, new_admin)` | Propose admin transfer |
+| `accept_pending_admin(new_admin)` | Accept admin transfer |
+
+## Events
+
+- `RoleGranted<T>` - Role granted
+- `RoleRevoked<T>` - Role revoked  
+- `AdminTransferProposed` - Admin transfer initiated
+- `AdminTransferCompleted` - Admin transfer completed
+
+## Error Codes
+
+- `E_NOT_ADMIN` (0) - Caller not admin
+- `E_ALREADY_HAS_ROLE` (1) - Role already assigned
+- `E_NO_SUCH_ROLE` (2) - Role not found
+- `E_ADMIN_ROLE_PROTECTED` (4) - Admin role cannot be manually managed
+
+## Security Notes
+
+- Admin role is protected - only transferable via two-step process
+- Built-in Admin role type cannot be granted/revoked manually
+- All operations emit events for audit trails