Repository Public
1// =============================================================================2// SP BOUCHER | SOFTWARE & RESEARCH3// ARTIFICIAL INTELLIGENCE • FINANCE • ENGINEERING4// =============================================================================5//6// PROJECT METADATA7// -----------------------------------------------------------------------------8// Project : SPWalletCore9// File : Sources/SPWalletCore/Domains/Agents/AgentsCanonical.swift10// Description : The objects an owner approves with a passkey to let an11// agent trade without a passkey per order, byte for byte as12// the backend serializes them: the spot vault mandate13// `SPW-MANDATE-v1` (packages/core/src/mandate.ts), the14// derivative mandate `SPW-VENUE-MANDATE-v1`15// (packages/derivatives/src/live/mandate.ts), the quoting16// mandate `SPW-VENUE-QUOTING-MANDATE-v1`17// (packages/derivatives/src/live/quoting.ts), the trading18// mandate `SPW-TRADING-MANDATE-v1`19// (packages/trading/src/mandate/trading-mandate.ts) whose20// hash the approval names, and the API-side approval intent21// `SPW-TRADING-MANDATE-APPROVAL-v1`22// (services/api/src/mandates/service.ts). Strict parsing: a23// field this code does not know, or a value the backend's24// schema would refuse, is a refusal — never hashed "as is".25// Module : SPWalletCore26// Repository : https://git.spboucher.ai/sp-wallet-core27// Created : 2026-11-1828// Last Modified : 2026-11-1829//30// =============================================================================31// AUTHOR & PROFESSIONAL AFFILIATION32// =============================================================================33//34// Author : Simon-Pierre Boucher35// Position : Professor of Finance36// Institution : Université du Québec en Outaouais (UQO)37// Department : Département des sciences administratives38// Organization : SP Boucher39//40// Website : https://spboucher.ai41// Git : https://git.spboucher.ai42//43// =============================================================================44// OFFICIAL CONTACT DIRECTORY45// =============================================================================46//47// General : info@spboucher.ai48// Professional : contact@spboucher.ai49// Direct : simon@spboucher.ai50// Research : research@spboucher.ai51// Development : dev@spboucher.ai52// Support : support@spboucher.ai53// Security/Admin : admin@spboucher.ai54// Notifications : notifications@spboucher.ai55//56// Preferred Contact: support@spboucher.ai57//58// =============================================================================59// COPYRIGHT & INTELLECTUAL PROPERTY60// =============================================================================61//62// Copyright (c) 202663// Simon-Pierre Boucher64//65// All rights reserved where applicable.66//67// This file is governed by the applicable project license,68// copyright notices, institutional agreements and relevant law.69//70// Unless expressly authorized by the applicable license or71// rights holder, copying, redistribution, sublicensing,72// publication and commercial exploitation are not permitted.73//74// Existing third-party rights and notices remain unaffected.75//76// =============================================================================77// CONFIDENTIALITY & SECURITY78// =============================================================================79//80// Classification : Public81// Distribution : Public repository; use is governed by the project license82// Security Contact : admin@spboucher.ai83//84// Access to this source does not independently grant permission85// to redistribute or disclose confidential materials.86//87// Do not embed credentials, private keys, access tokens,88// certificates or confidential personal information.89//90// =============================================================================91// LICENSE & MAINTENANCE92// =============================================================================93//94// License : None specified (no license file in this repository)95// Maintainer : Simon-Pierre Boucher96// Technical Contact: dev@spboucher.ai97//98// =============================================================================99// END OF SP BOUCHER SOURCE HEADER100// =============================================================================101102import Foundation103import CryptoKit104105// MARK: shared rules106107enum AgentsCanon {108 /**109 `canon(x) = D.str(D.from(x))` of packages/derivatives/src/decimal.ts: a canonical decimal string (optional minus, no leading zero,110 optional fraction, no exponent, at most 60 digits) with the trailing zeros of its fraction removed; zero is "0".111 */112 static func decimal(_ x: String, _ path: String) throws -> String {113 guard x.utf8.count <= 62, x.range(of: #"^-?(0|[1-9][0-9]*)(\.[0-9]+)?$"#, options: .regularExpression) != nil else { throw ApprovalError.unsupported("\(path) is not a canonical decimal") }114 let neg = x.hasPrefix("-"), body = neg ? String(x.dropFirst()) : x115 let parts = body.split(separator: ".", omittingEmptySubsequences: false)116 let int = String(parts[0])117 var frac = parts.count == 2 ? String(parts[1]) : ""118 guard int.count + frac.count <= 60 else { throw ApprovalError.unsupported("\(path) has more than 60 digits") }119 while frac.last == "0" { frac.removeLast() }120 if int == "0" && frac.isEmpty { return "0" }121 return (neg ? "-" : "") + int + (frac.isEmpty ? "" : "." + frac)122 }123 /** `PosDec`: not negative and with a non-zero digit. Returns the canonical text. */124 static func positive(_ x: String, _ path: String) throws -> String {125 let c = try decimal(x, path)126 guard !x.hasPrefix("-"), c != "0" else { throw ApprovalError.unsupported("\(path) must be positive") }127 return c128 }129 static func nonNegative(_ x: String, _ path: String) throws -> String {130 guard !x.hasPrefix("-") else { throw ApprovalError.unsupported("\(path) must not be negative") }131 return try decimal(x, path)132 }133 /** Exact comparison of two canonical non-negative decimals (no floating point). */134 static func less(_ a: String, _ b: String) -> Bool {135 func split(_ s: String) -> (String, String) { let p = s.split(separator: ".", omittingEmptySubsequences: false); return (String(p[0]), p.count == 2 ? String(p[1]) : "") }136 let (ai, af) = split(a), (bi, bf) = split(b)137 if ai.count != bi.count { return ai.count < bi.count }138 if ai != bi { return ai < bi }139 let n = max(af.count, bf.count)140 return af.padding(toLength: n, withPad: "0", startingAt: 0) < bf.padding(toLength: n, withPad: "0", startingAt: 0)141 }142 static func matches(_ s: String, _ pattern: String) -> Bool { s.range(of: pattern, options: .regularExpression) != nil }143 static func require(_ ok: Bool, _ what: String) throws { if !ok { throw ApprovalError.unsupported(what) } }144 static let uuid = #"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"#145 static let sha = "^[0-9a-f]{64}$"146 static let lowerAddress = "^0x[0-9a-f]{40}$"147 static let instrument = "^hyperliquid:[A-Za-z0-9]{1,15}$"148 static let agentId = #"^[A-Za-z0-9._:-]{1,64}$"#149 /** JavaScript's `<` on strings (UTF-16 code units): the order of every sorted list of these objects. */150 static func sorted(_ xs: [String]) -> [String] { xs.sorted(by: Intent.codeUnitOrder) }151152 static func frame(_ domain: String, _ fields: [(String, String)]) -> Data {153 var w = CanonicalWriter(domain: domain)154 for (k, v) in fields { w.field(k, v) }155 return w.data156 }157158 /**159 `stableJson` of services/api/src/derivatives/exec.ts: keys sorted at every depth, no whitespace, scalars as `JSON.stringify`160 writes them. Integers only: a non-integer number never occurs in the objects of this file and is refused.161 */162 static func stableJSON(_ v: JSONValue, _ path: String) throws -> String {163 switch v {164 case .null: return "null"165 case .bool(let b): return b ? "true" : "false"166 case .int(let i):167 guard abs(i) <= 9_007_199_254_740_991 else { throw ApprovalError.unsupported("\(path) is outside the exact integer range") }168 return String(i)169 case .double: throw ApprovalError.unsupported("\(path) is not an integer")170 case .string(let s): return quote(s)171 case .array(let a): return "[" + (try a.enumerated().map { try stableJSON($1, "\(path).\($0)") }).joined(separator: ",") + "]"172 case .object(let o): return "{" + (try sorted(Array(o.keys)).map { quote($0) + ":" + (try stableJSON(o[$0]!, "\(path).\($0)")) }).joined(separator: ",") + "}"173 }174 }175 private static func quote(_ s: String) -> String {176 var out = "\""177 for u in s.unicodeScalars {178 switch u.value {179 case 0x22: out += "\\\""180 case 0x5c: out += "\\\\"181 case 0x08: out += "\\b"182 case 0x09: out += "\\t"183 case 0x0a: out += "\\n"184 case 0x0c: out += "\\f"185 case 0x0d: out += "\\r"186 case 0..<0x20: out += String(format: "\\u%04x", u.value)187 default: out.unicodeScalars.append(u)188 }189 }190 return out + "\""191 }192}193194private extension StrictObject {195 mutating func strings(_ k: String) throws -> [String] {196 try array(k).map { guard let s = $0.stringValue else { throw ApprovalError.unsupported("\(path).\(k) holds a non-string") }; return s }197 }198 mutating func required(_ k: String) throws -> StrictObject {199 guard let c = try child(k) else { throw ApprovalError.unsupported("\(path).\(k) missing") }200 return c201 }202 mutating func int(_ k: String, in range: ClosedRange<Int>) throws -> Int {203 let v = try int(k)204 guard range.contains(v) else { throw ApprovalError.unsupported("\(path).\(k) = \(v) is outside \(range.lowerBound)…\(range.upperBound)") }205 return v206 }207 mutating func positiveInt(_ k: String) throws -> Int { try int(k, in: 1...Int(Int32.max) * 4_194_304) }208 mutating func match(_ k: String, _ pattern: String) throws -> String {209 let s = try string(k)210 guard AgentsCanon.matches(s, pattern) else { throw ApprovalError.unsupported("\(path).\(k) has an unexpected form") }211 return s212 }213}214215// MARK: SPW-MANDATE-v1 — the spot agent's vault mandate216217/**218 What an agent's vault may do without a passkey per order: swaps through ONE provider on ONE network, between the listed assets,219 within per-order and per-day caps, a daily order count and a slippage guard, until `expiresAt`. Stored and enforced by the isolated220 signer; nothing outside the signer can widen it. A vault can otherwise only pay the owner's own address.221 */222public struct AgentSpotMandate: PasskeyApprovable, Equatable {223 public static let domain = "SPW-MANDATE-v1"224 public static let maxDays = 90225226 public let mandateId: String227 /** The OWNER key this mandate belongs to. */228 public let keyId: String229 /** HD account index of the vault (≥ 1: index 0 is the owner's own wallet and can never be mandated). */230 public let vaultIndex: Int231 public let vault: String232 public let network: String233 /** `kyberswap` — the only provider the schema accepts. */234 public let provider: String235 /** Registry asset ids (`native` or a token address) the vault may hold and trade. */236 public let assets: [String]237 /** Per asset id, base units: largest input of a single order. An asset without a cap cannot be SOLD. */238 public let maxOrder: [String: String]239 /** Per asset id, base units: total input per UTC day. */240 public let maxDaily: [String: String]241 public let maxOrdersPerDay: Int242 /** The guaranteed output must be worth at least (1 − this) of the input at the signer's own prices. */243 public let maxSlippageBps: Int244 /** Unix seconds. */245 public let createdAt: Int246 public let expiresAt: Int247 /** SHA-256 of the strategy code this mandate was approved for. */248 public let strategySha256: String249 public let label: String250 public let served: JSONValue251252 public var expiry: Date { Date(timeIntervalSince1970: TimeInterval(expiresAt)) }253 /** Assets that can be sold under the mandate (those with caps). */254 public var sellable: [String] { assets.filter { maxOrder[$0] != nil } }255256 public init(served json: JSONValue) throws {257 var o = try StrictObject(json, path: "mandate")258 guard try o.int("v") == 1 else { throw ApprovalError.unsupported("mandate version") }259 mandateId = try o.match("mandateId", AgentsCanon.uuid)260 keyId = try o.string("keyId"); try AgentsCanon.require((8...80).contains(keyId.utf16.count), "mandate.keyId length")261 vaultIndex = try o.int("vaultIndex", in: 1...100_000)262 vault = try o.match("vault", "^0x[0-9a-fA-F]{40}$")263 network = try o.string("network"); try AgentsCanon.require((2...24).contains(network.utf16.count), "mandate.network length")264 provider = try o.string("provider"); try AgentsCanon.require(provider == "kyberswap", "mandate.provider \(provider)")265 assets = try o.strings("assets")266 try AgentsCanon.require((2...12).contains(assets.count) && assets.allSatisfy { (1...80).contains($0.utf16.count) }, "mandate.assets")267 try AgentsCanon.require(Set(assets.map { $0.lowercased() }).count == assets.count, "mandate.assets holds a duplicate")268 guard let mo = try o.stringMap("maxOrder"), let md = try o.stringMap("maxDaily") else { throw ApprovalError.unsupported("mandate limits missing") }269 maxOrder = mo; maxDaily = md270 maxOrdersPerDay = try o.int("maxOrdersPerDay", in: 1...500)271 maxSlippageBps = try o.int("maxSlippageBps", in: 10...500)272 createdAt = try o.positiveInt("createdAt"); expiresAt = try o.positiveInt("expiresAt")273 strategySha256 = try o.match("strategySha256", AgentsCanon.sha)274 label = try o.string("label"); try AgentsCanon.require((1...60).contains(label.utf16.count), "mandate.label length")275 try o.finish()276 served = json277278 // the structural rules of `validateMandate` that need neither the registry nor a clock: a mandate that breaks one is never signed279 for (name, map) in [("maxOrder", maxOrder), ("maxDaily", maxDaily)] {280 for (k, v) in map {281 try AgentsCanon.require(assets.contains(k), "mandate.\(name) sets a limit for an asset outside the mandate")282 try AgentsCanon.require((try? BaseUnits(v)) != nil, "mandate.\(name).\(k) is not a base-unit integer")283 }284 }285 for a in assets {286 try AgentsCanon.require((maxOrder[a] == nil) == (maxDaily[a] == nil), "mandate: order and daily limits must be set together")287 if let order = maxOrder[a], let daily = maxDaily[a] { try AgentsCanon.require(try BaseUnits(order) <= BaseUnits(daily), "mandate: order limit above the daily limit") }288 }289 try AgentsCanon.require(!maxOrder.isEmpty, "mandate: no sellable asset")290 try AgentsCanon.require(expiresAt > createdAt && expiresAt - createdAt <= Self.maxDays * 86_400, "mandate: validity above \(Self.maxDays) days")291 }292293 /** The backend's field list: asset list and both maps in sorted order. */294 public func fields() -> [(String, String)] {295 var f: [(String, String)] = [("v", "1"), ("mandateId", mandateId), ("keyId", keyId), ("vaultIndex", String(vaultIndex)), ("vault", vault), ("network", network), ("provider", provider),296 ("assets", AgentsCanon.sorted(assets).joined(separator: ","))]297 for k in AgentsCanon.sorted(Array(maxOrder.keys)) { f.append(("maxOrder.\(k)", maxOrder[k]!)) }298 for k in AgentsCanon.sorted(Array(maxDaily.keys)) { f.append(("maxDaily.\(k)", maxDaily[k]!)) }299 f += [("maxOrdersPerDay", String(maxOrdersPerDay)), ("maxSlippageBps", String(maxSlippageBps)), ("createdAt", String(createdAt)), ("expiresAt", String(expiresAt)),300 ("strategySha256", strategySha256), ("label", label)]301 return f302 }303 public func canonicalBytes() throws -> Data { AgentsCanon.frame(Self.domain, fields()) }304}305306// MARK: SPW-VENUE-MANDATE-v1 — the derivative mandate of a live perp agent307308/**309 The mandate the isolated signer stores and enforces for a perp agent on ONE Hyperliquid account: instruments with their leverage and310 worst-case position, order notional, gross exposure, order rates, daily turnover, a floor on the account value (below it only cancels311 and reduce-only orders are signed) and an expiry. It extends a venue authorization and dies with it. After it ends, cancels and312 reduce-only orders are still signed for 24 hours (`windDownSeconds`), never new exposure.313 */314public struct AgentVenueMandate: PasskeyApprovable, Equatable {315 public static let domain = "SPW-VENUE-MANDATE-v1"316 public static let maxDays = 30317 public static let windDownSeconds = 86_400318319 public struct Instrument: Sendable, Equatable {320 public let instrument: String321 public let maxLeverage: Int322 /** Canonical decimal, in the venue's collateral (USDC). */323 public let maxPositionNotional: String324 }325 public let mandateId, authorizationId, keyId, venue, network, account, agentAddress, strategySha256, agentId: String326 public let instruments: [Instrument]327 public let maxOrderNotional, maxGrossExposure: String328 public let maxOrdersPerDay, maxOrdersPerHour: Int329 public let maxDailyTurnover, floorEquity: String330 public let maxPriceDeviationBps: Int331 /** Unix seconds. */332 public let createdAt, expiresAt: Int333 /** SHA-256 of the jurisdiction acknowledgement text displayed at approval. */334 public let ackSha256: String335 public let served: JSONValue336337 public var expiry: Date { Date(timeIntervalSince1970: TimeInterval(expiresAt)) }338 public var windDownEnd: Date { expiry.addingTimeInterval(TimeInterval(Self.windDownSeconds)) }339 /** `testnet`: the money is not real. */340 public var isMainnet: Bool { network == "mainnet" }341 public var maxLeverage: Int { instruments.map(\.maxLeverage).max() ?? 0 }342343 public init(served json: JSONValue) throws {344 var o = try StrictObject(json, path: "mandate")345 guard try o.int("v") == 1 else { throw ApprovalError.unsupported("mandate version") }346 mandateId = try o.match("mandateId", AgentsCanon.uuid); authorizationId = try o.match("authorizationId", AgentsCanon.uuid)347 keyId = try o.string("keyId"); try AgentsCanon.require((8...80).contains(keyId.utf16.count), "mandate.keyId length")348 venue = try o.string("venue"); try AgentsCanon.require(venue == "hyperliquid", "mandate.venue \(venue)")349 network = try o.string("network"); try AgentsCanon.require(network == "mainnet" || network == "testnet", "mandate.network \(network)")350 account = try o.match("account", AgentsCanon.lowerAddress); agentAddress = try o.match("agentAddress", AgentsCanon.lowerAddress)351 strategySha256 = try o.match("strategySha256", AgentsCanon.sha); agentId = try o.match("agentId", AgentsCanon.agentId)352 instruments = try o.array("instruments").enumerated().map { k, v in353 var i = try StrictObject(v, path: "mandate.instruments.\(k)")354 let x = Instrument(instrument: try i.match("instrument", AgentsCanon.instrument), maxLeverage: try i.int("maxLeverage", in: 1...20),355 maxPositionNotional: try AgentsCanon.positive(try i.string("maxPositionNotional"), "mandate.instruments.\(k).maxPositionNotional"))356 try i.finish()357 return x358 }359 try AgentsCanon.require((1...8).contains(instruments.count), "mandate.instruments count")360 try AgentsCanon.require(Set(instruments.map(\.instrument)).count == instruments.count, "mandate.instruments holds a duplicate")361 maxOrderNotional = try AgentsCanon.positive(try o.string("maxOrderNotional"), "mandate.maxOrderNotional")362 maxGrossExposure = try AgentsCanon.positive(try o.string("maxGrossExposure"), "mandate.maxGrossExposure")363 maxOrdersPerDay = try o.int("maxOrdersPerDay", in: 1...500); maxOrdersPerHour = try o.int("maxOrdersPerHour", in: 1...60)364 maxDailyTurnover = try AgentsCanon.positive(try o.string("maxDailyTurnover"), "mandate.maxDailyTurnover")365 floorEquity = try AgentsCanon.positive(try o.string("floorEquity"), "mandate.floorEquity")366 maxPriceDeviationBps = try o.int("maxPriceDeviationBps", in: 10...2000)367 createdAt = try o.positiveInt("createdAt"); expiresAt = try o.positiveInt("expiresAt")368 ackSha256 = try o.match("ackSha256", AgentsCanon.sha)369 try o.finish()370 served = json371 try AgentsCanon.require(expiresAt > createdAt && expiresAt - createdAt <= Self.maxDays * 86_400, "mandate: validity above \(Self.maxDays) days")372 }373374 public func fields() -> [(String, String)] {375 let inst = instruments.sorted { Intent.codeUnitOrder($0.instrument, $1.instrument) }376 return [("v", "1"), ("mandateId", mandateId), ("authorizationId", authorizationId), ("keyId", keyId), ("venue", venue), ("network", network), ("account", account),377 ("agentAddress", agentAddress), ("strategySha256", strategySha256), ("agentId", agentId),378 ("instruments", inst.map { "\($0.instrument)|\($0.maxLeverage)|\($0.maxPositionNotional)" }.joined(separator: ",")),379 ("maxOrderNotional", maxOrderNotional), ("maxGrossExposure", maxGrossExposure), ("maxOrdersPerDay", String(maxOrdersPerDay)), ("maxOrdersPerHour", String(maxOrdersPerHour)),380 ("maxDailyTurnover", maxDailyTurnover), ("floorEquity", floorEquity), ("maxPriceDeviationBps", String(maxPriceDeviationBps)),381 ("createdAt", String(createdAt)), ("expiresAt", String(expiresAt)), ("ackSha256", ackSha256)]382 }383 public func canonicalBytes() throws -> Data { AgentsCanon.frame(Self.domain, fields()) }384}385386// MARK: SPW-VENUE-QUOTING-MANDATE-v1 — the quoting mandate of a live market-making agent387388/**389 The mandate under which a market-making engine keeps two-sided POST-ONLY quotes resting on a Hyperliquid account. Ported so that a390 screen can show and re-hash what the signer holds (`GET /mm/agents/:id` → `mandate`). It is created and approved through the trading391 mandates routes (`/api/v1/mandates`), which belong to another module of this package: there is no approve function for it here.392 */393public struct AgentQuotingMandate: PasskeyApprovable, Equatable {394 public static let domain = "SPW-VENUE-QUOTING-MANDATE-v1"395 public static let maxDays = 7396397 public struct Instrument: Sendable, Equatable {398 public let instrument: String399 public let maxLeverage: Int400 public let maxQuoteNotional: String401 public let maxRestingPerSide: Int402 public let maxRestingNotionalPerSide, maxInventoryNotional: String403 }404 public struct Rate: Sendable, Equatable {405 public let burstActions, actionsPerMinute, ordersPerHour, ordersPerDay: Int406 public let dailyTurnover: String407 }408 public let mandateId, authorizationId, keyId, venue, network, account, agentAddress, strategySha256, agentId: String409 public let instruments: [Instrument]410 public let maxRestingTotal: Int411 public let maxGrossExposure: String412 public let minHalfSpreadBps, maxDistanceBps, maxReduceDeviationBps: Int413 public let floorEquity: String414 public let rate: Rate415 /** The venue's dead man's switch must be armed, never further away than this. */416 public let deadManSeconds: Int417 public let createdAt, expiresAt: Int418 public let ackSha256: String419 public let served: JSONValue420421 public var expiry: Date { Date(timeIntervalSince1970: TimeInterval(expiresAt)) }422 public var isMainnet: Bool { network == "mainnet" }423424 public init(served json: JSONValue) throws {425 var o = try StrictObject(json, path: "mandate")426 guard try o.int("v") == 1 else { throw ApprovalError.unsupported("mandate version") }427 mandateId = try o.match("mandateId", AgentsCanon.uuid); authorizationId = try o.match("authorizationId", AgentsCanon.uuid)428 keyId = try o.string("keyId"); try AgentsCanon.require((8...80).contains(keyId.utf16.count), "mandate.keyId length")429 venue = try o.string("venue"); try AgentsCanon.require(venue == "hyperliquid", "mandate.venue \(venue)")430 network = try o.string("network"); try AgentsCanon.require(network == "mainnet" || network == "testnet", "mandate.network \(network)")431 account = try o.match("account", AgentsCanon.lowerAddress); agentAddress = try o.match("agentAddress", AgentsCanon.lowerAddress)432 strategySha256 = try o.match("strategySha256", AgentsCanon.sha); agentId = try o.match("agentId", AgentsCanon.agentId)433 instruments = try o.array("instruments").enumerated().map { k, v in434 var i = try StrictObject(v, path: "mandate.instruments.\(k)")435 let p = "mandate.instruments.\(k)"436 let x = Instrument(instrument: try i.match("instrument", AgentsCanon.instrument), maxLeverage: try i.int("maxLeverage", in: 1...10),437 maxQuoteNotional: try AgentsCanon.positive(try i.string("maxQuoteNotional"), "\(p).maxQuoteNotional"), maxRestingPerSide: try i.int("maxRestingPerSide", in: 1...5),438 maxRestingNotionalPerSide: try AgentsCanon.positive(try i.string("maxRestingNotionalPerSide"), "\(p).maxRestingNotionalPerSide"),439 maxInventoryNotional: try AgentsCanon.positive(try i.string("maxInventoryNotional"), "\(p).maxInventoryNotional"))440 try i.finish()441 return x442 }443 try AgentsCanon.require((1...3).contains(instruments.count), "mandate.instruments count")444 try AgentsCanon.require(Set(instruments.map(\.instrument)).count == instruments.count, "mandate.instruments holds a duplicate")445 maxRestingTotal = try o.int("maxRestingTotal", in: 1...20)446 maxGrossExposure = try AgentsCanon.positive(try o.string("maxGrossExposure"), "mandate.maxGrossExposure")447 minHalfSpreadBps = try o.int("minHalfSpreadBps", in: 1...499); maxDistanceBps = try o.int("maxDistanceBps", in: 2...500); maxReduceDeviationBps = try o.int("maxReduceDeviationBps", in: 10...300)448 floorEquity = try AgentsCanon.positive(try o.string("floorEquity"), "mandate.floorEquity")449 var r = try o.required("rate")450 rate = Rate(burstActions: try r.int("burstActions", in: 1...20), actionsPerMinute: try r.int("actionsPerMinute", in: 1...60), ordersPerHour: try r.int("ordersPerHour", in: 1...3600),451 ordersPerDay: try r.int("ordersPerDay", in: 1...20_000), dailyTurnover: try AgentsCanon.positive(try r.string("dailyTurnover"), "mandate.rate.dailyTurnover"))452 try r.finish()453 deadManSeconds = try o.int("deadManSeconds", in: 10...120)454 createdAt = try o.positiveInt("createdAt"); expiresAt = try o.positiveInt("expiresAt")455 ackSha256 = try o.match("ackSha256", AgentsCanon.sha)456 try o.finish()457 served = json458 try AgentsCanon.require(expiresAt > createdAt && expiresAt - createdAt <= Self.maxDays * 86_400, "mandate: validity above \(Self.maxDays) days")459 }460461 public func fields() -> [(String, String)] {462 let inst = instruments.sorted { Intent.codeUnitOrder($0.instrument, $1.instrument) }463 return [("v", "1"), ("mandateId", mandateId), ("authorizationId", authorizationId), ("keyId", keyId), ("venue", venue), ("network", network), ("account", account),464 ("agentAddress", agentAddress), ("strategySha256", strategySha256), ("agentId", agentId),465 ("instruments", inst.map { "\($0.instrument)|\($0.maxLeverage)|\($0.maxQuoteNotional)|\($0.maxRestingPerSide)|\($0.maxRestingNotionalPerSide)|\($0.maxInventoryNotional)" }.joined(separator: ",")),466 ("maxRestingTotal", String(maxRestingTotal)), ("maxGrossExposure", maxGrossExposure),467 ("minHalfSpreadBps", String(minHalfSpreadBps)), ("maxDistanceBps", String(maxDistanceBps)), ("maxReduceDeviationBps", String(maxReduceDeviationBps)), ("floorEquity", floorEquity),468 ("rate.burstActions", String(rate.burstActions)), ("rate.actionsPerMinute", String(rate.actionsPerMinute)), ("rate.ordersPerHour", String(rate.ordersPerHour)), ("rate.ordersPerDay", String(rate.ordersPerDay)),469 ("rate.dailyTurnover", rate.dailyTurnover), ("deadManSeconds", String(deadManSeconds)),470 ("createdAt", String(createdAt)), ("expiresAt", String(expiresAt)), ("ackSha256", ackSha256)]471 }472 public func canonicalBytes() throws -> Data { AgentsCanon.frame(Self.domain, fields()) }473}474475// MARK: SPW-TRADING-MANDATE-v1 — the trading mandate a live perp agent's derivative mandate is compiled from476477/**478 The execution layer's mandate of a principal (here: an agent). Its hash is never a passkey challenge by itself: the approval intent479 (`AgentMandateApprovalIntent`) names it, and the API enforces the fields the signer cannot (daily loss, stop conditions, fee cap).480 Ported so that the hash the second passkey prompt commits to is recomputed from the fields displayed.481 */482public struct AgentTradingMandate: Sendable, Equatable {483 public static let domain = "SPW-TRADING-MANDATE-v1"484485 public enum Account: Sendable, Equatable {486 case vault(network: String, vaultIndex: Int, address: String)487 case venueAccount(venue: String, network: String, account: String)488 var key: String {489 switch self {490 case .vault(let n, let i, let a): "vault|\(n)|\(i)|\(a)"491 case .venueAccount(let v, let n, let a): "venue_account|\(v)|\(n)|\(a)"492 }493 }494 }495 /** Declarative: when one is met the mandate takes no new risk (strictly reducing orders stay possible). */496 public enum StopCondition: Sendable, Equatable {497 case lossAtLeast(usd: String)498 case drawdownAtLeast(bps: Int)499 case consecutiveRejectsAtLeast(count: Int)500 case dataStaleAtLeast(ms: Int)501 case signerUnreachableAtLeast(ms: Int)502 var key: String {503 switch self {504 case .lossAtLeast(let usd): "loss_gte|\(usd)"505 case .drawdownAtLeast(let bps): "drawdown_gte|\(bps)"506 case .consecutiveRejectsAtLeast(let n): "consecutive_rejects_gte|\(n)"507 case .dataStaleAtLeast(let ms): "data_stale_gte|\(ms)"508 case .signerUnreachableAtLeast(let ms): "signer_unreachable_gte|\(ms)"509 }510 }511 }512 public let mandateId: String513 public let principalKind, principalId: String514 public let accounts: [Account]515 public let venues, networks, instruments, marketKinds, orderTypes: [String]516 /** Canonical decimals, USD. */517 public let maxCapitalUsd, maxOrderNotionalUsd, maxPositionNotionalUsd, maxLeverage, maxDailyLossUsd, floorEquityUsd: String518 /** Unix seconds. */519 public let createdAt, notBefore, notAfter: Int520 public let perMinute, perHour, perDay: Int521 public let maxSlippageBps: Int522 public let maxFeeUsd: String523 public let stopConditions: [StopCondition]524 /** `paper` or `live`. */525 public let mode: String526 public let strategySha256: String?527 public let label: String528 public let served: JSONValue529530 public var agentMode: AgentMode { AgentMode(server: mode) }531 public var expiry: Date { Date(timeIntervalSince1970: TimeInterval(notAfter)) }532533 public init(served json: JSONValue) throws {534 let id = "^[a-z0-9][a-z0-9-]{0,31}$"535 var o = try StrictObject(json, path: "tradingMandate")536 guard try o.int("v") == 1 else { throw ApprovalError.unsupported("trading mandate version") }537 mandateId = try o.match("mandateId", AgentsCanon.uuid)538 var p = try o.required("principal")539 principalKind = try p.string("kind"); try AgentsCanon.require(principalKind == "agent" || principalKind == "api_key", "tradingMandate.principal.kind")540 principalId = try p.match("id", AgentsCanon.agentId)541 try p.finish()542 accounts = try o.array("accounts").enumerated().map { k, v in543 var a = try StrictObject(v, path: "tradingMandate.accounts.\(k)")544 let acct: Account545 switch try a.string("kind") {546 case "vault": acct = .vault(network: try a.match("network", id), vaultIndex: try a.int("vaultIndex", in: 1...100_000), address: try a.string("address"))547 case "venue_account": acct = .venueAccount(venue: try a.match("venue", id), network: try a.match("network", id), account: try a.string("account"))548 default: throw ApprovalError.unsupported("tradingMandate.accounts.\(k).kind")549 }550 try a.finish()551 return acct552 }553 try AgentsCanon.require((1...8).contains(accounts.count), "tradingMandate.accounts count")554 venues = try o.strings("venues"); networks = try o.strings("networks"); instruments = try o.strings("instruments")555 marketKinds = try o.strings("marketKinds"); orderTypes = try o.strings("orderTypes")556 try AgentsCanon.require(venues.allSatisfy { AgentsCanon.matches($0, id) } && networks.allSatisfy { AgentsCanon.matches($0, id) } && (1...8).contains(venues.count) && (1...8).contains(networks.count), "tradingMandate.venues / networks")557 try AgentsCanon.require((1...24).contains(instruments.count) && instruments.allSatisfy { AgentsCanon.matches($0, #"^[a-z0-9][a-z0-9-]{0,31}:(\*|[A-Za-z0-9._/-]{1,60})$"#) }, "tradingMandate.instruments")558 // the separator of the joined lists never occurs in a value the schema accepts; anything else is refused rather than serialized ambiguously559 try AgentsCanon.require(!marketKinds.isEmpty && !orderTypes.isEmpty && (marketKinds + orderTypes).allSatisfy { AgentsCanon.matches($0, "^[a-z_]{1,32}$") }, "tradingMandate.marketKinds / orderTypes")560 maxCapitalUsd = try AgentsCanon.positive(try o.string("maxCapitalUsd"), "tradingMandate.maxCapitalUsd")561 maxOrderNotionalUsd = try AgentsCanon.positive(try o.string("maxOrderNotionalUsd"), "tradingMandate.maxOrderNotionalUsd")562 maxPositionNotionalUsd = try AgentsCanon.positive(try o.string("maxPositionNotionalUsd"), "tradingMandate.maxPositionNotionalUsd")563 maxLeverage = try AgentsCanon.positive(try o.string("maxLeverage"), "tradingMandate.maxLeverage")564 maxDailyLossUsd = try AgentsCanon.positive(try o.string("maxDailyLossUsd"), "tradingMandate.maxDailyLossUsd")565 floorEquityUsd = try AgentsCanon.nonNegative(try o.string("floorEquityUsd"), "tradingMandate.floorEquityUsd")566 createdAt = try o.positiveInt("createdAt"); notBefore = try o.positiveInt("notBefore"); notAfter = try o.positiveInt("notAfter")567 var f = try o.required("frequency")568 perMinute = try f.int("perMinute", in: 1...600); perHour = try f.int("perHour", in: 1...10_000); perDay = try f.int("perDay", in: 1...500)569 try f.finish()570 maxSlippageBps = try o.int("maxSlippageBps", in: 1...2000)571 maxFeeUsd = try AgentsCanon.nonNegative(try o.string("maxFeeUsd"), "tradingMandate.maxFeeUsd")572 stopConditions = try o.array("stopConditions").enumerated().map { k, v in573 var s = try StrictObject(v, path: "tradingMandate.stopConditions.\(k)")574 let c: StopCondition575 switch try s.string("kind") {576 case "loss_gte": c = .lossAtLeast(usd: try AgentsCanon.positive(try s.string("usd"), "tradingMandate.stopConditions.\(k).usd"))577 case "drawdown_gte": c = .drawdownAtLeast(bps: try s.int("bps", in: 1...10_000))578 case "consecutive_rejects_gte": c = .consecutiveRejectsAtLeast(count: try s.int("count", in: 1...1000))579 case "data_stale_gte": c = .dataStaleAtLeast(ms: try s.positiveInt("ms"))580 case "signer_unreachable_gte": c = .signerUnreachableAtLeast(ms: try s.positiveInt("ms"))581 default: throw ApprovalError.unsupported("tradingMandate.stopConditions.\(k).kind")582 }583 try s.finish()584 return c585 }586 try AgentsCanon.require(stopConditions.count <= 10, "tradingMandate.stopConditions count")587 mode = try o.string("mode"); try AgentsCanon.require(mode == "paper" || mode == "live", "tradingMandate.mode \(mode)")588 switch o.raw("strategySha256") {589 case .some(.null): strategySha256 = nil590 case .some(.string(let s)) where AgentsCanon.matches(s, AgentsCanon.sha): strategySha256 = s591 default: throw ApprovalError.unsupported("tradingMandate.strategySha256")592 }593 label = try o.string("label"); try AgentsCanon.require((1...60).contains(label.utf16.count), "tradingMandate.label length")594 try o.finish()595 served = json596 }597598 public func fields() -> [(String, String)] {599 func list(_ xs: [String]) -> String { AgentsCanon.sorted(xs).joined(separator: ",") }600 return [("v", "1"), ("mandateId", mandateId), ("principal.kind", principalKind), ("principal.id", principalId),601 ("accounts", list(accounts.map(\.key))), ("venues", list(venues)), ("networks", list(networks)),602 ("instruments", list(instruments)), ("marketKinds", list(marketKinds)), ("orderTypes", list(orderTypes)),603 ("maxCapitalUsd", maxCapitalUsd), ("maxOrderNotionalUsd", maxOrderNotionalUsd), ("maxPositionNotionalUsd", maxPositionNotionalUsd), ("maxLeverage", maxLeverage),604 ("maxDailyLossUsd", maxDailyLossUsd), ("floorEquityUsd", floorEquityUsd),605 ("createdAt", String(createdAt)), ("notBefore", String(notBefore)), ("notAfter", String(notAfter)),606 ("frequency.perMinute", String(perMinute)), ("frequency.perHour", String(perHour)), ("frequency.perDay", String(perDay)),607 ("maxSlippageBps", String(maxSlippageBps)), ("maxFeeUsd", maxFeeUsd), ("stopConditions", list(stopConditions.map(\.key))),608 ("mode", mode), ("strategySha256", strategySha256 ?? ""), ("label", label)]609 }610 public func canonicalBytes() -> Data { AgentsCanon.frame(Self.domain, fields()) }611 /** `tradingMandateHashHex`: what the approval intent names. */612 public func hashHex() -> String { SHA256Digest.hash(canonicalBytes()).hex }613}614615// MARK: SPW-TRADING-MANDATE-APPROVAL-v1 — the API's own passkey step of a live mandate616617/**618 The second passkey prompt of a live mandate: an intent that names the FULL trading mandate hash and the hash of the signer mandate619 compiled from it. Its challenge is `SHA-256("SPW-TRADING-MANDATE-APPROVAL-v1\n" + stableJson(intent))`. Verified by the API (it620 protects the stored record against alteration); the signer judges the first prompt.621 */622public struct AgentMandateApprovalIntent: PasskeyApprovable, Equatable {623 public static let domain = "SPW-TRADING-MANDATE-APPROVAL-v1"624625 public let kind, mandateId, tradingMandateHash, principal, mode: String626 /** `SPW-VENUE-MANDATE-v1` or `SPW-VENUE-QUOTING-MANDATE-v1`. */627 public let signerShape: String628 public let signerMandateHash: String629 /** Quoting mandates only. */630 public let quotingSectionHash: String?631 public let nonce: String632 /** Unix MILLISECONDS. */633 public let createdAt, expiresAt: Int634 public let served: JSONValue635636 public var expiry: Date { Date(timeIntervalSince1970: TimeInterval(expiresAt) / 1000) }637638 public init(served json: JSONValue) throws {639 var o = try StrictObject(json, path: "binding.intent")640 guard try o.int("v") == 1 else { throw ApprovalError.unsupported("approval intent version") }641 kind = try o.string("kind"); try AgentsCanon.require(kind == "trading_mandate_approval", "binding.intent.kind \(kind)")642 mandateId = try o.match("mandateId", AgentsCanon.uuid)643 tradingMandateHash = try o.match("tradingMandateHash", AgentsCanon.sha)644 principal = try o.string("principal")645 mode = try o.string("mode"); try AgentsCanon.require(mode == "live", "binding.intent.mode \(mode)")646 var s = try o.required("signer")647 signerShape = try s.string("shape"); signerMandateHash = try s.match("mandateHash", AgentsCanon.sha)648 try s.finish()649 quotingSectionHash = try o.optionalString("quotingSectionHash")650 if let q = quotingSectionHash { try AgentsCanon.require(AgentsCanon.matches(q, AgentsCanon.sha), "binding.intent.quotingSectionHash") }651 nonce = try o.string("nonce")652 createdAt = try o.positiveInt("createdAt"); expiresAt = try o.positiveInt("expiresAt")653 try o.finish()654 served = json655 }656 public func canonicalBytes() throws -> Data { Data((Self.domain + "\n" + (try AgentsCanon.stableJSON(served, "binding.intent"))).utf8) }657}658659enum SHA256Digest {660 static func hash(_ data: Data) -> Data { Data(SHA256.hash(data: data)) }661}662