Tokens

.dockerignore

@@ -17,6 +17,14 @@ logs
 logs_*
 blocked_ips.json
 
+# Exclude local runtime state (may contain root-owned files / huge volumes)
+ipfs/data_*/
+ipfs_*/
+docker_data/
+logs/
+postgres/
+postgres_*/
+
 # Exclude unnecessary files
 *.log
 .DS_Store

.gitignore

@@ -170,4 +170,13 @@ src/GPATH
 src/GRTAGS
 src/GTAGS
 /docs/diagrams
-/.serena
+
+# ---- Tokens-branch specific ----
+documentation/Demos_ Technical Design Decisions.pdf
+documentation/demos_yp_v5.odt
+documentation/demos_yp_v5.pdf
+better_testing/runs/*
+!better_testing/runs/.gitkeep
+/documentation/tokens/AUDIT.md
+/documentation/tokens/TEAM.md
+/myc.json

.serena/memories/arch_hook_system.md

@@ -0,0 +1,191 @@
+# Hook System Architecture
+
+## Summary
+The hook system allows token scripts to extend native operations (transfer, mint, burn, approve) with custom logic. Hooks can validate, modify, or reject operations and add additional mutations.
+
+## Hook Types
+All 8 hook types are supported:
+- `beforeTransfer` / `afterTransfer`
+- `beforeMint` / `afterMint`
+- `beforeBurn` / `afterBurn`
+- `beforeApprove` / `afterApprove`
+
+## Key Components
+
+### HookExecutor (`HookExecutor.ts`)
+High-level orchestrator for hook execution during native operations.
+
+**Main Method**: `executeWithHooks(request: ExecuteWithHooksRequest): Promise<HookExecutionResult>`
+
+**Execution Flow**:
+```text
+ExecuteWithHooksRequest
+       │
+       ▼
+1. Execute beforeHook
+   ├── If hook throws or returns `reject` → Return `rejection`
+   └── If hook returns mutations/setStorage → Update working state
+       │
+       ▼
+2. Apply native operation mutations
+       │
+       ▼
+3. Execute afterHook
+   ├── If hook throws or returns `reject` → Return `rejection`
+   └── If hook returns mutations/setStorage → Update working state
+       │
+       ▼
+4. Return HookExecutionResult
+   ├── finalState: GCRTokenData
+   ├── mutations: TokenMutation[]
+   ├── rejection: { hookType: string; reason: string } | null
+   └── metadata: HookExecutionMetadata
+```
+
+### Hook Result Structure
+```typescript
+interface HookResult {
+    reject?: string | boolean
+    mutations?: TokenMutation[]
+    setStorage?: Record<string, unknown>
+}
+```
+
+### Hook Rejection
+```typescript
+interface HookRejection {
+    hookType: string
+    reason: string
+}
+```
+
+## Utility Functions
+
+### Native Operation Mutations
+- `createTransferMutations(from, to, amount)` → [subBalance, addBalance]
+- `createMintMutations(to, amount)` → [addBalance]
+- `createBurnMutations(from, amount)` → [subBalance]
+- `createApproveMutations(owner, spender, amount)` → [setAllowance]
+
+### Validation Helpers
+- `validateSufficientBalance(tokenData, address, amount)`
+- `validateSufficientAllowance(tokenData, owner, spender, amount)`
+
+### Merging
+- `mergeHookResults(results: HookResult[])` → Single HookResult
+
+## Usage Example
+```typescript
+const executor = new HookExecutor(scriptExecutor)
+
+const result = await executor.executeWithHooks({
+    operation: "transfer",
+    operationData: { from: "0x1", to: "0x2", amount: 100n },
+    tokenAddress: "0xToken",
+    tokenData: currentState,
+    scriptCode: tokenScript,
+    txContext: { caller, txHash, timestamp, blockHeight, prevBlockHash },
+    nativeOperationMutations: createTransferMutations("0x1", "0x2", 100n),
+})
+
+if (!result.rejection) {
+    // Apply result.finalState to storage
+} else {
+    // Handle rejection: result.rejection.reason
+}
+```
+
+## Integration with ScriptExecutor
+HookExecutor uses the current `scriptExecutor` implementation in `src/libs/scripting/index.ts`, which executes exported hook functions inside a Node `vm` context with timeouts. This is a determinism-oriented execution model, not a security boundary.
+
+## Error Handling
+- Hook errors cancel the operation.
+- The current branch does not re-run hook logic during rollback; rollback support is limited to the native reverse paths implemented in `GCRTokenRoutines`.
+- Custom-method rollback remains explicitly unsupported and should not be documented as fully restorative.
+
+## Consensus Integration (Phase 5.1)
+
+### GCRTokenRoutines Integration
+The hook system is now integrated into the consensus flow through `GCRTokenRoutines`:
+
+**Files Modified**:
+- `src/libs/blockchain/gcr/handleGCR.ts` - Passes Transaction to GCRTokenRoutines.apply
+- `src/libs/blockchain/gcr/gcr_routines/GCRTokenRoutines.ts` - Contains hook integration
+
+**Key Changes**:
+
+1. **GCRTokenRoutines.apply signature updated**:
+   ```typescript
+   static async apply(
+       editOperation: GCREditToken,
+       gcrTokenRepository: Repository<GCRToken>,
+       simulate: boolean,
+       tx?: Transaction,  // New: Transaction context for hook execution
+   ): Promise<GCRResult>
+   ```
+
+2. **Helper Methods Added**:
+   - `getHookExecutor()` - Singleton HookExecutor instance
+   - `tokenToGCRTokenData(token)` - Converts GCRToken entity to GCRTokenData interface
+   - `applyGCRTokenDataToEntity(token, data)` - Applies mutations back to entity
+
+3. **Handler Integration Pattern**:
+   Each handler (transfer, mint, burn) now checks for scripts:
+   ```typescript
+   if (token.hasScript && token.script?.code && tx && !edit.isRollback) {
+       // Use HookExecutor.executeWithHooks()
+       // Handle rejection via result.rejection
+       // Apply finalState via applyGCRTokenDataToEntity()
+   } else {
+       // Native operation without hooks
+   }
+   ```
+
+### Consensus Flow
+
+```text
+Transaction submitted
+       │
+       ▼
+PoRBFTv2 Consensus
+       │
+       ▼
+applyGCREditsFromMergedMempool
+       │
+       ▼
+HandleGCR.apply(edit, tx)    ← Now passes tx
+       │
+       ▼
+GCRTokenRoutines.apply(edit, repo, simulate, tx)
+       │
+       ▼
+handleTransferToken / handleMintToken / handleBurnToken
+       │
+       ├── Token has script? ──Yes──▶ HookExecutor.executeWithHooks()
+       │                                    │
+       │                              ┌─────┴─────┐
+       │                              │           │
+       │                        Proceed     Rejection
+       │                              │           │
+       │                      Apply finalState    │
+       │                              │           │
+       │                              ▼           ▼
+       │                         Save entity   Return failure
+       │
+       └── No script ───────▶ Native operation
+                                    │
+                                    ▼
+                               Save entity
+```
+
+### Determinism Notes
+- Consensus-critical hook execution currently uses the Node `vm`-based runtime in `src/libs/scripting/index.ts`, not SES.
+- `prevBlockHash` is currently a placeholder value in some paths and is intended to be injected by consensus later.
+- `blockHeight` comes from `tx.blockNumber` and may be absent during mempool-side processing.
+- `timestamp` is taken from transaction content when available; any `Date.now()` fallback should be treated as non-consensus or pre-consensus behavior, not as a deterministic guarantee.
+
+### Rollback Handling
+Script hooks are not executed during rollback. Rollback paths currently reverse only the supported native token effects; script-upgrade payload restoration and opaque custom-method state reversal are tracked separately and are not complete guarantees today.
+
+## Last Updated
+2026-02-23 - Phase 5.1 consensus integration complete

.serena/memories/arch_scripting_module_structure.md

@@ -0,0 +1,87 @@
+# Scripting Module Architecture
+
+## Summary
+The `src/libs/scripting/` module provides secure, deterministic script execution for token operations using SES (Secure EcmaScript) sandbox technology.
+
+## Key Components
+
+### TokenSandbox (`TokenSandbox.ts`)
+Low-level SES compartment management:
+- `initialize()` - Locks down JS primordials via SES
+- `execute(code, context, config)` - Runs script in isolated compartment
+- `executeHook(hookCode, hookType, context, config)` - Runs hooks for native operations
+- `validateMutations()` - Structural validation of mutations
+- Deterministic PRNG via `createSeededRandom()` using prevBlockHash + txHash
+
+### ScriptExecutor (`ScriptExecutor.ts`)
+High-level orchestration service:
+- `executeMethod(request)` - Main entry point for consensus layer
+- `executeHook(request)` - Hook execution for native operations
+- `validateMutationsAgainstToken()` - Business rule validation
+- Builds ScriptContext from ExecuteMethodRequest
+- Merges config with defaults
+
+Key types:
+- `BlockContext` - height, prevBlockHash, timestamp
+- `ExecuteMethodRequest` - tokenAddress, method, args, caller, blockContext, txHash, tokenData
+- `ExecuteHookRequest` - hookCode, hookType, hookContext, tokenData
+
+### MutationApplier (`MutationApplier.ts`)
+Pure functions for applying mutations:
+- `applyMutations(tokenData, mutations)` - Main apply function
+- Returns `MutationApplicationResult` with newState, events, mutationsApplied
+- Immutable - creates deep copy before modifications
+- Utility functions: `isEmitMutation()`, `getStateMutations()`, `getEventMutations()`
+
+### TokenStateAccessorBuilder (`TokenStateAccessorBuilder.ts`)
+Builds read-only state accessors:
+- `buildTokenStateAccessor(data)` - Full accessor for scripts
+- `buildMinimalAccessor()` - Minimal accessor for testing
+
+### Types (`types.ts`)
+Core type definitions:
+- `ScriptContext` - caller, method, args, timestamp, blockHeight, prevBlockHash, txHash, token
+- `StateMutation` - Union of SetBalance, AddBalance, SubBalance, SetAllowance, SetStorage, Emit
+- `ScriptResult` - ScriptSuccess | ScriptError
+- `HookContext`, `HookResult` - Hook-specific types
+
+## Execution Flow
+
+```
+ExecuteMethodRequest
+       │
+       ▼
+ScriptExecutor.executeMethod()
+       │
+       ├─▶ buildTokenStateAccessor(tokenData)
+       │
+       ├─▶ Build ScriptContext
+       │
+       ├─▶ tokenSandbox.execute(code, context, config)
+       │       │
+       │       └─▶ SES Compartment execution
+       │           Returns StateMutation[]
+       │
+       ├─▶ validateMutationsAgainstToken()
+       │       (Business rule validation)
+       │
+       └─▶ Return ScriptResult
+               │
+               ▼
+         applyMutations(tokenData, result.mutations)
+               │
+               └─▶ MutationApplicationResult
+                   (newState, events, mutationsApplied)
+```
+
+### HookExecutor (`HookExecutor.ts`)
+Native operation hook orchestrator:
+- `executeWithHooks(request)` - Main entry for consensus layer
+- Execution flow: beforeHook → native mutations → afterHook
+- Rejection handling with rollback on afterHook failure
+- Utility functions: `createTransferMutations()`, `createMintMutations()`, etc.
+
+See `arch_hook_system` memory for detailed hook architecture.
+
+## Last Updated
+2026-02-22 - Phase 2.4 completion (added HookExecutor)