@claritydao/midnight-agora-sdk 0.1.0

package/src/validators.ts

@@ -0,0 +1,245 @@
+/**
+ * Validation utilities for the Agora DAO Governor SDK.
+ *
+ * @module validators
+ */
+
+import { InvalidParameterError, InvalidConfigurationError } from "./errors";
+import type {
+  GovernanceConfig,
+  GovernorConfig,
+  DeploymentConfig,
+  TokenConfig
+} from "./types";
+import { VoteChoice } from "./types";
+
+// Constants for validation limits
+const MAX_TITLE_LENGTH = 256;
+const MAX_DESCRIPTION_LENGTH = 10000;
+const MAX_TOKEN_NAME_LENGTH = 64;
+const MAX_TOKEN_SYMBOL_LENGTH = 16;
+const MAX_TOKEN_DECIMALS = 18n;
+const MIN_VOTING_PERIOD = 60n;
+
+/**
+ * Validates that a value is a non-empty string.
+ */
+export function validateNonEmptyString(
+  value: string,
+  parameterName: string
+): void {
+  if (typeof value !== "string") {
+    throw new InvalidParameterError(parameterName, "must be a string");
+  }
+  if (value.trim().length === 0) {
+    throw new InvalidParameterError(parameterName, "cannot be empty");
+  }
+}
+
+/**
+ * Validates that a string does not exceed a maximum length.
+ */
+export function validateMaxLength(
+  value: string,
+  maxLength: number,
+  parameterName: string
+): void {
+  if (value.length > maxLength) {
+    throw new InvalidParameterError(
+      parameterName,
+      `cannot exceed ${maxLength} characters (got ${value.length})`
+    );
+  }
+}
+
+/**
+ * Validates that a value is a valid Uint8Array address (32 bytes).
+ */
+export function validateAddress(
+  address: Uint8Array,
+  parameterName: string
+): void {
+  if (!(address instanceof Uint8Array)) {
+    throw new InvalidParameterError(parameterName, "must be a Uint8Array");
+  }
+  if (address.length !== 32) {
+    throw new InvalidParameterError(
+      parameterName,
+      `must be exactly 32 bytes (got ${address.length})`
+    );
+  }
+}
+
+/**
+ * Validates that a bigint is positive.
+ */
+export function validatePositiveBigInt(
+  value: bigint,
+  parameterName: string
+): void {
+  if (typeof value !== "bigint") {
+    throw new InvalidParameterError(parameterName, "must be a bigint");
+  }
+  if (value <= 0n) {
+    throw new InvalidParameterError(parameterName, "must be greater than 0");
+  }
+}
+
+/**
+ * Validates that a bigint is non-negative.
+ */
+export function validateNonNegativeBigInt(
+  value: bigint,
+  parameterName: string
+): void {
+  if (typeof value !== "bigint") {
+    throw new InvalidParameterError(parameterName, "must be a bigint");
+  }
+  if (value < 0n) {
+    throw new InvalidParameterError(parameterName, "cannot be negative");
+  }
+}
+
+/**
+ * Validates a vote choice value.
+ */
+export function validateVoteChoice(choice: VoteChoice): void {
+  if (
+    ![VoteChoice.For, VoteChoice.Against, VoteChoice.Abstain].includes(choice)
+  ) {
+    throw new InvalidParameterError(
+      "choice",
+      "must be VoteChoice.For, VoteChoice.Against, or VoteChoice.Abstain"
+    );
+  }
+}
+
+/**
+ * Validates proposal parameters.
+ */
+export function validateProposal(
+  title: string,
+  description: string,
+  creator: Uint8Array
+): void {
+  validateNonEmptyString(title, "title");
+  validateMaxLength(title, MAX_TITLE_LENGTH, "title");
+
+  validateNonEmptyString(description, "description");
+  validateMaxLength(description, MAX_DESCRIPTION_LENGTH, "description");
+
+  validateAddress(creator, "creator");
+}
+
+/**
+ * Validates governance configuration.
+ */
+export function validateGovernanceConfig(config: GovernanceConfig): void {
+  validatePositiveBigInt(config.votingPeriod, "votingPeriod");
+  validatePositiveBigInt(config.quorumThreshold, "quorumThreshold");
+  validatePositiveBigInt(config.proposalThreshold, "proposalThreshold");
+  validatePositiveBigInt(config.proposalLifetime, "proposalLifetime");
+  validateNonNegativeBigInt(config.executionDelay, "executionDelay");
+  validateNonNegativeBigInt(config.gracePeriod, "gracePeriod");
+  validatePositiveBigInt(config.minStakeAmount, "minStakeAmount");
+  validateNonNegativeBigInt(config.stakingPeriod, "stakingPeriod");
+
+  // Logical validations
+  if (config.votingPeriod < MIN_VOTING_PERIOD) {
+    throw new InvalidConfigurationError(
+      `votingPeriod must be at least ${MIN_VOTING_PERIOD} seconds`
+    );
+  }
+
+  if (config.proposalThreshold > config.quorumThreshold) {
+    throw new InvalidConfigurationError(
+      "proposalThreshold cannot exceed quorumThreshold"
+    );
+  }
+}
+
+/**
+ * Validates governor configuration.
+ */
+export function validateGovernorConfig(config: GovernorConfig): void {
+  validateGovernanceConfig(config.governance);
+
+  validateNonNegativeBigInt(config.executionDelay, "executionDelay");
+  validateNonNegativeBigInt(config.gracePeriod, "gracePeriod");
+  validatePositiveBigInt(config.maxActiveProposals, "maxActiveProposals");
+  validatePositiveBigInt(config.proposalLifetime, "proposalLifetime");
+
+  if (typeof config.emergencyVetoEnabled !== "boolean") {
+    throw new InvalidParameterError(
+      "emergencyVetoEnabled",
+      "must be a boolean"
+    );
+  }
+
+  if (config.emergencyVetoEnabled) {
+    validatePositiveBigInt(
+      config.emergencyVetoThreshold,
+      "emergencyVetoThreshold"
+    );
+  }
+
+  // Check consistency
+  if (config.executionDelay !== config.governance.executionDelay) {
+    throw new InvalidConfigurationError(
+      "executionDelay must match governance.executionDelay"
+    );
+  }
+
+  if (config.gracePeriod !== config.governance.gracePeriod) {
+    throw new InvalidConfigurationError(
+      "gracePeriod must match governance.gracePeriod"
+    );
+  }
+
+  if (config.proposalLifetime !== config.governance.proposalLifetime) {
+    throw new InvalidConfigurationError(
+      "proposalLifetime must match governance.proposalLifetime"
+    );
+  }
+}
+
+/**
+ * Validates token configuration.
+ */
+export function validateTokenConfig(config: TokenConfig): void {
+  validateNonEmptyString(config.name, "token.name");
+  validateMaxLength(config.name, MAX_TOKEN_NAME_LENGTH, "token.name");
+
+  validateNonEmptyString(config.symbol, "token.symbol");
+  validateMaxLength(config.symbol, MAX_TOKEN_SYMBOL_LENGTH, "token.symbol");
+
+  validatePositiveBigInt(config.decimals, "token.decimals");
+
+  if (config.decimals > MAX_TOKEN_DECIMALS) {
+    throw new InvalidConfigurationError(
+      `token.decimals cannot exceed ${MAX_TOKEN_DECIMALS}`
+    );
+  }
+}
+
+/**
+ * Validates complete deployment configuration.
+ */
+export function validateDeploymentConfig(config: DeploymentConfig): void {
+  validateGovernorConfig(config.governor);
+  validateTokenConfig(config.token);
+  validateAddress(config.adminKey, "adminKey");
+
+  // Security check: warn about predictable admin keys
+  const allZeros = config.adminKey.every((byte) => byte === 0);
+  const allOnes = config.adminKey.every((byte) => byte === 1);
+  const sequential =
+    config.adminKey[0] === 1 &&
+    config.adminKey.slice(1).every((byte) => byte === 0);
+
+  if (allZeros || allOnes || sequential) {
+    console.warn(
+      "WARNING: adminKey appears to be predictable. Use cryptographically secure random bytes in production."
+    );
+  }
+}

