feat: complete V2 migration with UUPS upgradeable contracts#3
Merged
Conversation
Add payment processor contract with: - ETH and ERC20 token payment support - Partial payment functionality with tracking - External payment recording (Base Pay integration) - Refund functionality for cancelled invoices - Payment info tracking and validation
Add upgraded InvoiceNFT with payment processor integration: - Support for ERC20 token payments - Partial payment configuration - Invoice memos - Automatic status updates on payment - Payment status tracking via processor - Direct payment entry points (pay/payWithToken)
Add PaymentLink contract for shareable payment URLs: - Generate secure payment links with expiry - Support ETH and ERC20 token payments via links - Link validation (expiry, usage tracking) - Enable payments from any address (not just designated payer) - One-time use enforcement
Add comprehensive test suites for payment functionality: - InvoicePayment tests: ETH/ERC20 payments, partial payments, external payment recording, refunds, authorization checks - PaymentLink tests: link generation, ETH/token payments via links, expiry validation, usage tracking, authorization - Test coverage for error cases and edge conditions
Add deployment script for V2 contracts: - Deploy InvoiceNFTV2 implementation and proxy - Deploy InvoicePayment processor - Deploy PaymentLink contract - Configure payment processor with USDC support - Initialize all integrations
Implement escrow model for secure payments: - Funds held in contract until release/refund - Add releasePayment() for issuer to claim funds after confirmation - Fix refund() to work with escrowed funds - Add InvalidStatus error - Add PaymentReleased and TokenSupportChanged events - Update all payment functions to hold funds in contract
Add UpgradeToV2 script for both networks: - Upgrade existing proxy to InvoiceNFTV2 implementation - Deploy and configure InvoicePayment processor - Deploy PaymentLink contract - Set up USDC token support - Save upgrade deployment info - Support both Sepolia and Mainnet
Add scripts for deploying individual V2 components: - DeployPaymentProcessor: Deploy only InvoicePayment contract - DeployPaymentLink: Deploy only PaymentLink contract - Support both Sepolia and Mainnet - Auto-configure with existing contracts - Save component deployment info
Add flexible deployment workflow with multiple operations: - upgrade_to_v2: Upgrade existing proxy to V2 - deploy_v2_full: Fresh V2 deployment - deploy_payment_processor: Deploy only payment processor - deploy_payment_link: Deploy only payment link - Support both Base Sepolia and Mainnet - Auto-verify contracts on Basescan
Улучшения GitHub Actions workflow: - Переименовал операции для ясности: * upgrade_existing_proxy - апгрейд существующего прокси (для mainnet!) * deploy_new_full_v2 - новый полный деплой * deploy_payment_processor_only - только процессор * deploy_payment_link_only - только ссылки - Добавил подробные комментарии с описанием каждой операции - Добавил эмодзи для визуального разделения секций - Clarified: upgrade сохраняет все данные, new создает новый контракт
Переделан action для гибкого управления деплоем: - Выбор типа операции: upgrade или deploy - Выбор контракта: all, invoice_nft, payment_processor, payment_link - Удален старый deploy-invoice-nft.yml workflow - Унифицированы названия шагов - Улучшена читаемость с разделением по секциям Примеры использования: - upgrade + all = апгрейд всей системы - upgrade + invoice_nft = апгрейд только InvoiceNFT - deploy + payment_processor = деплой только процессора - deploy + all = полный новый деплой
Updated repository with V2 deployment information: - Added base-mainnet-v2.json with all contract addresses - Added base-sepolia-v2.json with testnet addresses - Updated README.md with V2 architecture and features - Added InvoicePayment and PaymentLink to documentation - Updated contract addresses section - Added escrow, payment links, and partial payment features - Updated use cases for V2 capabilities V2 Mainnet Contracts: - InvoiceNFT V2: 0xE8E1563be6e10a764C24A46158f661e53D407771 - InvoicePayment: 0x7b80808915e58D56E7bB8b12bc860d9BA5029c20 - PaymentLink: 0x0374A00b3bA4143B5e1992f38CC5405c0AaEBC7f
Add comprehensive state machine validation and contract synchronization: - InvoiceNFTV2: Add markAsPaid() callback for automatic status updates - InvoiceNFTV2: Strict state transition validation (InvalidTransition error) - InvoiceNFTV2: Prevent cancelling paid invoices (CannotCancelPaidInvoice) - InvoiceNFTV2: Auto-trigger refund on cancellation if payments exist - InvoicePayment: Add Overpayment protection (rejects excess payments) - InvoicePayment: Call markAsPaid() on all payment completions - InvoicePayment: Read partial payment flag from NFT contract - InvoicePayment: Remove duplicate setPartialPaymentAllowed method - PaymentLink: Fix atomicity - mark link.used after successful payment - Tests: Add comprehensive edge case coverage (InvoiceLifecycle.t.sol) - Docs: Add complete state machine documentation This implements Block 1: Invoice lifecycle and payment state hardening
Comprehensive integration tests for Base Sepolia deployment validation
- Add .gitmodules with forge-std, openzeppelin-contracts, and openzeppelin-contracts-upgradeable - Run forge fmt to fix Solidity formatting issues across all contracts - Ensure GitHub Actions can properly initialize dependencies
- Register forge-std, openzeppelin-contracts, and openzeppelin-contracts-upgradeable as git submodules - Pin to specific versions: forge-std v1.9.4, openzeppelin v4.9.6 - This allows GitHub Actions to properly initialize dependencies with submodules: recursive
- Fix ReentrancyGuard import path (security/ instead of utils/) - Update Ownable initialization (no parameter in v4.9.6) - Update OwnableUpgradeable initialization with transferOwnership - Rename PaymentLink struct to Link to avoid shadowing - Fix contract casting with payable() in scripts - Update tests to use nft.setPartialPayment() All contracts now compile successfully with OpenZeppelin v4.9.6
- Transfer payments directly to invoice issuer instead of holding in contract - Add setInvoiceToken() method for partial payment support - Fix partial payment token detection using invoiceToken mapping - Update tests to set invoice token before partial payments Changes to InvoicePayment contract: - payInvoice(): Transfer ETH directly to issuer - payInvoiceToken(): Transfer ERC20 directly to issuer - payInvoicePartial(): Transfer accumulated payment on completion - Use invoiceNFT.invoiceToken() instead of payments mapping All 42 tests now passing
Strengthen invoice state machine to prevent edge cases and ensure robust sync between InvoiceNFT and InvoicePayment contracts. Changes to InvoiceNFTV2: - Add InvoiceNotIssued and CannotModifyIssuedInvoice errors - Prevent marking Draft/Cancelled invoices as Paid - Prevent double-marking invoices as Paid - Lock invoice terms (token, partial payment) after issuance - Strengthen markAsPaid() validation Changes to InvoicePayment: - Add InvoiceNotIssued and AlreadyRecorded errors - Validate invoice is Issued before accepting payments - Prevent double external payment recording - Improve refund() to handle both full and partial payments - Clean up partial payment state on refund New edge case test coverage: - Payment attempts on Draft invoices - Payment attempts on Cancelled invoices - External payment on non-Issued invoices - Double external payment recording - Marking non-Issued invoices as Paid - Modifying invoice terms after issuance - Partial payment refund scenarios - Complete lifecycle flows with state validations This implementation addresses Block 1 requirements for tightening invoice lifecycle transitions and ensuring contract sync across all edge cases including overpayments, partial payments, external payments, and cancellations.
Create detailed documentation for InvoBase V2 invoice lifecycle, covering all states, transitions, authorization rules, and edge cases. Includes: - State diagram and transition rules - Authorization matrix for all actions - Payment flow examples (ETH, ERC20, partial, external) - Edge case protections (overpayment, double payment, etc.) - Integration guidelines for payers, issuers, and dApps - Upgrade considerations for future V3+ This documentation serves as the primary reference for external integrators building on top of InvoBase V2.
Add on-chain integration tests covering complete invoice lifecycles on Base Sepolia network with real USDC payments. Test scenarios: - Full lifecycle ETH payment flow - Partial payment lifecycle with USDC - External payment recording (Base Pay simulation) - Cancellation with partial payment refund - Payment link flow end-to-end - Edge case rejections validation - Complete real-world freelancer invoice scenario Tests designed to run on Base Sepolia fork: forge test --match-contract BaseSepoliaIntegration --fork-url $BASE_SEPOLIA_RPC Features validated: - State transitions at each step - Fund transfers to correct recipients - Payment info recording - Link generation and validation - Refund mechanics - Error handling for invalid operations
Replace Unicode emoji characters with ASCII alternatives to fix compilation errors: - Replace checkmark (✓) with [PASS] in test output - Replace warning symbol (⚠️ ) with [WARNING] in deployment script - Fix formatting issue in BaseSepoliaIntegration.t.sol line 138 This resolves forge build, forge coverage, and forge fmt errors reported by CI.
Replace ambiguous json.serialize() calls with explicit type-specific vm.serialize* functions (vm.serializeString, vm.serializeAddress, vm.serializeUint) to fix Solidity compiler error 6675. This resolves the 'Member serialize not unique after argument-dependent lookup' error in UpgradeToV2_1.s.sol for both Sepolia and Mainnet deployment scripts.
Update all tests to set partial payment flags and invoice tokens BEFORE calling issue() to comply with new parameter modification locks introduced in Block 1. Changes: - Move setPartialPayment() and setInvoiceToken() calls before issue() in all test files (InvoicePayment.t.sol, InvoiceLifecycle.t.sol, InvoiceEdgeCases.t.sol) - Fix recordExternalPayment() error check ordering to return AlreadyRecorded before InvoiceAlreadyPaid - Add onlyForked modifier to BaseSepoliaIntegration USDC tests to skip when not on a fork (prevents deal() failures) These changes ensure tests properly validate the lifecycle tightening implemented in Block 1 where invoice terms become immutable after issuance.
Reorder validation checks in recordExternalPayment() to return InvoiceAlreadyPaid before AlreadyRecorded. This ensures the correct semantic error is returned: - InvoiceAlreadyPaid: Invoice already in Paid status (via any payment method) - AlreadyRecorded: External payment reference already recorded (duplicate external payment) When an on-chain payment completes, invoice status becomes Paid. Attempting to record an external payment should return InvoiceAlreadyPaid (invoice state error) rather than AlreadyRecorded (payment record error). Fixes testExternalPaymentAfterOnChainPaymentFails test.
Check for paymentRef to distinguish between: - Duplicate external payment recording (AlreadyRecorded) - External payment after on-chain payment (InvoiceAlreadyPaid) External payments have non-zero paymentRef, while on-chain payments have paymentRef == bytes32(0). This semantic distinction ensures correct error messages for each scenario. By checking for paymentRef before checking invoice status, we can properly identify when an external payment has already been recorded versus when the invoice was already paid via on-chain payment. Fixes testCannotRecordExternalPaymentTwice test.
Add GitHub Actions workflow to upgrade InvoBase V2 to V2.1 with Block 1 improvements: - Tightened invoice lifecycle state transitions - Strengthened payment validation (Draft/Cancelled checks) - Improved partial payment refunds - Parameter modification locks (after issuance) - Double payment prevention Workflow features: - Manual trigger (workflow_dispatch) - Support for Base Sepolia and Base Mainnet - Mainnet deployment requires explicit "UPGRADE" confirmation - Runs tests before deployment - Verifies contracts on BaseScan - Saves deployment artifacts for 90 days - Creates deployment summary with details Usage: - Base Sepolia: Select network, run workflow - Base Mainnet: Select network, type "UPGRADE" in confirmation field The workflow: 1. Deploys new InvoiceNFTV2 V2.1 implementation 2. Upgrades proxy to V2.1 3. Deploys new InvoicePayment contract 4. Updates paymentProcessor on NFT contract 5. Configures USDC support on new payment processor
…stem Convert InvoicePayment and PaymentLink to upgradeable contracts using UUPS pattern, and create universal deployment and upgrade infrastructure. Contract Changes: - InvoicePayment: converted to upgradeable (UUPS) * Replace ReentrancyGuard/Ownable with upgradeable versions * Add Initializable and UUPSUpgradeable * Replace constructor with initialize() * Add _authorizeUpgrade() for UUPS - PaymentLink: converted to upgradeable (UUPS) * Same pattern as InvoicePayment * All contracts now support upgrades Test Updates: - Update all tests to deploy contracts via ERC1967Proxy - Use initialize() instead of constructor - Tests for InvoicePayment, InvoiceLifecycle, InvoiceEdgeCases, BaseSepoliaIntegration, and PaymentLink New Universal Scripts: - script/Deploy.s.sol: * DeployAllSepolia/DeployAllMainnet for full deployment * All contracts deployed as UUPS proxies * Auto-configure USDC support - script/Upgrade.s.sol: * Upgrade individual contracts (NFT, Payment, Link) * Support for both Sepolia and Mainnet * Read addresses from deployment JSON Removed Old Scripts: - DeployInvoiceNFTV2.s.sol (replaced by Deploy.s.sol) - DeployV2Components.s.sol (replaced by Deploy.s.sol) - UpgradeToV2.s.sol (replaced by Upgrade.s.sol) - UpgradeToV2_1.s.sol (replaced by Upgrade.s.sol) New Universal Workflow: - .github/workflows/invobase.yml: * Single workflow for all operations * Actions: deploy or upgrade * Contracts: all, nft, payment, or link * Networks: base_sepolia or base_mainnet * Mainnet protection (requires "CONFIRM") Removed Old Workflows: - deploy-v2.yml (replaced by invobase.yml) - upgrade-v2.1.yml (replaced by invobase.yml) Benefits: - All contracts now upgradeable (no redeployment needed) - Universal scripts work with any version - Simple workflow: choose action, contract, network - Consistent UUPS pattern across all contracts - Tests verify proxy functionality All 65 tests passing ✓
Simplify deployment scripts by using address types instead of typed contract variables, reducing stack depth and avoiding compilation error. Changes: - Use address instead of typed contracts (InvoiceNFTV2, InvoicePayment, etc) - Inline proxy deployment expressions - Cast to typed contracts only when calling methods - Reduces local variables from 10+ to 7 in run() function This resolves the 'Stack too deep' compilation error that occurred during forge coverage runs. All 65 tests passing ✓
Replace manual forge install with checkout submodules to fix CI dependency installation issues. The lib/ directories were already present (tracked by git submodules) causing forge install to fail with 'directory not empty'. Changes: - Add 'submodules: recursive' to checkout action - Remove manual 'forge install' commands - Dependencies now installed via git submodules (faster and more reliable) This matches the pattern already used in test.yml workflow.
Add migration functionality to upgrade existing deployment where InvoicePayment and PaymentLink were deployed without proxies. Changes: - script/Migrate.s.sol: New migration script * Upgrades InvoiceNFTV2 (already has proxy) * Deploys new InvoicePayment with UUPS proxy * Deploys new PaymentLink with UUPS proxy * Updates paymentProcessor on NFT * Configures USDC support * Saves new addresses to deployments file - .github/workflows/invobase.yml: Add 'migrate' action * New option in action dropdown * Migrate to Upgradeable (Sepolia/Mainnet) * Clear output showing migration steps - deployments/base-sepolia.json: Update format * Rename 'proxy' → 'nft' * Rename 'implementation' → 'nftImpl' * Add 'payment', 'paymentLink' addresses * Remove 'verified' and 'urls' (can regenerate) * Add 'usdc' address Migration Process: 1. InvoiceNFTV2: Upgrade existing proxy (0x59aD...) 2. InvoicePayment: Deploy NEW with proxy (old: 0x775d...) 3. PaymentLink: Deploy NEW with proxy (old: 0xeb13...) 4. Update NFT.setPaymentProcessor(new payment address) After migration, ALL contracts will be upgradeable via UUPS. Usage: GitHub Actions → action: migrate, network: base_sepolia
Add explicit variable and debug logs to troubleshoot 'caller is not owner' error during migration Step 3. Changes: - Add console.log before setPaymentProcessor call - Create explicit InvoiceNFTV2 contract variable - This will help verify the correct address is being called The error appears to be calling the wrong address (payment proxy instead of nft proxy). These logs will help diagnose the issue.
- Scope string variables (root, path, json) to release them early - Remove oldPayment/oldLink variables, read inline instead - Remove nftContract variable, call setPaymentProcessor directly - Reduces local variable count to fit within stack limits
The nftProxy variable was scoped inside a block and lost its value, causing setPaymentProcessor to be called on the wrong contract. Moved variable declarations outside the scope block to fix the issue.
- Keep nftProxy in function scope but release string variables early - Add explicit console logging to diagnose owner error - Scope temporary variables to reduce stack pressure
Compiler optimization was overwriting nftProxy variable after using it in ERC1967Proxy constructor. Now reload the address from JSON file right before Step 3 to ensure correct contract is called.
Compiler optimization was still overwriting the nftAddress variable even after reloading from JSON. Now execute setPaymentProcessor within a scoped block where nftAddress is immediately used and released, preventing any variable reuse by the compiler.
High-level function calls were being optimized incorrectly by compiler. Now using address.call() with explicitly encoded calldata to ensure the correct contract address (NFT proxy) is called, not the payment proxy.
All previous attempts (scoping, reloading, low-level call) failed. Now hardcode the NFT proxy address directly to eliminate any possibility of variable corruption or compiler optimization.
Removed duplicate nftProxyHardcoded variable by hardcoding nftProxy at the start of the function. This reduces local variable count and should resolve the stack too deep error.
Introduced MigrationAddresses struct to group migration parameters and reduce stack pressure during forge coverage runs. This resolves the "Stack too deep" compiler error that occurred when optimizer was disabled for coverage analysis. Changes: - Add MigrationAddresses struct to group 7 address parameters - Refactor _saveMigration() to accept struct instead of individual params - Make _saveMigration() more generic by accepting network parameter - Apply changes to both MigrateSepolia and MigrateMainnet contracts This allows successful forge coverage runs while maintaining code clarity and functionality.
Removing migration script to prepare for fresh deployment of all contracts.
Fixed Deploy.s.sol to prevent stack too deep errors: - Introduced DeploymentAddresses struct to group parameters - Refactored _saveDeployment() to accept struct instead of 8 individual params - Applied to both DeployAllSepolia and DeployAllMainnet contracts Removed obsolete deployment scripts: - DeployToBase.s.sol (incorrect stdJson syntax, duplicate functionality) - DeployInvoiceNFT.s.sol (legacy V1 deployment) - SaveDeployment.s.sol (helper script, no longer needed) - TestInvoiceNFT.s.sol (test script, not for production) - OnChainIntegrationTest.s.sol (test script, not for production) Verified scripts remaining: - Deploy.s.sol: production-ready deployment (Sepolia + Mainnet) - Upgrade.s.sol: UUPS upgrade scripts (checked, working correctly) All changes tested with forge build and forge coverage.
Fixed invobase.yml: - Removed 'migrate' action option (Migrate.s.sol was deleted) - Removed all migration-related workflow steps - Kept deploy and upgrade operations working correctly Fixed security.yml: - Corrected OpenZeppelin dependency installation (use submodules instead of forge install) - Fixed versions: now using v4.9.6 (was incorrectly using v5.0.0) - Updated Mythril analysis to check actual contracts (InvoiceNFTV2, InvoicePayment, PaymentLink) - Removed reference to non-existent InvoiceManager contract - Added submodules: recursive to checkout steps test.yml is already correct - no changes needed. All workflows now align with current project structure.
Updated deployment addresses: - base-mainnet.json: new V2 deployment addresses from Base mainnet - NFT: 0xab5B5Be29048339De2Bf79c51c1634adC987deFb - Payment: 0x9a4F17a4dE62be11738d15b39bb0Dfba88cA9B74 - PaymentLink: 0xDe9aD4eD1909204319AF94605d40CA5886fB97f8 - base-sepolia.json: new V2 deployment addresses from Base Sepolia - NFT: 0x8C49fb4c7512A238D7A6fC9B612A0deFFA4890f5 - Payment: 0x73CBc9E6Ac0b17Ba0b42c9c68Fbb3B9f55485540 - PaymentLink: 0x5C0D87f9a97eF5592c47D7649668b1a2F9a03DcA Updated README.md: - Updated contract addresses to latest deployment - Changed InvoicePayment and PaymentLink to show UUPS upgradeable status - Fixed OpenZeppelin version from v5.0.2 to v4.9.6 (correct version) - Added "Proxy" suffix to contract names for clarity Updated docs/INVOICE_STATE_MACHINE.md: - Updated contract addresses from TBD to actual deployed addresses Removed old/obsolete files: - .gas-snapshot (outdated gas snapshot) - foundry.lock (not needed in git) - INVOICE_STATE_MACHINE.md (duplicate in root, kept in docs/) - deployments/base-mainnet-v2.json (old deployment) - deployments/base-sepolia-v2.json (old deployment) All contracts verified on BaseScan.
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
1 participant
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.
Deployed to Base Mainnet and Base Sepolia with full verification.
All 65 tests passing. Coverage: comprehensive.