Update docs to match current state (#66)

Author: ScreamingHawk

CLAUDE.md

@@ -34,55 +34,35 @@ Deployment scripts are in `script/` directory. Required environment variables:
 
 ### Core Components
 
-This is a Solidity project implementing **Sapient Signer modules** for Sequence v3 wallets, focusing on cross-chain payment and bridging functionality through LiFi and relay protocols.
+This is a Solidity project implementing cross-chain payment and bridging functionality through TrailsRouter and TrailsIntentEntrypoint for Sequence v3 wallets.
 
 #### Primary Contracts
-- **TrailsLiFiSapientSigner** (`src/TrailsLiFiSapientSigner.sol`) - Validates LiFi protocol operations (swaps/bridges) via off-chain attestations. Targets a specific immutable `TARGET_LIFI_DIAMOND` address for security.
-- **TrailsRelaySapientSigner** (`src/TrailsRelaySapientSigner.sol`) - Validates relay operations through similar attestation mechanism.
-- **TrailsTokenSweeper** (`src/TrailsTokenSweeper.sol`) - Utility contract for token recovery operations.
+- **TrailsRouter** (`src/TrailsRouter.sol`) - Consolidated router contract combining multicall routing, balance injection, and token sweeping functionality. Executes via delegatecall from Sequence v3 wallets.
+- **TrailsRouterShim** (`src/TrailsRouterShim.sol`) - Lightweight shim that wraps router calls and records execution success using storage sentinels.
+- **TrailsIntentEntrypoint** (`src/TrailsIntentEntrypoint.sol`) - EIP-712 signature-based entrypoint for depositing tokens to intent addresses with user authorization.
 
 #### Library Architecture
 The project uses a modular library approach under `src/libraries/`:
 
-**Execution Info Management:**
-- `TrailsExecutionInfoInterpreter.sol` - Standardizes cross-chain execution data
-- `TrailsExecutionInfoParams.sol` - Parameter handling for execution info
+**Sentinel Management:**
+- `TrailsSentinelLib.sol` - Manages storage sentinels for conditional execution tracking using tstore/sstore
 
-**LiFi Integration:**
-- `TrailsLiFiFlagDecoder.sol` - Decodes LiFi call data using flag-based strategies
-- `TrailsLiFiInterpreter.sol` - Interprets and validates LiFi operations
-- `TrailsLiFiValidator.sol` - Validation logic for LiFi transactions
-
-**Relay Integration:**
-- `TrailsRelayDecoder.sol` - Decodes relay call data
-- `TrailsRelayInterpreter.sol` - Interprets relay operations
-- `TrailsRelayValidator.sol` - Validation logic for relay transactions
-- `TrailsRelayParams.sol` - Parameter handling for relay operations
+### Key Architecture Patterns
 
-#### Interface Definitions
-- `TrailsExecutionInfo.sol` - Core execution info structure
-- `TrailsLiFi.sol` - LiFi-specific interfaces and decoding strategies
-- `TrailsRelay.sol` - Relay-specific interfaces
+**Delegatecall-Only Execution:** TrailsRouter and TrailsRouterShim are designed to execute only via delegatecall from Sequence v3 wallets. Direct calls are blocked via `onlyDelegatecall` modifier.
 
-### Key Architecture Patterns
+**Success Sentinel Pattern:** Operations track success/failure via storage sentinels keyed by `opHash`. This enables conditional fee collection and fallback refund logic.
 
-**Sapient Signer Integration:** Both main contracts implement `ISapient` interface and integrate with Sequence wallet configuration trees as "Sapient Signer Leaves". They validate off-chain attestations to authorize operations without requiring direct wallet pre-approval.
+**Balance Injection:** Runtime balance injection allows protocols to receive exact token amounts when bridge amounts are unknown beforehand (due to slippage and fees).
 
-**Validation Flow:**
-1. Contract receives payload and encoded signature (attestation)
-2. Validates target addresses match immutable contract addresses
-3. Recovers attestation signer from signature
-4. Decodes and interprets operation data using libraries
-5. Computes intent hash from operations + signer
-6. Returns hash for comparison against wallet's configured `imageHash`
+**EIP-712 Intent Authorization:** TrailsIntentEntrypoint uses EIP-712 signatures to authorize deposits to intent addresses, preventing replay attacks via nonce tracking.
 
-**Security Model:** Each contract is deployed with immutable target addresses to prevent authorization of calls to arbitrary contracts. All validation is stateless and deterministic.
 
 ### External Dependencies
-- **Sequence Wallet v3** - Core wallet infrastructure and payload handling
-- **OpenZeppelin** - Cryptographic utilities (ECDSA, MessageHashUtils)
-- **LiFi Protocol** - Cross-chain bridge/swap interfaces
-- **ERC2470** - Singleton deployment pattern
+- **Sequence Wallet v3** (`wallet-contracts-v3`) - Core wallet infrastructure and payload handling (`IDelegatedExtension`)
+- **OpenZeppelin** (`openzeppelin-contracts`) - Token standards (IERC20, IERC20Permit), SafeERC20, cryptographic utilities (ECDSA), and security (ReentrancyGuard)
+- **Tstorish** (`tstorish`) - Storage library for tstore/sstore operations
+- **ERC2470** (`erc2470-libs`) - Singleton deployment pattern for deterministic addresses
 
 ### Testing Structure
 Tests mirror the source structure with unit tests for libraries and integration tests for main contracts. Mock contracts in `test/mocks/` simulate external protocol interactions.

CODE4ARENA.md

@@ -1,6 +1,6 @@
 # Trails Contracts — Code4rena Audit Prep
 
-These contracts are used with **Trails** (https://docs.trails.build/) and Sequence v3 **sapient signer** wallets. The closed‑source **Intent Machine** is **out of scope** for this audit, but auditors can exercise public API interfaces that drive the on‑chain flows.
+These contracts are used with **Trails** (https://docs.trails.build/) and Sequence v3 wallets. The closed‑source **Intent Machine** is **out of scope** for this audit, but auditors can exercise public API interfaces that drive the on‑chain flows.
 
 ---
 

docs/README.md

@@ -6,28 +6,18 @@ Welcome to the comprehensive documentation for the Trails smart contract ecosyst
 
 ### Core Contracts
 
-#### 🚀 TrailsEntrypointV2 - Revolutionary 1-Click Transactions
-**[Technical Specification →](TrailsEntrypointV2.md)**
+#### 🚀 TrailsIntentEntrypoint - Revolutionary 1-Click Transactions
+**[Technical Specification →](../src/TrailsIntentEntrypoint.sol)**
 
 The latest innovation in the Trails ecosystem: a single entrypoint contract that enables true 1-click crypto transactions by accepting intents through ETH/ERC20 transfers with calldata suffixes.
 
 **Key Features:**
 - Single entrypoint for all intent-based operations
-- Transfer suffix pattern eliminates approve step
-- Commit-prove pattern with signature validation
+- EIP-712 signature verification for secure intent authorization
+- ERC-2612 permit support for gasless approvals
 - Generic multicall execution for bridges, swaps, and DeFi operations
 - Comprehensive safety mechanisms and emergency functions
 
-#### 🔐 Sapient Signer Architecture
-**[Sapient Signer Documentation →](SAPIENT_SIGNER.md)**
-
-Framework for Sequence v3 wallet integration enabling off-chain attestation validation for automated protocol operations.
-
-**Core Modules:**
-- TrailsLiFiSapientSigner - LiFi protocol validation
-- TrailsRelaySapientSigner - Relay operation validation  
-- TrailsTokenSweeper - Token recovery utilities
-
 ## 🏗️ Architecture Overview
 
 ### Design Principles
@@ -70,7 +60,7 @@ forge build
 forge test
 
 # Run specific tests
-forge test --match-contract TrailsEntrypointV2Test
+forge test --match-contract TrailsIntentEntrypointTest
 ```
 
 ### Testing Strategy
@@ -110,67 +100,10 @@ forge script script/Deploy.s.sol --rpc-url $RPC_URL --broadcast --verify
 
 ## 🚀 Usage Examples
 
-### Simple ETH Bridge
-
-```javascript
-// 1. Commit intent
-const intent = {
-    sender: userAddress,
-    token: ZERO_ADDRESS, // ETH
-    amount: parseEther("1.0"),
-    destinationChain: 137, // Polygon
-    destinationAddress: userAddress,
-    extraData: "0x",
-    nonce: await entrypoint.nonces(userAddress),
-    deadline: Math.floor(Date.now() / 1000) + 3600
-};
-
-const intentHash = await entrypoint.commitIntent(intent);
-
-// 2. Send ETH with intent hash suffix
-const calldata = ethers.utils.concat([
-    ethers.utils.randomBytes(32),
-    intentHash
-]);
-
-await user.sendTransaction({
-    to: entrypoint.address,
-    value: intent.amount,
-    data: calldata
-});
-
-// 3. Backend proves and executes
-await entrypoint.proveETHDeposit(intentHash, txProof);
-await entrypoint.executeIntent(intentHash, bridgeCalls);
-```
+For integration examples and usage guides, please refer to:
 
-### ERC20 Swap + Bridge
-
-```javascript
-// 1. Commit ERC20 intent
-const intent = {
-    sender: userAddress,
-    token: USDC_ADDRESS,
-    amount: parseUnits("100", 6),
-    destinationChain: 42161, // Arbitrum
-    destinationAddress: userAddress,
-    extraData: encodeSwapData(USDC_ADDRESS, WETH_ADDRESS),
-    nonce: await entrypoint.nonces(userAddress),
-    deadline: Math.floor(Date.now() / 1000) + 3600
-};
-
-// 2. Deposit ERC20
-await usdc.approve(entrypoint.address, intent.amount);
-await entrypoint.depositERC20WithIntent(intentHash, USDC_ADDRESS, intent.amount);
-
-// 3. Execute swap + bridge
-const calls = [
-    { target: DEX_ADDRESS, data: swapCalldata, value: 0 },
-    { target: BRIDGE_ADDRESS, data: bridgeCalldata, value: 0 }
-];
-
-await entrypoint.executeIntent(intentHash, calls);
-```
+- **[Trails Website](https://trails.build)** - Learn more about Trails and explore the platform
+- **[Trails SDK Documentation](https://docs.trails.build/sdk/get-started)** - Complete SDK integration guide with React widget examples
 
 ## 📈 Future Roadmap