diff --git a/README.md b/README.md index cc00505..a82a61c 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ +# Lean Gas-Optimized Ledger with Batching + This project implements a lean gas-optimized ledger with batching capabilities. Key concepts: @@ -9,3 +11,50 @@ How to use: - Deploy the contract - Call batchMint with recipients and amounts, passing the current nonce for your address +Usage (Hardhat-focused) +- Prerequisites + - Node.js and npm/yarn installed + - A Hardhat project setup in this repository (hardhat.config.js, etc.) + +- Install dependencies + - npm install + - or yarn install + +- Compile + - npx hardhat compile + +- Test + - npx hardhat test + +- Deploy (local Hardhat node) + - Start a local node: npx hardhat node + - Deploy using a script (scripts/deploy.js) + - Run deployment: npx hardhat run scripts/deploy.js --network localhost + +- Interact (example) + - Run a batch mint via a script (scripts/batchMint.js) or via a Hardhat console/script + - Ensure you pass the current nonce for your address to enable replay resistance + +- Notes + - Replace network names and addresses as appropriate for your environment (localhost, testnet, mainnet) + - Use deterministic nonces on the caller side to enable replay-resistant batch minting + +Design Notes +- Gas considerations + - Batch minting aggregates multiple mints into a single transaction, reducing per-transfer calldata and associated framing overhead. + - Deterministic nonce sequencing per caller helps avoid gas-heavy replay vectors and reduces the need for excessive on-chain state changes to enforce replay protection. + - Storage layout is kept simple to minimize SLOAD/SSTORE costs; consider packing related state and avoiding unnecessary storage writes. + - Use of events for batch operations can provide cheaper off-chain tracking vs. on-chain reads, depending on the workflow. + - calldata arrays for recipients and amounts minimize copy cost into memory during contract calls. + - Where possible, avoid looping with unbounded iterations in state-changing paths; prefer bounded batch sizes or internal batching strategies. + - Access control is kept minimal (owner-only) to reduce complexity and potential gas overhead from permission checks on frequent paths. + - Nonce validation is designed to be a light pre-check before minting to reduce wasted gas on invalid attempts. + - If extending with additional batch types, consider offering a capped batch size or a two-step nonce verification to balance UX and gas. + +Example workflow (conceptual) +- Prepare two arrays: recipients[] and amounts[] for the batch. +- Retrieve current nonce for the caller (off-chain or via a view). +- Call batchMint(recipients, amounts, nonce) in a single transaction. +- Emit a BatchMint event with batch details for off-chain indexing. + +If you’d like, I can tailor the \ No newline at end of file diff --git a/docs/RELEASE_NOTES.md b/docs/RELEASE_NOTES.md new file mode 100644 index 0000000..4d700c2 --- /dev/null +++ b/docs/RELEASE_NOTES.md @@ -0,0 +1,13 @@ +# Release notes (DX improvement) + +This update adds a lightweight, non-intrusive documentation note describing a suggested emergency withdrawal pattern for the Gas Opt Ledger contract. While not changing contract logic in this patch, it outlines how an emergencyWithdraw function could be implemented in a future iteration, including security notes and access controls. + +Key topics: +- Intent: provide a safe path to recover assets from the contract in edge cases (e.g., stuck funds). +- Suggested contract shape: a function callable by the owner to transfer Ether from the contract to a trusted recipient. +- Security considerations: validate non-zero recipient, check contract balance, and report via an event. + +Next steps (for the next patch): +- Implement emergencyWithdraw in GasOptLedger.sol (with onlyOwner access control). +- Add tests to cover success and failure paths (insufficient balance, zero address, reentrancy safety). +- Document how this interacts with Pause/Guarded states. diff --git a/docs/SECURITY_TIPS.md b/docs/SECURITY_TIPS.md new file mode 100644 index 0000000..f184c33 --- /dev/null +++ b/docs/SECURITY_TIPS.md @@ -0,0 +1,23 @@ +# Security tips for GasOptLedger project + +This document outlines lightweight, incremental improvements you can apply to tighten security without large refactors. + +- Enforce strict access controls on admin-only operations: + - Ensure that only the contract owner or designated admin can call sensitive functions (e.g., pause, emergencyWithdraw, configuration changes). + - Prefer Ownable patterns or a dedicated AccessControl role for granular permissions. +- Enable pause capability where appropriate: + - If the contract supports a pause/unpause mechanism (via OwnablePause or a custom Pausable pattern), ensure all critical state-changing operations check the paused state. +- Guard external interactions: + - Limit external calls to trusted addresses or implement reentrancy guards for functions that modify ETH/token balances. +- Validate inputs early: + - Use require statements to validate inputs and state assumptions (non-zero addresses, non-zero amounts, valid array lengths). +- Avoid gas-tuning side effects in public functions: + - Do not rely on gas price or block state for critical logic; keep such behavior off-chain or behind a clear admin interface. +- Testing and audits: + - Extend tests to cover access control and pause behavior, including edge cases (paused state, zero addresses, reentrant calls). + - Add a small regression test that ensures only authorized accounts can call sensitive functions. +- Deployment hygiene: + - Explicitly set admin addresses during deployment and document the expected roles in deployment scripts. + - Keep environment-specific configurations out of on-chain logic. + +This file is intentionally lightweight to keep changes focused and low-risk while improving overall contract security posture. Implementations may vary depending on how OwnablePause and access control are wired in your contracts; adapt checks to align with your existing patterns.