SPB Git

Repository Public

AgentsCanonical.swift 40.4 KB 662 lines swift

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
Files main
Menu

Theme