{"id":48716781,"url":"https://github.com/envoy1084/kora","last_synced_at":"2026-04-11T17:30:32.682Z","repository":{"id":311523575,"uuid":"1040610424","full_name":"envoy1084/kora","owner":"envoy1084","description":"A privacy-preserving Dollar Cost Averaging (DCA) using Zama Confidential Protocol","archived":false,"fork":false,"pushed_at":"2025-11-19T20:46:34.000Z","size":1403,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-22T15:24:12.303Z","etag":null,"topics":["dca","dca-bot","fhevm","web3","zama"],"latest_commit_sha":null,"homepage":"https://kora-dca.vercel.app","language":"TypeScript","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/envoy1084.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-19T08:38:59.000Z","updated_at":"2025-11-19T20:45:22.000Z","dependencies_parsed_at":"2025-08-25T03:13:10.268Z","dependency_job_id":"45b4ec15-64c4-4582-9e02-4e7c6067c02b","html_url":"https://github.com/envoy1084/kora","commit_stats":null,"previous_names":["envoy-vc/kora","envoy1084/kora"],"tags_count":null,"template":false,"template_full_name":"envoy1084/turbo-fullstack-starter","purl":"pkg:github/envoy1084/kora","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/envoy1084%2Fkora","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/envoy1084%2Fkora/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/envoy1084%2Fkora/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/envoy1084%2Fkora/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/envoy1084","download_url":"https://codeload.github.com/envoy1084/kora/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/envoy1084%2Fkora/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31689752,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-11T13:07:20.380Z","status":"ssl_error","status_checked_at":"2026-04-11T13:06:47.903Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":["dca","dca-bot","fhevm","web3","zama"],"created_at":"2026-04-11T17:30:32.101Z","updated_at":"2026-04-11T17:30:32.670Z","avatar_url":"https://github.com/envoy1084.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kora Protocol: Privacy-Preserving DCA Bot with Transaction Batching\n\n## Table of Contents\n1. [Overview](#overview)\n2. [Architecture](#architecture)\n3. [WorkFlow](#workflow)\n4. [Hook System Architecture](#hook-system-architecture)\n5. [Deployments](#deployments)\n6. [Testing](#testing)\n7. [Future Enhancements](#future-enhancements)\n\n## Overview\n\nKora is a privacy-preserving Dollar Cost Averaging (DCA) bot that leverages Fully Homomorphic Encryption (FHE) and the Zama Confidential Blockchain Protocol to execute automated investment strategies while maintaining complete user privacy. The protocol aggregates encrypted DCA intents from multiple users, executes batched swaps on decentralized exchanges, and distributes purchased tokens proportionally without revealing individual investment amounts or strategies.\n\n### Key Features\n- **Privacy-Preserving**: All user parameters and amounts remain encrypted throughout the entire process\n- **Batched Execution**: Aggregates multiple user intents into single transactions for gas efficiency\n- **Hook-Based Strategy System**: Modular, extensible strategy framework with customizable conditions\n- **FHE Integration**: Leverages Zama's FHE implementation for encrypted computations\n- **Automated DCA**: Executes strategies based on time, frequency, and dynamic market conditions\n\n## Architecture\n\nThe protocol is built on Zama's Confidential Blockchain using Fully Homomorphic Encryption (FHE) to enable private computations on encrypted data. The system comprises four main components:\n\n- **KoraExecutor**: The central smart contract that orchestrates strategy management, batch processing, and swap execution. It handles encrypted operations through FHEVM library integration and manages the complete workflow from intent collection to token distribution.\n- **Encrypted ERC20 Tokens**: Privacy-preserving token implementations that extend standard ERC20 functionality with FHE capabilities. These tokens (e.g., eWETH, eUSDC) maintain encrypted balances and support encrypted transfers while interfacing with underlying standard tokens for DEX interactions.\n- **Hook System**: Modular conditional validators that enforce strategy parameters without revealing them. Each hook implements a specific validation rule through standardized interfaces, allowing strategy composition without modifying the core protocol.\n\n### Technical Implementation Details\n\n#### Strategy Management\n\nUsers create strategies by combining multiple hooks with encrypted parameters. Each strategy receives a unique identifier computed as `keccak256(user, token0, token1, salt)`, ensuring deterministic addressing while preserving privacy. Strategies store only public addresses and encrypted state, with all sensitive data maintained within hooks.\n\n#### Batch Processing Mechanism\n\nThe system collects encrypted intents from multiple users and processes them in batches of up to 64 transactions. The batching operates through two-phase execution:\n\n- Phase 1 - Encrypted Processing:\n    - Validates intents against strategy hooks using FHE operations\n    - Aggregates encrypted swap amounts using homomorphic addition\n    - Packages pre-hook results into packed boolean arrays for efficient decryption\n- Phase 2 - Decrypted Execution:\n    - Receives decrypted totals from FHE oracle after signature verification\n    - Executes single aggregated swap on Uniswap V2\n    - Calculates proportional distributions using encrypted arithmetic\n    - Distributes output tokens back to users based on their contribution percentages\n\n#### Hook Architecture\n\nHooks implement the ISwapHook interface with three functions:\n\n- `initialize()`: Sets up encrypted strategy parameters\n- `preSwap()`: Validates intents against strategy rules using FHE comparisons\n- `postSwap()`: Updates encrypted state after successful executions\n\nStandard hooks include:\n\n1. `BudgetHook`: Enforces maximum total expenditure with FHE.le(spent + amount, budget)\n2. `PurchaseAmountHook`: Validates per-transaction limits\n3. `TimeframeHook`: Checks timestamp validity using encrypted time comparisons\n4. `FrequencyHook`: Ensures minimum intervals between executions\n\n## Workflow\n\n### Strategy Creation Phase\n\n```mermaid\nsequenceDiagram\n    participant U as User\n    participant K as KoraExecutor\n    participant H as Hook Contracts\n\n    U-\u003e\u003eU: Generate encrypted strategy parameters\n    U-\u003e\u003eK: createStrategy(user, hooks, salt)\n    K-\u003e\u003eK: Compute strategyId = keccak256(user, token0, token1, salt)\n    K-\u003e\u003eK: Validate hook addresses\n    loop For each hook\n        K-\u003e\u003eH: initialize(strategyId, hookData)\n        H--\u003e\u003eK: Hook initialized\n    end\n    K-\u003e\u003eK: Store strategy mapping\n    K--\u003e\u003eU: StrategyCreated event\n```\n\nUsers create customized DCA strategies by specifying encrypted parameters through hook contracts:\n\n- `BudgetHook`: Sets maximum total spendable amount\n- `PurchaseAmountHook`: Defines maximum per-transaction amount\n- `TimeframeHook`: Sets strategy expiration time\n- `FrequencyHook`: Controls execution intervals\n- `DynamicConditionHook`: Optional conditions like \"buy the dip\"\n\nEach strategy receives a unique strategyId computed as `keccak256(user, token0, token1, salt)`, ensuring deterministic addressing.\n\n### Intent Submission and Batching\n\n```mermaid\nsequenceDiagram\n    participant U as User\n    participant K as KoraExecutor\n    participant H as Hook Contracts\n    participant T as EncryptedToken\n\n    U-\u003e\u003eU: Encrypt amount0 with inputProof\n    U-\u003e\u003eK: executeBatch([intents])\n    K-\u003e\u003eK: Validate batch size ≤ MAX_BATCH_SIZE\n    loop For each intent\n        K-\u003e\u003eK: Validate strategy exists\n        K-\u003e\u003eH: Run preSwap hooks\n        H--\u003e\u003eK: ebool result\n        K-\u003e\u003eT: pullIn(user, amount0)\n        T--\u003e\u003eK: Transfer success/failure\n        K-\u003e\u003eK: Aggregate encrypted amounts\n    end\n    K-\u003e\u003eK: Pack pre-hook results\n    K-\u003e\u003eFHE: requestDecryption(cts, callback)\n    FHE--\u003e\u003eK: requestId\n    K-\u003e\u003eK: Store batch information\n    K--\u003e\u003eU: BatchRequested event\n```\n\nUsers submit encrypted trading intents containing:\n\n- amount0: Encrypted amount of token0 to swap\n- inputProof: Zero-knowledge proof of valid encryption\n- intentId: Unique identifier for the intent\n- strategyId: Reference to user's strategy\n\nThe batch mechanism:\n\n1. Collects up to 64 intents (MAX_BATCH_SIZE)\n2. Validates each against strategy hooks\n3. Aggregates encrypted amounts using FHE operations\n4. Packages hooks results (`ebools`) into single packed `euint64` for single decryption\n5. Requests decryption from FHE oracle\n\n### Batch Execution Phase\n\n```mermaid\nsequenceDiagram\n    participant FHE as FHE Oracle\n    participant K as KoraExecutor\n    participant U as Uniswap V2\n    participant T0 as Token0\n    participant T1 as Token1\n    participant H as Hook Contracts\n\n    FHE-\u003e\u003eK: decryptionCallback(requestId, totalIn, packedChecks, signatures)\n    K-\u003e\u003eK: Verify oracle signatures\n    K-\u003e\u003eK: Validate batch state\n    K-\u003e\u003eT0: withdraw(totalIn)\n    K-\u003e\u003eU: swapExactTokensForTokens(totalIn, 0)\n    U-\u003e\u003eT0: transferFrom(KoraExecutor, totalIn)\n    U-\u003e\u003eT1: transfer(KoraExecutor, amountOut)\n    K-\u003e\u003eT1: deposit(amountOut)\n    loop For each successful intent\n        K-\u003e\u003eK: Calculate proportional share\n        K-\u003e\u003eT1: transfer(user, intentAmountOut)\n        K-\u003e\u003eH: Execute postSwap hooks\n    end\n    K-\u003e\u003eK: Mark batch completed\n    K--\u003e\u003eK: BatchExecuted event\n```\n\nUpon receiving decrypted values from the FHE oracle:\n\n1. **Signature Verification**: Validates oracle responses\n2. **Token Preparation**: Withdraws underlying tokens for swapping\n3. **DEX Execution**: Executes single aggregated swap on Uniswap V2\n4. **Proportional Distribution**: Calculates and distributes output tokens using encrypted arithmetic\n5. **Post-Hook Execution**: Runs strategy completion hooks\n\n## Hook System Architecture\n\n### Hook Interface\n\n```solidity\ninterface ISwapHook {\n    function initialize(bytes32 strategyId, bytes memory data) external;\n    function preSwap(bytes32 strategyId, Intent calldata intent) external returns (ebool);\n    function postSwap(bytes32 strategyId, IntentResult memory result) external;\n}\n```\n\n#### Hook Types\n\n**Budget Hook (`BudgetHook.sol`)**\n- Manages total investment budget\n- Tracks remaining allocation\n- Prevents over-investment\n\n**Frequency Hook (`FrequencyHook.sol`)**\n- Controls purchase timing\n- Manages interval-based execution\n- Prevents too-frequent purchases\n\n**Purchase Amount Hook (`PurchaseAmountHook.sol`)**\n- Manages per-interval amounts\n- Implements dynamic amount adjustments\n- Handles market condition responses\n\n**Timeframe Hook (`TimeframeHook.sol`)**\n- Controls strategy duration\n- Manages start/end dates\n- Implements time-based constraints\n\n## Deployments\n\nKora has been deployed on Ethereum Sepolia Testnet.\n\n| Contract | Address |\n| --- | --- |\n| KoraExecutor | [0xf699607145CEeE364EA7BD82B656B6E167518bF5](https://sepolia.etherscan.io/address/0xf699607145CEeE364EA7BD82B656B6E167518bF5) |\n| USDC |[0x006fF8309C4384171EEA16a01d2fa3b63e1bD778](https://sepolia.etherscan.io/address/0x006fF8309C4384171EEA16a01d2fa3b63e1bD778)  |\n| WETH | [0xD2eAA8Cfa269F66b7604c28fA0cfE1062a969ED0](https://sepolia.etherscan.io/address/0xD2eAA8Cfa269F66b7604c28fA0cfE1062a969ED0) |\n| eUSDC | [0x89418DB22C3Cb32E3e33b1B83aC658fB0B8d6D34](https://sepolia.etherscan.io/address/0x89418DB22C3Cb32E3e33b1B83aC658fB0B8d6D34) |\n| eWETH | [0xEE029e11343551d52fab4a6513D1637D28e43Dc1](https://sepolia.etherscan.io/address/0xEE029e11343551d52fab4a6513D1637D28e43Dc1) |\n| BudgetHook | [0x90aB31A738f27994Fc911ccD55AeCDB630e75C0f](https://sepolia.etherscan.io/address/0x90aB31A738f27994Fc911ccD55AeCDB630e75C0f) |\n| PurchaseAmountHook | [0x2e46532420c18f4e39B822995F300AF40419287f](https://sepolia.etherscan.io/address/0x2e46532420c18f4e39B822995F300AF40419287f) |\n| TimeframeHook | [0x1d99E812B871111F21B4351cEbdd140573A6C93c](https://sepolia.etherscan.io/address/0x1d99E812B871111F21B4351cEbdd140573A6C93c) |\n| FrequencyHook | [0xBAc099d874fa5A66DD63ffeBb5e650bF85B216d3](https://sepolia.etherscan.io/address/0xBAc099d874fa5A66DD63ffeBb5e650bF85B216d3) |\n\n## Testing\n\n### 1. Test Structure\n\nThe test suite is organized into logical modules located in `packages/contracts/test`:\n\n```\n├── test\n│   ├── executor.test.ts\n│   ├── helpers\n│   │   ├── env.ts\n│   │   ├── index.ts\n│   │   └── uniswap.ts\n│   ├── hooks\n│   │   ├── budget.test.ts\n│   │   ├── frequency.test.ts\n│   │   ├── purchase-amount.test.ts\n│   │   └── timeframe.test.ts\n│   ├── libraries\n│   │   └── packed-bool.test.ts\n│   └── wrapped-token.test.ts\n```\n\n### 2. Test Coverage\n\n#### Integration Tests (`executor.test.ts`)\n- **Strategy Creation**: Test strategy creation and validation\n- **Intent Processing**: Test intent submission and validation\n- **Batch Execution**: Test batch formation and execution\n- **Hook Integration**: Test pre and post-swap hook execution\n- **Token Distribution**: Test proportional token distribution\n\n#### Hooks Tests (`test/hooks`)\n- **Budget Hook Tests**: Test Budget Hook functionality\n- **Frequency Hook Tests**: Test Frequency Hook functionality\n- **Purchase Amount Hook Tests**: Test Purchase Amount Hook functionality\n- **Timeframe Hook Tests**: Test Timeframe Hook functionality\n\n#### Unit Tests\n- **Library Tests**: Test utility libraries and helper functions\n- **Token Tests**: Test encrypted token functionality\n- **Hook Tests**: Test individual hook implementations\n\n#### Helper Functions\n- **Environment Setup**: Configure test environment and contracts\n- **Uniswap Integration**: Mock DEX operations for testing\n- **Test Utilities**: Common testing functions and assertions\n\n## Future Enhancements\n\n- **Larger Batch Sizes**: Implementation of dynamic batch sizing algorithms that automatically adjust based on network congestion and gas prices. \n- **Advanced Hook Types**: Development of more sophisticated hook patterns including:\n    - Oracle-Based Hooks: Integration with price oracles for conditional execution based on external market data\n    - Social Hooks: Strategy templates that can be shared and executed with parameter customization\n    - Cross-Strategy Hooks: Coordination between multiple strategies for complex portfolio rebalancing\n- **Intent Matching Engine**: Development of an off-chain intent matching system that optimizes batch composition based on strategy compatibility, reducing on-chain computation requirements.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fenvoy1084%2Fkora","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fenvoy1084%2Fkora","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fenvoy1084%2Fkora/lists"}