Codex/builder fee approval

.gitignore

@@ -4,3 +4,12 @@
 .env
 .env.*
 *.xcuserstate
+
+# Local signing material and exported credentials.
+*.p8
+*.p12
+*.pem
+*.key
+*.keystore
+*.keychain
+*.keychain-db

Package.swift

@@ -9,9 +9,13 @@ let package = Package(
     ],
     dependencies: [
         .package(url: "https://github.com/21-DOT-DEV/swift-secp256k1.git", exact: "0.23.2"),
-        .package(url: "https://github.com/apple/swift-nio.git", exact: "2.103.0"),
+        .package(url: "https://github.com/apple/swift-nio.git", exact: "2.104.0"),
         .package(url: "https://github.com/apple/swift-nio-ssl.git", exact: "2.37.5"),
-        .package(url: "https://github.com/swift-server/async-http-client.git", exact: "1.36.2")
+        .package(url: "https://github.com/swift-server/async-http-client.git", exact: "1.36.2"),
+        .package(url: "https://github.com/grpc/grpc-swift-2.git", exact: "2.4.4"),
+        .package(url: "https://github.com/grpc/grpc-swift-nio-transport.git", exact: "2.11.0"),
+        .package(url: "https://github.com/grpc/grpc-swift-protobuf.git", exact: "2.5.0"),
+        .package(url: "https://github.com/apple/swift-protobuf.git", exact: "1.39.0")
     ],
     targets: [
         .target(
@@ -24,8 +28,19 @@ let package = Package(
                 .product(name: "NIOPosix", package: "swift-nio"),
                 .product(name: "NIOHTTP1", package: "swift-nio"),
                 .product(name: "NIOWebSocket", package: "swift-nio"),
-                .product(name: "NIOSSL", package: "swift-nio-ssl")
+                .product(name: "NIOSSL", package: "swift-nio-ssl"),
+                .product(name: "GRPCCore", package: "grpc-swift-2"),
+                .product(name: "GRPCNIOTransportHTTP2Posix", package: "grpc-swift-nio-transport"),
+                .product(name: "GRPCProtobuf", package: "grpc-swift-protobuf"),
+                .product(name: "SwiftProtobuf", package: "swift-protobuf")
             ]),
-        .testTarget(name: "HyperliquidCoreTests", dependencies: ["HyperliquidCore"])
+        .testTarget(name: "HyperliquidCoreTests", dependencies: [
+            "HyperliquidCore",
+            .product(name: "GRPCCore", package: "grpc-swift-2"),
+            .product(name: "GRPCInProcessTransport", package: "grpc-swift-2"),
+            .product(name: "GRPCNIOTransportHTTP2Posix", package: "grpc-swift-nio-transport"),
+            .product(name: "GRPCProtobuf", package: "grpc-swift-protobuf"),
+            .product(name: "SwiftProtobuf", package: "swift-protobuf")
+        ])
     ]
 )

README.md

@@ -4,17 +4,22 @@ Swift protocol and domain library extracted from HyperliquidX. This is a communi
 
 ## Requirements
 
-Xcode 26.3 or later (Swift 6.2+) to build; macOS 14 or later to run. Other platforms are not currently validated; the implementation uses Apple Security, CryptoKit, Network and Darwin APIs.
+Xcode 26.3 or later (Swift 6.2+) to build; macOS 14 or later to run. The optional gRPC L4 client requires macOS 15 or later; reducers and existing REST/WS APIs retain macOS 14 support. Other platforms are not currently validated; the implementation uses Apple Security, CryptoKit, Network and Darwin APIs.
 
 ## Scope
 
 - REST and WebSocket transports, market catalogs (including HIP-3), candles and order books.
+- Full per-order L4 reconstruction and a configurable Quicknode typed gRPC client; see [L4 coverage and contracts](docs/L4_BOOK.md).
 - Account streams, history, order validation, slippage and position risk calculations.
 - Ethereum signing, temporary trading sessions, wallet connection models and a local browser-wallet bridge.
 - Transfers and deposit routing, including CCTP and Unit-related models and clients.
 
 The package contains no app screens, chart rendering, layout models, Touch ID workflow, Reown dependency, or bundled wallet web page. Applications provide their own UI and wallet integration. APIs are initially experimental; releases before 1.0 may change them.
 
+## Module organization
+
+Implementation and tests are grouped by Hyperliquid domain: types, networking, market data, accounts, trading, signing, wallet, funding and analytics. See [module ownership and fixture paths](docs/MODULES.md). Public imports remain `import HyperliquidCore`.
+
 ## Swift Package Manager
 
 Add the package and product to your manifest:

Sources/HyperliquidCore/MarketData/L4/L4BookQueries.swift

@@ -0,0 +1,30 @@
+import Foundation
+
+public enum L4BookQueryError: Error, Equatable, Sendable {
+    case invalidLimit, invalidPrice, invalidCursor, staleCursor
+}
+
+/// Local pagination identity, not an exchange sequence or a queue-priority position.
+public struct L4OrderPageCursor: Equatable, Sendable {
+    public let environment: NetworkEnvironment
+    public let coin: String
+    public let side: L4OrderIdentity.Side
+    public let price: Decimal
+    public let levelRevision: UUID
+    public let afterOID: UInt64
+}
+
+/// A bounded inspection of one unchanged price level, sorted numerically by OID, never FIFO.
+public struct L4OrderPage: Sendable {
+    public let environment: NetworkEnvironment
+    public let coin: String
+    public let side: L4OrderIdentity.Side
+    public let price: Decimal
+    public let height: UInt64
+    public let time: Int64
+    public let levelRevision: UUID?
+    public let totalOrderCount: Int
+    public let totalSize: Decimal
+    public let orders: [L4Order]
+    public let nextCursor: L4OrderPageCursor?
+}