Feature/parametric token support

.gitignore

@@ -0,0 +1,12 @@
+node_modules/
+.prettierrc
+.prettierignore
+.vscode/
+.prettierrc
+.prettierignore
+.vscode/
+.idea/
+*.swp
+.DS_Store
+contracts/foundry.toml
+package-lock.json

.prettierrc

@@ -0,0 +1,22 @@
+{
+  "tabWidth": 2,
+  "useTabs": false,
+  "printWidth": 120,
+  "semi": true,
+  "singleQuote": false,
+  "trailingComma": "es5",
+  "bracketSpacing": true,
+  "arrowParens": "always",
+  "overrides": [
+    {
+      "files": "*.sol",
+      "options": {
+        "printWidth": 160,
+        "tabWidth": 4,
+        "useTabs": false,
+        "bracketSpacing": false
+      }
+    }
+  ],
+  "plugins": ["prettier-plugin-solidity"]
+}

.vscode/settings.json

@@ -0,0 +1,22 @@
+{
+  "[solidity]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "editor.formatOnSave": true
+  },
+  "[typescript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "editor.formatOnSave": true,
+    "editor.tabSize": 2,
+    "editor.insertSpaces": true,
+    "editor.detectIndentation": false
+  },
+  "[javascript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "editor.formatOnSave": true,
+    "editor.tabSize": 2,
+    "editor.insertSpaces": true,
+    "editor.detectIndentation": false
+  },
+  "prettier.documentSelectors": ["**/*.sol"],
+  "prettier.enable": true
+}

contracts/README.md

@@ -4,10 +4,10 @@
 
 Foundry consists of:
 
--   **Forge**: Ethereum testing framework (like Truffle, Hardhat and DappTools).
--   **Cast**: Swiss army knife for interacting with EVM smart contracts, sending transactions and getting chain data.
--   **Anvil**: Local Ethereum node, akin to Ganache, Hardhat Network.
--   **Chisel**: Fast, utilitarian, and verbose solidity REPL.
+- **Forge**: Ethereum testing framework (like Truffle, Hardhat and DappTools).
+- **Cast**: Swiss army knife for interacting with EVM smart contracts, sending transactions and getting chain data.
+- **Anvil**: Local Ethereum node, akin to Ganache, Hardhat Network.
+- **Chisel**: Fast, utilitarian, and verbose solidity REPL.
 
 ## Documentation
 
@@ -64,3 +64,57 @@ $ forge --help
 $ anvil --help
 $ cast --help
 ```
+
+## Parametric Tokens
+
+Nitrolite supports tokens with additional parameters (e.g., mintTime) through the `IParametricToken` interface. These tokens maintain separate balances per sub-account to preserve parameter integrity. `ParametricToken` contract provides implementation of a token with both mutable and immutable parameters.
+
+### How It Works
+
+When a token is marked parametric, the ChannelHub contract:
+
+1. Converts its own account to Super account on the token
+2. Creates a new sub-account for each channel at channel creation time
+3. Stores the sub-account ID in channel metadata
+
+All subsequent deposits, withdrawals, and transfers for that channel automatically use the correct sub-account.
+
+### Important: Channel Must Exist First
+
+For parametric tokens, funds **cannot be deposited before channel creation**. The workflow is:
+
+1. **Create channel** → ChannelHub creates a sub-account and returns channel ID
+2. **Deposit** → Funds go to the channel's sub-account
+3. **Transfer/Withdraw** → Funds move from/to the sub-account
+
+Depositing a parametric token without an existing channel leads to token lock and requires reclaim.
+
+### Enabling Parametric Token Support
+
+The vault contract owner must perform two steps:
+
+```solidity
+// Step 1: Mark token as parametric
+channelHub.setParametricToken(tokenAddress, true);
+
+// Step 2: Convert ChannelHub to Super account on the token
+IParametricToken(tokenAddress).convertToSuper(address(channelHub));
+```
+
+After this, channel creation and deposits work through the standard NitroliteClient API - no additional user action required.
+
+### Low-Level Access
+
+For advanced use cases, the `IParametricToken` interface exposes direct sub-account operations:
+
+- `transferToSub()` - Transfer from normal account to a vault sub-account
+
+- `transferFromSub()` - Transfer from a vault sub-account to normal account
+
+- `transferBetweenSubs()` - Transfer between sub-accounts of the same super account (including vault)
+
+These are intended for custom integrations and use `subId` for sub-account identification; standard channel operations handle sub-accounts automatically.
+
+### Standard ERC20 Tokens
+
+For non-parametric tokens (USDC, ETH, etc.), the `isParametricToken` flag is disabled by default and no sub-accounts are created.

contracts/foundry.lock

@@ -0,0 +1,11 @@
+{
+  "lib/forge-std": {
+    "tag": {
+      "name": "v1.15.0",
+      "rev": "0844d7e1fc5e60d77b68e469bff60265f236c398"
+    }
+  },
+  "lib/openzeppelin-contracts": {
+    "rev": "fcbae5394ae8ad52d8e580a3477db99814b9d565"
+  }
+}

contracts/foundry.toml

@@ -11,10 +11,10 @@ optimizer_runs = 1_000_000
 
 # special compiler profile for ChannelHub to prevent code size overflow
 additional_compiler_profiles = [
-  { name = "channelhub", optimizer_runs = 2_000 }
+  { name = "channelhub", optimizer_runs = 750 }
 ]
 
 # compile ChannelHub with lower optimizer runs to stay within size limits
 compilation_restrictions = [
-  { paths = "src/ChannelHub.sol", optimizer_runs = 2_000 }
+  { paths = "src/ChannelHub.sol", optimizer_runs = 750 }
 ]

contracts/src/ChannelEngine.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity 0.8.30;
+pragma solidity ^0.8.30;
 
 import {SafeCast} from "@openzeppelin/contracts/utils/math/SafeCast.sol";
 import {ChannelStatus, State, StateIntent} from "./interfaces/Types.sol";
@@ -54,13 +54,14 @@ library ChannelEngine {
         uint256 lockedFunds;
         uint256 nodeAvailableFunds;
         uint64 challengeExpiry;
+        bool isParametricToken;
+        uint48 channelSubId;
     }
 
     struct TransitionEffects {
         // Fund movements (positive = pull/lock, negative = push/release)
         int256 userFundsDelta; // Funds to pull from user (>0) or push to user (<0)
         int256 nodeFundsDelta; // Funds to lock from node vault (>0) or release (<0)
-
         // State updates
         ChannelStatus newStatus;
         uint64 newChallengeExpiry;
@@ -100,6 +101,12 @@ library ChannelEngine {
         // homeLedger always represents current chain
         require(candidate.homeLedger.chainId == block.chainid, IncorrectHomeChainId());
         require(candidate.version > ctx.prevState.version || Utils.isEmpty(ctx.prevState), IncorrectStateVersion());
+        if (ctx.isParametricToken) {
+            require(
+                Utils.isEmpty(ctx.prevState) || candidate.homeLedger.token == ctx.prevState.homeLedger.token,
+                "Parametric token cannot change during channel lifetime"
+            );
+        }
 
         // Validate token decimals for homeLedger
         Utils.validateTokenDecimals(candidate.homeLedger);