package/test/README.md

@@ -0,0 +1,409 @@
+# SDK Test Suite
+
+Comprehensive test suite for the Agora DAO Midnight SDK.
+
+## Overview
+
+The test suite validates the SDK's functionality across multiple layers:
+- Type definitions and enums
+- Input validators
+- Error classes
+- Utility functions
+- WASM initialization
+- Integration tests with mocked providers
+
+## Test Structure
+
+```
+test/
+├── types.test.ts              # Type system tests (8 tests)
+├── validators.test.ts         # Input validation tests (31 tests)
+├── errors.test.ts             # Error class tests (14 tests)
+├── utils.test.ts              # Utility function tests (14 tests)
+├── wasm-init.test.ts          # WASM loading tests (5 tests)
+├── integration/
+│   └── governor-api.test.ts   # Integration tests (31 tests)
+└── mocks/
+    └── providers.ts           # Mock provider factories
+```
+
+## Running Tests
+
+### Run All Tests
+```bash
+pnpm test
+```
+
+### Watch Mode
+```bash
+pnpm test --watch
+```
+
+### Run Specific Test File
+```bash
+pnpm test types.test.ts
+pnpm test integration/governor-api.test.ts
+```
+
+### Coverage
+```bash
+pnpm test --coverage
+```
+
+## Test Categories
+
+### 1. Type System Tests (`types.test.ts`)
+
+Tests the core type definitions and enums:
+
+- **VoteChoice Enum**: Validates For, Against, Abstain values
+- **ProposalStatus Enum**: Validates all 8 proposal states
+- **ConfigPresets**: Tests production() and testing() configurations
+- **Type Exports**: Ensures all types are properly exported
+
+**Key Tests:**
+- VoteChoice enum values (0, 1, 2)
+- ProposalStatus enum completeness
+- ConfigPresets have correct values
+- Production config has higher thresholds than testing
+
+### 2. Validator Tests (`validators.test.ts`)
+
+Tests input validation for all public SDK methods:
+
+**Coverage:**
+- `validateDeploymentConfig()`: Token config, governance config, admin key
+- `validateProposal()`: Title, description, creator validation
+- `validateVoteChoice()`: Enum validation
+- `validateStakeAmount()`: BigInt validation
+- `validateAddress()`: Uint8Array length validation
+- `validateProposalId()`: BigInt validation
+
+**Edge Cases:**
+- Empty strings
+- Maximum length limits
+- Invalid enum values
+- Incorrect array lengths
+- Negative values
+
+### 3. Error Class Tests (`errors.test.ts`)
+
+Tests custom error classes:
+
+**Error Types:**
+- `GovernorSDKError`: Base error
+- `WalletNotConnectedError`: Wallet state errors
+- `InsufficientStakeError`: Stake validation errors
+- `InvalidParameterError`: Input validation errors
+- `ContractNotFoundError`: Contract lookup errors
+- `ProposalNotFoundError`: Proposal lookup errors
+- `TransactionError`: Transaction submission errors
+- `DeploymentError`: Contract deployment errors
+- `InvalidConfigurationError`: Configuration errors
+- `NetworkNotConfiguredError`: Network setup errors
+
+**Validation:**
+- Correct error names
+- Proper message formatting
+- Error inheritance
+- Parameter validation in constructors
+
+### 4. Utility Function Tests (`utils.test.ts`)
+
+Tests utility functions:
+
+**Functions Tested:**
+- `randomBytes()`: Cryptographically secure random generation
+- `bytesToHex()`: Binary to hex string conversion
+- `hexToBytes()`: Hex string to binary conversion
+- `addressToBytes()`: Midnight address parsing
+
+**Key Tests:**
+- Random bytes are non-zero and different each call
+- Hex conversion is reversible
+- Address parsing handles prefixes
+- Edge cases (empty arrays, 0x prefix)
+
+### 5. WASM Initialization Tests (`wasm-init.test.ts`)
+
+Tests WASM module loading behavior:
+
+**Critical Tests:**
+- SDK imports without triggering immediate WASM load
+- WASM modules load only when needed
+- No `ocrt.maxField is not a function` errors
+- Proper lazy loading behavior
+
+**Why This Matters:**
+The SDK uses WASM modules from `@midnight-ntwrk/compact-runtime`. These tests ensure:
+- No top-level WASM execution during import
+- Vite can bundle the SDK correctly
+- Browser compatibility is maintained
+
+### 6. Integration Tests (`integration/governor-api.test.ts`)
+
+Tests SDK logic with mocked providers (no real blockchain):
+
+**Test Categories:**
+
+#### Provider Interaction (8 tests)
+- Public data provider queries contract state
+- Wallet provider submits transactions
+- Transaction failure handling
+- Proof provider generates ZK proofs
+- Block height queries
+- Private state save/retrieve
+- Network queries
+- Transaction balancing
+
+#### Configuration Validation
+- Valid deployment config accepted
+- Invalid deployment config rejected
+- Admin key length validation
+
+#### Vote Choice Validation
+- Valid vote choices (For, Against, Abstain)
+- Invalid vote choices rejected
+
+#### Proposal Validation
+- Valid proposals accepted
+- Empty titles rejected
+- Title length limits enforced
+- Empty descriptions rejected
+
+#### Transaction Flow
+- Transaction balancing
+- Transaction submission
+- Error handling
+
+#### Private State Management
+- State retrieval
+- State saving
+- State persistence
+
+#### Block Height Queries
+- Current block height queries
+
+#### Error Handling Scenarios
+- Wallet connection errors
+- Indexer query errors
+- Proof generation errors
+
+#### Wallet State
+- Wallet state retrieval
+- Address, coinPublicKey, encryptionPublicKey
+
+#### Configuration Presets
+- Testing configuration values
+- Production configuration values
+- Production has higher thresholds than testing
+
+## Mock Providers
+
+The test suite uses mock providers to simulate blockchain interactions:
+
+### `createMockProviders()`
+
+Creates a complete mock provider set with default successful responses:
+
+```typescript
+const mockProviders = createMockProviders();
+// All operations succeed
+```
+
+### `createFailingMockProviders()`
+
+Creates providers that simulate transaction failures:
+
+```typescript
+const failingProviders = createFailingMockProviders();
+// submitTransaction() throws error
+```
+
+### `createInsufficientStakeMockProviders()`
+
+Creates providers with insufficient stake scenarios:
+
+```typescript
+const insufficientStakeProviders = createInsufficientStakeMockProviders();
+// User has stake < minStakeAmount
+```
+
+### Custom Overrides
+
+Override specific provider behavior:
+
+```typescript
+const customProviders = createMockProviders({
+  publicDataProvider: {
+    queryContractState: vi.fn().mockResolvedValue(customState),
+  },
+});
+```
+
+## Test Execution Strategy
+
+### Unit Tests
+Fast, isolated tests for individual functions:
+- Type definitions
+- Validators
+- Error classes
+- Utility functions
+
+### Integration Tests
+Tests SDK logic with mocked providers:
+- No real blockchain connection
+- No proof generation
+- Fast execution (< 100ms)
+- Suitable for CI/CD
+
+### E2E Tests (Not Included)
+For complete end-to-end testing:
+- Use real testnet
+- Real Lace wallet
+- Real proof generation
+- Slow execution (minutes)
+- Manual testing recommended
+
+## Common Issues
+
+### Issue: "Cannot find module '@agora-dao-midnight/sdk'"
+
+**Solution:** Build the SDK first:
+```bash
+cd /path/to/sdk
+pnpm run build
+```
+
+### Issue: "ocrt.maxField is not a function"
+
+**Solution:** This should not happen in tests. If it does:
+1. Check that WASM modules are properly mocked
+2. Verify `wasm-init.test.ts` is passing
+3. Ensure no eager WASM loading in imports
+
+### Issue: Tests timing out
+
+**Solution:**
+- Check if using real providers instead of mocks
+- Increase Vitest timeout in test file
+- Verify no network calls in unit tests
+
+## Test Coverage Goals
+
+Current coverage: **103 tests passing**
+
+Target coverage:
+- Types: 100%
+- Validators: 100%
+- Errors: 100%
+- Utils: 100%
+- WASM Init: 100%
+- Integration: 80%+ (critical paths)
+
+## Writing New Tests
+
+### Unit Test Template
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { functionToTest } from '../src/module';
+
+describe('Module Name', () => {
+  describe('functionToTest', () => {
+    it('should handle valid input', () => {
+      const result = functionToTest(validInput);
+      expect(result).toBe(expectedValue);
+    });
+
+    it('should throw on invalid input', () => {
+      expect(() => functionToTest(invalidInput)).toThrow();
+    });
+  });
+});
+```
+
+### Integration Test Template
+
+```typescript
+import { describe, it, expect, beforeEach } from 'vitest';
+import { createMockProviders } from '../mocks/providers';
+import { GovernorAPI } from '../../src/governor-api';
+
+describe('GovernorAPI Feature', () => {
+  let mockProviders: GovernorProviders;
+
+  beforeEach(() => {
+    mockProviders = createMockProviders();
+  });
+
+  it('should perform operation', async () => {
+    const result = await governorAPI.operation(params);
+    expect(result).toBeDefined();
+  });
+});
+```
+
+## Best Practices
+
+1. **Use Mocks for Integration Tests**: Never hit real blockchain in tests
+2. **Test Edge Cases**: Empty strings, max lengths, invalid types
+3. **Test Error Paths**: Ensure errors are thrown correctly
+4. **Keep Tests Fast**: Unit tests < 5ms, integration tests < 100ms
+5. **Clear Test Names**: Describe what the test validates
+6. **Arrange-Act-Assert**: Structure tests clearly
+7. **Don't Test Implementation Details**: Test behavior, not internals
+
+## CI/CD Integration
+
+The test suite is designed to run in continuous integration:
+
+```yaml
+# GitHub Actions example
+- name: Run tests
+  run: pnpm test
+
+- name: Check coverage
+  run: pnpm test --coverage
+```
+
+All tests should pass before merging to main.
+
+## Future Test Additions
+
+Planned test coverage:
+
+1. **Contract Interaction Tests**: Test actual contract method calls with mocked blockchain
+2. **State Management Tests**: Comprehensive private state tests
+3. **Transaction Building Tests**: Test transaction construction
+4. **ZK Witness Tests**: Test witness preparation
+5. **Performance Tests**: Benchmark critical operations
+
+## Troubleshooting
+
+### Tests Fail After SDK Changes
+
+1. Rebuild the SDK: `pnpm run build`
+2. Clear test cache: `rm -rf node_modules/.vite`
+3. Reinstall: `pnpm install`
+4. Run tests: `pnpm test`
+
+### Mock Provider Issues
+
+If mock providers aren't working:
+1. Check `test/mocks/providers.ts`
+2. Verify Vitest mock functions are used: `vi.fn()`
+3. Ensure proper async/await in tests
+
+### Type Errors in Tests
+
+1. Rebuild SDK types: `pnpm run build`
+2. Check test imports match SDK exports
+3. Verify TypeScript version compatibility
+
+## Contact
+
+For test-related issues:
+- Check test output for specific error messages
+- Review this README for common solutions
+- Check main SDK README for build instructions