diff --git a/docs/LabContract.md b/docs/LabContract.md new file mode 100644 index 000000000..e62b4888a --- /dev/null +++ b/docs/LabContract.md @@ -0,0 +1,77 @@ +## Overview +`LabContract` is a sophisticated smart contract designed to manage scientific experiments on the blockchain. It provides a robust framework for creating, tracking, and managing experimental configurations with integrated funding and status tracking mechanisms. + +## Interface +| Function | Parameters | Returns | Description | +|----------|------------|---------|-------------| +| `createExperiment` | `fundingAmount`, `configHash` | `bytes32` | Create a new experiment with initial funding | +| `updateExperimentStatus` | `experimentId`, `newStatus` | `void` | Toggle experiment active status | +| `getExperimentDetails` | `experimentId` | `ExperimentConfig` | Retrieve full experiment configuration | +| `withdrawFunds` | `experimentId`, `amount` | `void` | Withdraw funds from an active experiment | + +## Events +- `ExperimentCreated`: Emitted when a new experiment is initialized + - `experimentId`: Unique identifier + - `creator`: Experiment creator's address + - `fundingAmount`: Initial funding amount + +- `ExperimentUpdated`: Emitted when experiment status changes + - `experimentId`: Unique identifier + - `isActive`: New active status + +## Storage Layout +- `experiments`: Mapping of experiment IDs to `ExperimentConfig` +- `creatorExperiments`: Mapping tracking experiments per creator +- `ExperimentConfig` struct contains: + - `creator`: Experiment initiator + - `startTimestamp`: Experiment creation time + - `fundingAmount`: Available experiment funds + - `isActive`: Current experiment status + - `configHash`: Experiment configuration identifier + +## Access Control +- Uses OpenZeppelin's `Ownable` for contract-level administration +- Experiment creators have exclusive rights to: + - Update experiment status + - Withdraw experiment funds + +## Security Considerations +- `nonReentrant` modifier prevents recursive calls +- Strict access controls on critical functions +- Validates input parameters +- Checks experiment creator before allowing modifications +- Requires positive funding amounts +- Validates experiment existence before operations + +## Deployment +### ChunkNet Deployment Parameters +- **RPC URL**: https://rpc.chunknet.org +- **Chain ID**: 214562 +- **Required Constructor Parameters**: + 1. `_registryAddress`: LabRegistry contract address + 2. `_helperAddress`: LabHelper contract address + +### Deployment Script Example +bash +forge create LabContract \ + --rpc-url https://rpc.chunknet.org \ + --constructor-args $LAB_REGISTRY_ADDRESS $LAB_HELPER_ADDRESS + + +## Testing +### Recommended Test Scenarios +- Experiment creation with valid parameters +- Status update permissions +- Fund withdrawal mechanics +- Edge case handling: + - Zero funding amount + - Invalid experiment ID + - Unauthorized status modifications +- Verify event emissions +- Validate access control mechanisms + +### Test Coverage +- Unit tests for each function +- Integration tests with registry interactions +- Fuzz testing for input validation +- Simulation of various experiment lifecycle stages \ No newline at end of file