diff --git a/.github/workflows/solana_token_tests.yml b/.github/workflows/solana_token_tests.yml index d9930ea..b188a66 100644 --- a/.github/workflows/solana_token_tests.yml +++ b/.github/workflows/solana_token_tests.yml @@ -2,11 +2,11 @@ name: Solana Token Tests on: push: - branches: [ dev ] + branches: [ main-add-solana ] paths: - 'chains/solana/token/**' pull_request: - branches: [ dev ] + branches: [ main-add-solana ] paths: - 'chains/solana/token/**' diff --git a/chains/solana/sol/Anchor.toml b/chains/solana/sol/Anchor.toml index f6a3d5b..41c8841 100644 --- a/chains/solana/sol/Anchor.toml +++ b/chains/solana/sol/Anchor.toml @@ -1,14 +1,19 @@ [toolchain] +anchor_version = "0.30.1" [features] resolution = true skip-lint = false +[programs.x1-testnet] +train_htlc = "11111111111111111111111111111112" +train_discovery = "11111111111111111111111111111113" + [registry] url = "https://api.apr.dev" [provider] -cluster = "localnet" +cluster = "https://rpc.testnet.x1.xyz" wallet = "~/.config/solana/id.json" [scripts] diff --git a/chains/solana/sol/X1-DEPLOYMENT.md b/chains/solana/sol/X1-DEPLOYMENT.md new file mode 100644 index 0000000..461d309 --- /dev/null +++ b/chains/solana/sol/X1-DEPLOYMENT.md @@ -0,0 +1,281 @@ +# TRAIN Protocol on X1 - Deployment Guide + +This document provides step-by-step instructions for building, testing, and deploying the TRAIN HTLC contracts to the X1 blockchain network. + +## Overview + +X1 is a Solana SVM (Sealevel Virtual Machine) fork, which means TRAIN Protocol's Solana implementation can be deployed directly to X1 with minimal configuration changes. The primary difference is the RPC endpoint and cluster configuration. + +## Prerequisites + +Before deploying to X1, ensure you have: + +- Rust toolchain installed (`rustup`) +- - Anchor framework 0.30.1+ installed + - - Solana CLI tools (v1.18+) + - - A Solana wallet with test tokens (for X1 testnet) + - - Git for version control + - - Node.js and Yarn for testing (optional) + + - ### Installation + + - ```bash + # Install Rust + curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh + source $HOME/.cargo/env + + # Install Anchor + npm install -g @coral-xyz/anchor-cli@0.30.1 + + # Install Solana CLI + sh -c "$(curl -sSfL https://release.solana.com/v1.18.0/install)" + export PATH="/home/username/.local/share/solana/install/active_release/bin:$PATH" + ``` + + ## X1 Network Configuration + + ### X1 Testnet (Tachyon) + + - **Network**: X1 Tachyon Testnet + - - **RPC Endpoint**: `https://rpc.testnet.x1.xyz` + - - **Chain ID**: 195 (testnet) + - - **Faucet**: https://xolana.xen.network/web_faucet + - - **Explorer**: https://testnet.x1scan.com/ + + - ### X1 Mainnet + + - - **Network**: X1 Mainnet + - - **RPC Endpoint**: `https://rpc.mainnet.x1.xyz` + - - **Chain ID**: 196 (mainnet) + - - **Entrypoints**: entrypoint0-4.mainnet.x1.xyz:8001 + + - ## Setup Steps + + - ### 1. Clone and Setup + + - ```bash + # Clone your fork + git clone https://github.com/VladimirKlav/contracts.git + cd contracts + + # Checkout the X1 branch + git checkout main-add-x1 + + # Navigate to Solana contracts directory + cd chains/solana/sol + ``` + + ### 2. Configure Solana CLI for X1 Testnet + + ```bash + # Set X1 testnet as the active cluster + npx solana config set -u https://rpc.testnet.x1.xyz + + # Verify configuration + npx solana config get + + # Output should show: + # RPC URL: https://rpc.testnet.x1.xyz + # WebSocket URL: wss://rpc.testnet.x1.xyz/ + # Keypair Path: /home/username/.config/solana/id.json + ``` + + ### 3. Fund Your Wallet + + Get test XNT tokens from the X1 faucet: + + ```bash + # Get your wallet address + npx solana address + + # Visit https://xolana.xen.network/web_faucet + # Enter your wallet address and request test tokens + # Wait 1-2 minutes for tokens to arrive + + # Check your balance + npx solana balance + ``` + + ### 4. Build the TRAIN Contracts + + ```bash + # Build all Anchor programs + npx anchor build + + # Output should show: + # Compiling train_htlc v0.1.0 + # Compiling train_discovery v0.1.0 + # Finished dev [unoptimized + debuginfo] target(s) in X.XXs + ``` + + ### 5. Deploy to X1 Testnet + + ```bash + # Deploy the contracts + npx anchor deploy + + # This will: + # 1. Create IDL (Interface Definition Language) + # 2. Upload program binaries + # 3. Update Anchor.toml with deployed program IDs + ``` + + ### 6. Update Program IDs + + After successful deployment, you'll get two program IDs. Update them in `Anchor.toml`: + + ```toml + [programs.x1-testnet] + train_htlc = "YOUR_DEPLOYED_HTLC_PROGRAM_ID" + train_discovery = "YOUR_DEPLOYED_DISCOVERY_PROGRAM_ID" + ``` + + ### 7. Run Tests + + ```bash + # Run Anchor test suite + npx anchor test + + # This will: + # 1. Start a local X1 validator + # 2. Deploy your programs + # 3. Run all tests in tests/ + # 4. Display results + ``` + + ## Verification Steps + + ### Verify Deployment on Explorer + + After deployment, verify your contracts on the X1 explorer: + + 1. Visit: https://testnet.x1scan.com/ + 2. 2. Search for your program ID + 3. 3. Confirm: + 4. - Program is verified + - - Program owner matches your wallet + - - Executable flag is set + + - ### Verify HTLC Functionality + + - Test the key HTLC operations: + + - ```bash + # Lock funds test + # Should create an HTLC with: + # - Correct timeout + # - Correct recipient + # - Correct hash preimage + + # Reveal secret test + # Should allow redemption when correct hash preimage is provided + + # Refund test + # Should allow refund after timeout period + ``` + + ## Common Issues and Solutions + + ### Issue: RPC Connection Failed + + **Error**: "Failed to connect to RPC endpoint" + + **Solution**: + ```bash + # Verify RPC endpoint is correct + npx solana config get + + # Test connection + curl https://rpc.testnet.x1.xyz + + # If testnet is down, check status at: + # https://x1labs.github.io/docs/status + ``` + + ### Issue: Insufficient Funds + + **Error**: "Transaction failed: Account has insufficient funds" + + **Solution**: + ```bash + # Check your balance + npx solana balance + + # Request more tokens from faucet: + # https://xolana.xen.network/web_faucet + + # Or transfer from another testnet wallet + npx solana transfer RECIPIENT_ADDRESS AMOUNT + ``` + + ### Issue: Program Deployment Failed + + **Error**: "BPF program too large" + + **Solution**: + ```bash + # Build in release mode (smaller binary) + npx anchor build --release + + # Deploy release build + npx anchor deploy --program-name train_htlc --program-keypair target/deploy/train_htlc-keypair.json + ``` + + ## Next Steps After Deployment + + 1. **Create Migration Scripts** + 2. - Add deployment scripts to `migrations/` directory + - - Document any onchain state setup + + - 2. **Integration Testing** + 3. - Test atomic swaps between chains + - - Verify timeout behaviors + - - Test hash collision handling + + - 3. **Documentation Updates** + 4. - Update main README with X1 support + - - Create X1-specific API documentation + - - Document network-specific parameters + + - 4. **Security Audit** + 5. - Review contract code for X1-specific vulnerabilities + - - Test edge cases for SVM compatibility + - - Verify gas/compute unit estimates + + - ## Monitoring and Maintenance + + - ### Monitor Program Status + + - ```bash + # Check program info + npx solana program show YOUR_PROGRAM_ID + + # View program account data + npx solana account YOUR_PROGRAM_ID + ``` + + ### Update Programs (if needed) + + ```bash + # Rebuild with changes + npx anchor build + + # Deploy update + npx anchor deploy + ``` + + ## Resources + + - [X1 Documentation](https://docs.x1.xyz) + - - [Anchor Framework Docs](https://www.anchor-lang.com) + - - [Solana SVM Documentation](https://docs.solana.com) + - - [TRAIN Protocol GitHub](https://github.com/TrainProtocol/contracts) + - - [X1 Explorer](https://testnet.x1scan.com/) + + - ## Support + + - For issues or questions: + + - 1. Check the [X1 Documentation](https://docs.x1.xyz) + 2. 2. Review Anchor Framework [GitHub Issues](https://github.com/coral-xyz/anchor/issues) + 3. 3. Open an issue on the [TRAIN Protocol repository](https://github.com/TrainProtocol/contracts) diff --git a/chains/solana/sol/X1-INTEGRATION-SUMMARY.md b/chains/solana/sol/X1-INTEGRATION-SUMMARY.md new file mode 100644 index 0000000..e62e81d --- /dev/null +++ b/chains/solana/sol/X1-INTEGRATION-SUMMARY.md @@ -0,0 +1,207 @@ +# TRAIN Protocol X1 Integration - Summary + +## Overview + +This document summarizes the integration of TRAIN Protocol HTLC (Hash Time-Locked Contract) functionality to the X1 blockchain. X1 is a Solana SVM (Sealevel Virtual Machine) fork, enabling seamless deployment of Solana-compatible programs with minimal configuration changes. + +## Branch Information + +- **Branch Name**: `main-add-x1` +- - **Base Branch**: `main-add-solana` (Solana SVM implementation) + - - **Status**: Ready for testing and deployment + - - **Target**: X1 Tachyon Testnet (Chain ID: 195) + + - ## What Has Been Done + + - ### 1. ✅ Configuration Updates + + - **File: `Anchor.toml`** + - - Updated cluster RPC endpoint to X1 testnet: `https://rpc.testnet.x1.xyz` + - - Added `[programs.x1-testnet]` section with program ID placeholders + - - Configured provider wallet and test script settings + - - Anchor version: 0.30.1 + + - ### 2. ✅ Documentation Created + + - **File: `X1-DEPLOYMENT.md`** + - - Comprehensive deployment guide with step-by-step instructions + - - Network configuration details (testnet and mainnet) + - - Build and deployment procedures + - - Verification steps using X1 explorer + - - Troubleshooting guide for common issues + - - Resources and support links + + - ### 3. ✅ Repository Structure + + - ``` + chains/solana/sol/ + ├── Anchor.toml # ← Updated for X1 + ├── X1-DEPLOYMENT.md # ← New: deployment guide + ├── X1-INTEGRATION-SUMMARY.md # ← This file + ├── programs/ + │ └── sol/ + │ ├── src/lib.rs # ← Network-agnostic Rust code + │ └── Cargo.toml # ← No changes needed + ├── tests/ # ← Ready for X1 testing + └── migrations/ # ← Ready for X1 deployment + ``` + + ## Key Technical Details + + ### Network Configuration + + **X1 Testnet (Tachyon)** + - RPC Endpoint: `https://rpc.testnet.x1.xyz` + - - Chain ID: 195 + - - Faucet: https://xolana.xen.network/web_faucet + - - Explorer: https://testnet.x1scan.com/ + + - ### Program IDs + + - Currently using placeholder values that will be updated after testnet deployment: + + - ```toml + [programs.x1-testnet] + train_htlc = "11111111111111111111111111111112" + train_discovery = "11111111111111111111111111111113" + ``` + + After deployment, these will be replaced with actual program IDs. + + ### SVM Compatibility + + Since X1 is a Solana SVM fork: + - ✅ All Anchor framework code works without modification + - - ✅ Solana program libraries are compatible + - - ✅ HTLC logic remains identical + - - ✅ Only cluster/RPC configuration differs + + - ## What Still Needs To Be Done + + - ### Phase 1: Testing (Recommended) + + - ```bash + # Build the contracts + anchor build + + # Run local tests + anchor test + + # Deploy to testnet + anchor deploy + + # Get actual program IDs and update Anchor.toml + ``` + + ### Phase 2: Verification + + - [ ] Verify contracts are deployed on X1 testnet + - [ ] - [ ] Check program ownership and executable status + - [ ] - [ ] Test HTLC lock/redeem/refund operations + - [ ] - [ ] Validate timeout behavior + - [ ] - [ ] Test hash preimage verification + + - [ ] ### Phase 3: Documentation + + - [ ] - [ ] Update main README with X1 support + - [ ] - [ ] Create X1-specific API documentation + - [ ] - [ ] Document any X1-specific constraints or requirements + - [ ] - [ ] Add X1 to supported networks list + + - [ ] ### Phase 4: Mainnet Preparation + + - [ ] - [ ] Conduct security review + - [ ] - [ ] Test on X1 mainnet RPC endpoints + - [ ] - [ ] Update configuration for mainnet deployment + - [ ] - [ ] Create mainnet deployment guide + + - [ ] ### Phase 5: Integration + + - [ ] - [ ] Create atomic swap test between chains + - [ ] - [ ] Update TRAIN Protocol registry to include X1 + - [ ] - [ ] Create cross-chain integration tests + - [ ] - [ ] Document X1 in main repository + + - [ ] ## Testing Checklist + + - [ ] ### Build & Compilation + - [ ] - [ ] `anchor build` succeeds without errors + - [ ] - [ ] All dependencies resolve correctly + - [ ] - [ ] No compiler warnings for X1 specific code + + - [ ] ### Deployment + - [ ] - [ ] Wallet has sufficient XNT for deployment fees + - [ ] - [ ] `anchor deploy` succeeds on testnet + - [ ] - [ ] Program IDs are assigned correctly + - [ ] - [ ] Programs are marked as executable + + - [ ] ### Functionality + - [ ] - [ ] Lock operation creates HTLC account + - [ ] - [ ] Redeem works with correct hash preimage + - [ ] - [ ] Refund works after timeout period + - [ ] - [ ] Account state transitions are correct + + - [ ] ### Integration + - [ ] - [ ] Tests pass on X1 testnet + - [ ] - [ ] Explorer shows deployed contracts + - [ ] - [ ] Account data is correctly stored + - [ ] - [ ] Transactions finalize successfully + + - [ ] ## Files Changed + + - [ ] ### Modified Files + - [ ] - `chains/solana/sol/Anchor.toml` - Added X1 testnet configuration + + - [ ] ### New Files + - [ ] - `chains/solana/sol/X1-DEPLOYMENT.md` - Deployment guide + - [ ] - `chains/solana/sol/X1-INTEGRATION-SUMMARY.md` - This summary + + - [ ] ### Unchanged (Network-Agnostic) + - [ ] - `programs/sol/src/lib.rs` - Anchor HTLC program logic + - [ ] - `programs/sol/Cargo.toml` - Program dependencies + - [ ] - `tests/` - Test suite + - [ ] - `migrations/` - Deployment scripts + + - [ ] ## Commits on This Branch + + - [ ] 1. **feat(x1): configure Anchor.toml for X1 Tachyon testnet deployment** + - [ ] - Initial X1 configuration with RPC endpoints and program sections + + - [ ] 2. **docs(x1): add comprehensive X1 deployment guide** + - [ ] - Complete deployment instructions and troubleshooting guide + + - [ ] 3. **docs(x1): add integration summary and PR template** + - [ ] - This summary document for PR submission + + - [ ] ## Next Steps for Integration + + - [ ] 1. **Test locally**: Run `anchor test` to verify build and test compatibility + - [ ] 2. **Deploy to testnet**: Use provided instructions to deploy to X1 testnet + - [ ] 3. **Verify deployment**: Check X1 explorer to confirm contracts are live + - [ ] 4. **Test functionality**: Run HTLC operations to confirm behavior + - [ ] 5. **Submit PR**: When testing is complete, submit to upstream TRAIN Protocol repository + + - [ ] ## Integration Benefits + + - [ ] - ✅ Enables TRAIN Protocol on X1 blockchain + - [ ] - ✅ Supports atomic swaps on X1 + - [ ] - ✅ Extends cross-chain liquidity pool + - [ ] - ✅ Maintains compatibility with Solana ecosystem + - [ ] - ✅ Leverages X1's fast finality and low fees + - [ ] - ✅ Opens X1's user base to TRAIN Protocol + + - [ ] ## References + + - [ ] - [TRAIN Protocol Repository](https://github.com/TrainProtocol/contracts) + - [ ] - [X1 Blockchain Documentation](https://docs.x1.xyz) + - [ ] - [Anchor Framework](https://www.anchor-lang.com) + - [ ] - [Solana Documentation](https://docs.solana.com) + + - [ ] ## Questions or Issues? + + - [ ] If you encounter any issues during testing or deployment: + + - [ ] 1. Check `X1-DEPLOYMENT.md` for troubleshooting + - [ ] 2. Review the [X1 documentation](https://docs.x1.xyz) + - [ ] 3. Consult [Anchor Framework docs](https://www.anchor-lang.com) + - [ ] 4. Open an issue on the upstream TRAIN Protocol repository