{"id":31619256,"url":"https://github.com/multiversx/mx-bridge-sc-sui","last_synced_at":"2026-02-14T07:31:16.973Z","repository":{"id":298672064,"uuid":"995939103","full_name":"multiversx/mx-bridge-sc-sui","owner":"multiversx","description":null,"archived":false,"fork":false,"pushed_at":"2026-02-10T14:30:19.000Z","size":817,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-10T16:07:37.228Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Move","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/multiversx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":"audits/xMoney Audit Report-2025-9-30.pdf","citation":null,"codeowners":null,"security":null,"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-06-04T08:17:30.000Z","updated_at":"2026-02-10T14:30:25.000Z","dependencies_parsed_at":"2025-06-12T09:20:33.849Z","dependency_job_id":"eeea06f1-4844-4257-b16f-b0e71e8e3267","html_url":"https://github.com/multiversx/mx-bridge-sc-sui","commit_stats":null,"previous_names":["multiversx/mx-bridge-sc-sui"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/multiversx/mx-bridge-sc-sui","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/multiversx%2Fmx-bridge-sc-sui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/multiversx%2Fmx-bridge-sc-sui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/multiversx%2Fmx-bridge-sc-sui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/multiversx%2Fmx-bridge-sc-sui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/multiversx","download_url":"https://codeload.github.com/multiversx/mx-bridge-sc-sui/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/multiversx%2Fmx-bridge-sc-sui/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29439487,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-14T07:24:13.446Z","status":"ssl_error","status_checked_at":"2026-02-14T07:23:58.969Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-06T14:02:17.872Z","updated_at":"2026-02-14T07:31:16.956Z","avatar_url":"https://github.com/multiversx.png","language":"Move","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SUI BRIDGE SMART CONTRACTS\n\nA comprehensive bridge solution enabling secure token transfers between MultiversX and Sui blockchains, built with Move smart contracts on Sui.\n\n## Abstract\n\nThis project implements a secure cross-chain bridge that facilitates token transfers from MultiversX to Sui. The bridge operates through a batch-based system where relayers process transactions in groups, ensuring efficiency and security through quorum validation and cryptographic verification.\n\n## Bridge Flows\n\n### 1. MultiversX → Sui Transfer Flow\n\nWhen a bridge is initiated from MultiversX to Sui, the following process occurs:\n\n1. **Batch Processing**: Relayers process incoming transactions and group them into batches\n2. **Execute Transfer Calls**: The `execute_transfer` endpoint from the bridge module is called for each batch\n   - Each call processes a portion of one batch, sorted by token type\n   - Multiple `execute_transfer` calls may be required for complete batch execution (one per token type)\n3. **Batch Completion**: The last transaction from the Programmable Transaction Block (PTB) marks the end of the batch\n4. **Batch Execution Marking**: The batch is marked as executed in the bridge module\n5. **Safe Transfer**: The bridge module calls the `transfer` function from the safe module\n6. **Final Transfer**: Tokens are transferred from safe storage to the recipient address with the amount specified in the batch\n\n#### Security Features\n\n- **Quorum Validation**: At the `execute_transfer` level, the system validates quorum by:\n  - Collecting relayer signatures\n  - Constructing message hash\n  - Verifying signatures using Ed25519's `verify` function\n- **Batch-based Processing**: Ensures atomic execution of related transfers\n- **Multi-token Support**: Handles different token types within the same batch efficiently\n\n### 2. Sui → MultiversX Transfer Flow\n\nWhen a user initiates a bridge transfer from Sui to MultiversX, the following process occurs:\n\n1. **User Deposit**: The user calls the `deposit` endpoint from the safe module\n2. **Batch Processing**: The system automatically creates or adds to existing batches based on timing and capacity\n3. **Relayer Processing**: Relayers monitor batches and process them on the MultiversX side when complete\n4. **Batch Status Updates**: Relayers mark each batch status after processing\n\n#### Deposit Endpoint Logic\n\nThe `deposit` function in the safe module performs the following operations:\n\n- **Validation Checks**:\n  - Ensures the bridge is not paused\n  - Validates recipient address format (32 bytes)\n  - Verifies token is whitelisted\n  - Checks amount is within configured limits (min/max)\n  - Prevents zero amount deposits\n\n- **Batch Management**:\n  - Creates new batch if needed based on timing\n  - Adds deposit to current active batch\n  - Increments batch deposit counters\n  - Updates batch timestamps\n\n- **Token Storage**:\n  - Stores deposited coins in the contract's coin storage\n  - Joins with existing coins of the same type\n  - Updates total balance for the token configuration\n\n- **Event Emission**:\n  - Emits deposit event with batch nonce, deposit nonce, sender, recipient, amount, and token type\n  - Enables off-chain monitoring and indexing\n\n## Project Structure\n\n```\nmx-bridge-sc-sui/\n├── sources/                          # Move smart contract source files\n│   ├── bridge_module.move            # Main bridge logic and execute_transfer\n│   ├── events.move                   # Event definitions for bridge operations\n│   ├── pausable.move                 # Pausable functionality for emergency stops\n│   ├── roles.move                    # Role-based access control\n│   ├── safe.move                     # Safe storage and transfer operations\n│   ├── shared_structs.move           # Shared data structures\n│   └── utils.move                    # Utility functions and helpers\n```\n\n## Key Components\n\n### Bridge Module (`bridge_module.move`)\n\nThe bridge module is the core orchestrator that handles cross-chain transfer execution and relayer management.\n\n#### **Capabilities**\n\n- **Cross-chain Transfer Execution**: Processes transfers from MultiversX to Sui\n- **Relayer Management**: Manages the set of authorized relayers\n- **Quorum Validation**: Ensures multiple relayer signatures for security\n- **Batch Execution Tracking**: Monitors and tracks batch execution status\n\n#### **Roles \u0026 Access Control**\n\n- **Admin**: Can modify quorum, add/remove relayers, change timeouts, transfer admin role\n- **Relayer**: Can execute transfers and validate batches\n- **Public**: Can view bridge state, batch information, and execution status\n\n#### **Key Endpoints**\n\n- **`execute_transfer\u003cT\u003e`**: Main function for executing cross-chain transfers\n  - Requires relayer authentication\n  - Validates quorum signatures\n  - Processes multiple transfers in a single call\n  - Marks batch completion status\n- **`add_relayer`**: Admin function to add new relayers with public keys\n- **`remove_relayer`**: Admin function to remove relayers (maintains quorum)\n- **`set_quorum`**: Admin function to adjust required signature count\n\n#### **Views \u0026 Queries**\n\n- **`get_batch`**: Retrieve batch information and finality status\n- **`get_batch_deposits`**: Get all deposits for a specific batch\n- **`was_batch_executed`**: Check if a batch has been processed\n- **`get_statuses_after_execution`**: Get transfer execution results\n- **`is_relayer`**: Verify if an address is an authorized relayer\n\n#### **Security Features**\n\n- **Ed25519 Signature Verification**: Cryptographic validation of relayer signatures\n- **Quorum Enforcement**: Minimum 3 signatures required for any transfer\n- **Message Hash Construction**: Secure message construction for signature verification\n- **Duplicate Signature Prevention**: Ensures each relayer signs only once\n\n### Safe Module (`safe.move`)\n\nThe safe module manages token storage, user deposits, and batch creation for outbound transfers.\n\n#### **Capabilities**\n\n- **Token Storage**: Secure storage of deposited tokens\n- **Batch Management**: Automatic batch creation and management\n- **Token Whitelisting**: Configurable token support with limits\n- **Emergency Controls**: Pausable operations for security incidents\n\n#### **Roles \u0026 Access Control**\n\n- **Admin**: Can whitelist/remove tokens, set limits, adjust timeouts, manage bridge address\n- **Bridge**: Can transfer tokens out (requires BridgeCap)\n- **Public**: Can deposit tokens and view safe state\n- **Pausable**: All operations can be paused by admin\n\n#### **Key Endpoints**\n\n- **`deposit\u003cT\u003e`**: User function to deposit tokens for cross-chain transfer\n  - Validates token whitelist status\n  - Checks amount limits (min/max)\n  - Automatically manages batch creation\n  - Emits deposit events\n\n#### **Storage Mechanism - Bag of Coins**\n\nThe safe module uses a sophisticated storage system to manage deposited tokens efficiently:\n\n- **Coin Storage**: Uses Sui's `Bag` data structure to store coins of different token types\n- **Type-based Organization**: Each token type has its own storage slot identified by the token's type name bytes\n- **Automatic Coin Joining**: When new deposits arrive, coins of the same type are automatically joined together\n- **Efficient Management**: The system maintains a single coin object per token type, reducing storage overhead\n\n**How It Works:**\n\n1. **Initial Deposit**: First deposit of a token type creates a new storage slot in the bag\n2. **Subsequent Deposits**: Additional deposits of the same token type are joined with existing coins\n3. **Balance Tracking**: Total balance is tracked separately in the token configuration for quick access\n4. **Transfer Optimization**: When transfers occur, coins are split from the stored amount without affecting other operations\n\n- **`transfer\u003cT\u003e`**: Bridge function to send tokens to recipients\n  - Requires BridgeCap authentication\n  - Updates token balances\n  - Returns success/failure status\n- **`whitelist_token\u003cT\u003e`**: Admin function to enable new tokens\n- **`init_supply\u003cT\u003e`**: Admin function to initialize native token supply\n\n#### **Views \u0026 Queries**\n\n- **`get_batch`**: Get batch information and finality status\n- **`get_deposits`**: Retrieve all deposits for a specific batch\n- **`get_stored_coin_balance\u003cT\u003e`**: Check current token balance in safe\n- **`is_token_whitelisted\u003cT\u003e`**: Verify if a token is supported\n- **`get_token_min_limit\u003cT\u003e` / `get_token_max_limit\u003cT\u003e`**: Get token transfer limits\n\n#### **Batch Management**\n\n- **Automatic Creation**: New batches created based on timeouts or size limits\n- **Configurable Timeouts**: Adjustable batch progress and settlement timeouts\n- **Size Limits**: Configurable maximum batch size (default: 10, max: 100)\n- **Timestamp Tracking**: Monitors batch creation and update times\n\n#### **Configuration Management**\n\n- **Token Limits**: Per-token minimum and maximum transfer amounts\n- **Batch Timeouts**: Configurable intervals for batch progress and settlement\n- **Bridge Address**: Configurable bridge contract address\n- **Pause Controls**: Emergency pause/unpause functionality\n\n#### **Event System**\n\n- **Deposit Events**: Emitted for each successful deposit\n- **Token Events**: Whitelist additions/removals and limit updates\n- **Batch Events**: Batch creation and management events\n- **Admin Events**: Configuration changes and role transfers\n\n## Development\n\n### Prerequisites\n\n- Sui CLI installed and configured\n- Move development environment set up\n\n### Testing\n\n```bash\n# Run all tests\nsui move test\n\n# Run tests with coverage\nsui move test --coverage\n\n# Run specific test file\nsui move test --filter bridge_comprehensive_tests\n```\n\n###Setup\n\nFor detailed setup instructions, see [SETUP.md](./SETUP.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmultiversx%2Fmx-bridge-sc-sui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmultiversx%2Fmx-bridge-sc-sui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmultiversx%2Fmx-bridge-sc-sui/lists"}