{"id":24390467,"url":"https://github.com/texora/blockhead-documentation","last_synced_at":"2025-06-26T23:33:37.843Z","repository":{"id":272792620,"uuid":"893192063","full_name":"texora/Blockhead-Documentation","owner":"texora","description":"Blockhead Documentation","archived":false,"fork":false,"pushed_at":"2024-11-24T01:56:00.000Z","size":29,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-10T19:57:05.826Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"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/texora.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-23T19:18:35.000Z","updated_at":"2024-11-25T17:02:10.000Z","dependencies_parsed_at":"2025-01-16T17:42:10.210Z","dependency_job_id":"4c118b67-401c-446a-919c-418ae280db84","html_url":"https://github.com/texora/Blockhead-Documentation","commit_stats":null,"previous_names":["texora/blockhead-documentation"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/texora%2FBlockhead-Documentation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/texora%2FBlockhead-Documentation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/texora%2FBlockhead-Documentation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/texora%2FBlockhead-Documentation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/texora","download_url":"https://codeload.github.com/texora/Blockhead-Documentation/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243307495,"owners_count":20270263,"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","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-01-19T16:17:44.529Z","updated_at":"2025-03-12T23:14:17.872Z","avatar_url":"https://github.com/texora.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"## **Overview**\n\nBlockhead is a decentralized, open-source, reputation-based payment processor built on Polygon. It facilitates crypto payments in MATIC using deterministic escrow wallets and decentralized oracles for trustless operations and dispute resolution.\n\n### **Key Features**\n1. **Secure Payments:**  \n   No-trust, deterministic payments stored in smart contract-controlled escrow wallets.\n   \n2. **Reputation-Bound Dispute Resolution:**  \n   Marketplace Oracles resolve disputes based on pre-configured rules, with transparency and fairness.\n\n3. **Permissionless Functionality:**  \n   Open to all users without restrictions, enabling invoice creation and payment management.\n\n4. **Automated Refunds:**  \n   For overpayments, underpayments, and canceled transactions.\n\n### **Core Components**\n1. **Website:**  \n   IPFS-hosted React application for user interaction, including invoice creation and payment tracking.\n   \n2. **Smart Contracts:**  \n   Solidity contracts handle payment processing, state management, refunds, and oracle integration.\n\n3. **Escrow Wallet:**  \n   Secure wallet holding funds temporarily until predefined release conditions are met.\n\n4. **Marketplace Oracles:**  \n   External entities validate invoices, manage escrow hold periods, and resolve disputes.\n\n5. **Blockchain Oracles:**  \n   Automated systems monitor on-chain activity and trigger contract state changes.\n\n---\n\n## **Development Phases and Budget**\n\n### **Phase 0: Specification and Platform Setup**\n**Objectives:**\n- Finalize specifications.\n- Develop an IPFS-hosted landing page (`blockheadverifybytoken.eth`).\n- Enable wallet authentication using WalletConnect.\n\n**Deliverables:**\n- Landing page wireframe hosted on IPFS.\n- Integrated Polygon-compatible wallet login.\n\n**Budget:** $1,500 + bonus.\n\n---\n\n### **Phase 1: Basic Functions and Smart Contracts**\n**Objectives:**\n- Develop core features:\n  - Admin controls.\n  - Invoice creation, acceptance, and cancellation.\n  - Payment processing and escrow management.\n- Deploy foundational smart contracts.\n- Pass initial security audit.\n\n**Deliverables:**\n- Functional website integrated with smart contracts.\n- Comprehensive documentation.\n- Audit 1 approval.\n\n**Budget:** $9,000 + bonus.\n\n---\n\n### **Phase 2: User-Enhancing Features**\n**Objectives:**\n- Add refunds, dispute handling, fiat conversion, and Marketplace Oracle integration.\n- Enable dynamic hold periods for invoices through Marketplace Oracles.\n\n**Deliverables:**\n- User-friendly interfaces and advanced workflows.\n- Integration of Marketplace Oracles for dispute and hold period management.\n- Audit 2 approval.\n\n**Budget:** $9,000 + bonus.\n\n---\n\n### **Phase 3: Scalability and Advanced Features**\n**Objectives:**\n- Add zk-rollups for scalability.\n- Introduce wallet notifications and enhanced admin controls.\n- Enable advanced contract features like multi-signature approvals and transaction disposal.\n\n**Deliverables:**\n- Fully scalable system with zk-rollups and wallet messaging.\n- Advanced features integrated into smart contracts.\n- Audit 3 approval.\n\n**Budget:** $8,000 + bonus.\n\n---\n\n## **Functional Specifications**\n\n### **Admin Functions**\n\nAdmins control the system using `/admin`, with actions restricted to authorized wallet addresses.\n\n---\n\n#### **Admin Authentication**\n**Description:** Admins authenticate using their wallet keys, which are encoded in the smart contract.\n\n**Example Code:**\n```solidity\nmapping(address =\u003e bool) public isAdmin;\n\nmodifier onlyAdmin() {\n    require(isAdmin[msg.sender], \"Not authorized\");\n    _;\n}\n\nfunction addAdmin(address _admin) external onlyAdmin {\n    isAdmin[_admin] = true;\n}\n\nfunction removeAdmin(address _admin) external onlyAdmin {\n    isAdmin[_admin] = false;\n}\n```\n\n---\n\n#### **Transfer Admin Control**\n**Description:** Allows the current admin to transfer control to another wallet, with secondary confirmation.\n\n**Example Code:**\n```solidity\naddress public pendingAdmin;\n\nfunction initiateAdminTransfer(address _newAdmin) external onlyAdmin {\n    require(_newAdmin != address(0), \"Invalid address\");\n    pendingAdmin = _newAdmin;\n}\n\nfunction confirmAdminTransfer() external {\n    require(msg.sender == pendingAdmin, \"Not authorized\");\n    isAdmin[pendingAdmin] = true;\n    isAdmin[msg.sender] = false;\n    pendingAdmin = address(0);\n}\n```\n\n---\n\n#### **Shut Off Switch**\n**Description:** Pauses all operations for emergencies and allows resumption when resolved.\n\n**Example Code:**\n```solidity\nbool public isPaused;\n\nfunction pauseOperations() external onlyAdmin {\n    isPaused = true;\n}\n\nfunction resumeOperations() external onlyAdmin {\n    isPaused = false;\n}\n```\n\n---\n\n#### **Set Oracles and Wallet Configurations**\n**Description:** Admins configure the addresses for Marketplace Oracles and the Escrow Wallet.\n\n**Example Code:**\n```solidity\naddress public oracleAddress;\naddress public escrowWallet;\n\nfunction setOracleAddress(address _oracle) external onlyAdmin {\n    oracleAddress = _oracle;\n}\n\nfunction setEscrowWallet(address _wallet) external onlyAdmin {\n    escrowWallet = _wallet;\n}\n```\n\n---\n\n### **Invoice Management**\n\n#### **Invoice Creation**\n**Workflow:**\n1. Creators input invoice details (amount, expiration, payer wallet).\n2. Smart contract validates data and stores it.\n3. The system generates a unique invoice ID and payment address.\n\n**Example Code:**\n```solidity\nstruct Invoice {\n    uint256 id;\n    address creator;\n    address payer;\n    uint256 amount;\n    uint256 expiration;\n    string state; // \"Created\", \"Paid\", \"Accepted\", etc.\n}\n\nInvoice[] public invoices;\n\nfunction createInvoice(\n    address _payer,\n    uint256 _amount,\n    uint256 _expiration\n) external returns (uint256) {\n    require(_expiration \u003e block.timestamp, \"Invalid expiration\");\n\n    uint256 invoiceId = invoices.length;\n    invoices.push(Invoice({\n        id: invoiceId,\n        creator: msg.sender,\n        payer: _payer,\n        amount: _amount,\n        expiration: _expiration,\n        state: \"Created\"\n    }));\n\n    return invoiceId;\n}\n```\n\n---\n\n#### **Invoice Payment**\n**Workflow:**\n1. Payers receive a payment URL and log in using WalletConnect.\n2. Payments are sent to a unique escrow address.\n3. Blockchain Oracles monitor transactions and update the state.\n\n**Example State Updates:**\n```solidity\nfunction updateInvoiceState(uint256 _invoiceId, string memory _state) external onlyOracle {\n    Invoice storage invoice = invoices[_invoiceId];\n    require(invoice.expiration \u003e block.timestamp, \"Invoice expired\");\n    invoice.state = _state;\n}\n```\n\n---\n\n#### **Refunds**\n**Trigger Conditions:**\n- Overpayment exceeds the required gas fees.\n- Invoice cancellation.\n- Marketplace Oracle reallocates funds.\n\n**Example Refund Process:**\n```solidity\nfunction refund(uint256 _invoiceId) external {\n    Invoice storage invoice = invoices[_invoiceId];\n    require(invoice.state == \"Cancelled\" || invoice.state == \"Overpaid\", \"Invalid state\");\n\n    payable(invoice.payer).transfer(invoice.amount);\n    invoice.state = \"Refunded\";\n}\n```\n\n---\n\n### **Escrow Wallet**\n\n#### **Key Features**\n1. **Deterministic Address Generation:**  \n   Unique wallet addresses for each invoice, derived securely from an admin-defined key.\n   \n2. **Admin Configuration:**  \n   Flexible wallet configuration for ease of maintenance.\n\n**Planned Enhancements (Phase 2):**\n- zk-rollups for improved transaction efficiency and lower gas costs.\n\n---\n\n### **Notifications**\n\n1. **Phase 2:**  \n   Notifications sent via Marketplace Oracles for dispute updates and state changes.\n\n2. **Phase 3:**  \n   Wallet-based notifications for real-time updates, such as payment confirmations and dispute outcomes.\n\n---\n\n### **Website**\n\n#### **Core Pages**\n1. **Landing Page:**  \n   Overview, WalletConnect login, and GitHub link.\n\n2. **Pay Invoice Page:**  \n   Displays invoice details (requires login to view payment address).\n\n3. **Invoice List:**  \n   Searchable and sortable interface for status, creation date, and payer/creator ID.\n\n4. **Admin Dashboard:**  \n   Controls for oracles, wallets, and system configuration.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftexora%2Fblockhead-documentation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftexora%2Fblockhead-documentation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftexora%2Fblockhead-documentation/lists"}