Repository Public
1// SP Wallet Core2// File: Sources/SPWalletCore/Domains/Swap/PlanModels.swift3// Description: Any-to-any plans (services/api/src/plan-exec.ts, plan-state.ts): a plan is a list of legs, each an ordinary4// proposal (swap, CCTP transfer, THORChain swap) created only when the previous leg has SETTLED and approved with5// its own passkey. A plan never signs and never holds funds; between two legs the funds are an ordinary balance.6//7// Author: Simon-Pierre Boucher8// Contact: contact@spboucher.ai9import Foundation1011/** GET /plans/capabilities: what the wallet can chain today, from the server's pinned tables. */12public struct PlanCapabilities: Codable, Sendable, Hashable {13 public let maxLegs: Int14 /** Network → the provider of the same-network swap executed there. */15 public let swap: [String: String]16 /** Networks between which CCTP moves USDC. */17 public let cctp: [String]18 /** Assets THORChain swaps; `source` = may be the input. */19 public let thorchain: [SwapAsset]20 /** The only intermediate asset of a plan. */21 public let hub: String22}2324public struct PlanRequest: Codable, Sendable, Hashable {25 /** Asset keys (`SwapAsset.key`). */26 public let from: String27 public let to: String28 public let amount: String29 /** 1…300, applied to every leg. */30 public let slippageBps: Int31 public init(from: String, to: String, amount: String, slippageBps: Int = 50) { self.from = from; self.to = to; self.amount = amount; self.slippageBps = slippageBps }32}3334public struct PlanIssue: Codable, Sendable, Hashable {35 /** `insufficient_balance`, `limit_missing`, `limit_per_transfer`, `limit_daily`, `limit_margin`, `below_minimum`, `gas_missing`, `gas_unknown`. */36 public let code: String37 /** A blocking issue makes the plan non-startable; a warning is shown and the leg's own check decides when its turn comes. */38 public let blocking: Bool39 public let leg: Int?40 public let network: String41 public let networkName: String?42 public let symbol: String43 public let need: String44 public let have: String45 public let decimals: Int46 public let needDisplay: String?47 public let haveDisplay: String?48}4950/** One candidate plan of POST /plans/quote (`planView`). "Expected" = every leg at its quote; "worst" = every leg at its guaranteed minimum. */51public struct PlanCandidate: Codable, Sendable, Hashable, Identifiable {52 public struct Fee: Codable, Sendable, Hashable { public let kind: String; public let symbol: String; public let network: String; public let networkName: String?; public let display: String; public let usd: Double?; public let includedInOutput: Bool?; public let estimated: Bool? }53 public struct Leg: Codable, Sendable, Hashable {54 /** `swap`, `bridge`, `xswap`. */55 public let kind: String56 public let via: String57 public let label: String?58 public let speed: String?59 public let from: SwapAsset60 public let to: SwapAsset61 public let venues: [String]?62 public let expectedInDisplay: String63 public let worstInDisplay: String64 public let expectedOutDisplay: String65 public let worstOutDisplay: String66 public let seconds: Double?67 public let fees: [Fee]?68 }69 public struct GasRequirement: Codable, Sendable, Hashable { public let network: String; public let networkName: String?; public let symbol: String; public let needDisplay: String; /** nil = the balance could not be read. */ public let haveDisplay: String?; public let ok: Bool }70 public struct LimitRequirement: Codable, Sendable, Hashable { public let leg: Int; public let network: String?; public let networkName: String?; public let symbol: String; public let needDisplay: String; public let perTransferDisplay: String; public let leftTodayDisplay: String; public let ok: Bool }71 public struct Requirements: Codable, Sendable, Hashable { public let gas: [GasRequirement]; public let limits: [LimitRequirement] }7273 /** The shape of the plan (its legs in order): what POST /plans takes as `plan`. */74 public let id: String75 /** False when a blocking issue prevents starting it. */76 public let executable: Bool77 /** One passkey approval per leg. */78 public let approvals: Int79 public let seconds: Double?80 public let extraFeesUsd: Double?81 public let from: SwapAsset82 public let to: SwapAsset83 public let amountIn: String84 public let amountInDisplay: String85 public let expectedOut: String86 public let expectedOutDisplay: String87 public let worstOut: String88 public let worstOutDisplay: String89 public let expectedUsd: Double?90 public let worstUsd: Double?91 public let inUsd: Double?92 public let legs: [Leg]93 public let requirements: Requirements?94 public let issues: [PlanIssue]95}9697/** POST /plans/quote. Signs nothing, prepares nothing, stores nothing. */98public struct PlanQuote: Codable, Sendable, Hashable {99 public struct NotExecutable: Codable, Sendable, Hashable { /** `same_asset`, `solana_evm_bridge`, `network_without_execution`, `no_executable_path`. */ public let code: String; public let network: String? }100 public struct Skipped: Codable, Sendable, Hashable { public let id: String; public let leg: Int; public let code: String; public let message: String }101 public let from: SwapAsset102 public let to: SwapAsset103 public let amountIn: String104 public let slippageBps: Int105 /** Why no plan exists for this pair, when none does. */106 public let notExecutable: NotExecutable?107 public let plans: [PlanCandidate]108 /** Shapes that had no quote right now, with the leg that failed. */109 public let skipped: [Skipped]110}111112public struct PlanState: ServerCode { public let rawValue: String; public init(rawValue: String) { self.rawValue = rawValue }113 public static let active = PlanState("active"), paused = PlanState("paused"), done = PlanState("done"), stopped = PlanState("stopped") }114115public struct PlanLegState: ServerCode { public let rawValue: String; public init(rawValue: String) { self.rawValue = rawValue }116 /** Its turn has not come. */ public static let pending = PlanLegState("pending")117 /** Can be prepared (the previous leg settled). */ public static let ready = PlanLegState("ready")118 /** A proposal exists and waits for the passkey. */ public static let proposed = PlanLegState("proposed")119 /** Approved and on its way. */ public static let inFlight = PlanLegState("in_flight")120 /** The amount actually received was read from the chain. */ public static let settled = PlanLegState("settled") }121122/** What the owner can do next (`next` of `docView`). Nothing here happens by itself. */123public struct PlanNextAction: ServerCode { public let rawValue: String; public init(rawValue: String) { self.rawValue = rawValue }124 /** The current leg is ready: prepare it (that asks nothing of the passkey yet). */ public static let prepare = PlanNextAction("prepare")125 /** The current leg has a proposal waiting for the passkey. */ public static let approve = PlanNextAction("approve")126 /** A leg is in flight: wait for it to settle. */ public static let wait = PlanNextAction("wait")127 public static let paused = PlanNextAction("paused"), done = PlanNextAction("done"), stopped = PlanNextAction("stopped") }128129/** A plan as shown to the owner (`docView`). */130public struct PlanView: Codable, Sendable, Hashable, Identifiable {131 public struct Holding: Codable, Sendable, Hashable {132 public let key: String133 public let network: String134 public let networkName: String?135 public let asset: String136 public let symbol: String137 public let decimals: Int138 /** How much of that balance belongs to this plan, base units. */139 public let amount: String140 public let amountDisplay: String141 }142 public struct Reason: Codable, Sendable, Hashable { public let code: String; public let params: [String: JSONValue]? }143 public struct Pause: Codable, Sendable, Hashable {144 /** `no_funds`, `floor`, `refused`, `refunded`, `leg_failed`, or the error code of the leg's preparation. */145 public let code: String146 public let message: String147 public let at: Date?148 public let leg: Int149 public let params: [String: JSONValue]?150 public let reason: Reason?151 }152 public struct Estimate: Codable, Sendable, Hashable { public let expectedOutDisplay: String; public let worstOutDisplay: String; public let at: Date? }153 public struct Planned: Codable, Sendable, Hashable { public let expectedInDisplay: String; public let worstInDisplay: String?; public let expectedOutDisplay: String; public let worstOutDisplay: String }154 public struct Actual: Codable, Sendable, Hashable { public let inDisplay: String?; public let outDisplay: String? }155 public struct Attempt: Codable, Sendable, Hashable {156 public let proposalId: String?157 /** `settled`, `failed`, `rejected`, `expired`, `refunded`; nil while the attempt is alive. */158 public let outcome: String?159 public let error: String?160 public let errorCode: String?161 public let errorParams: [String: JSONValue]?162 public let at: Date?163 }164 public struct Leg: Codable, Sendable, Hashable, Identifiable {165 public let index: Int166 public let state: PlanLegState167 /** `swap`, `bridge`, `xswap`. */168 public let kind: String169 public let via: String?170 public let label: String?171 public let speed: String?172 public let from: SwapAsset173 public let to: SwapAsset174 public let seconds: Double?175 /** What the plan showed when it was started or re-planned: information, not a promise. */176 public let planned: Planned177 /** What really happened; nil until it did. */178 public let actual: Actual179 public let proposalId: String?180 public let attempts: [Attempt]181 public let execution: ExecutionStatus?182 public var id: Int { index }183 /** True only when the leg's output was read from the chain. An approved or broadcast leg is not settled. */184 public var isSettled: Bool { state == .settled }185 }186187 public let id: String188 public let state: PlanState189 public let next: PlanNextAction190 /** Index of the current leg. */191 public let current: Int192 public let steps: Int193 public let replans: Int194 public let createdAt: Date?195 public let updatedAt: Date?196 public let from: SwapAsset197 public let to: SwapAsset198 public let amountInDisplay: String199 public let slippageBps: Int?200 /** The owner's overall floor (base units of the destination asset): the plan pauses before a leg when the estimate is below it. */201 public let floor: String?202 public let floorDisplay: String?203 /** Where the funds are now: always the wallet's own address, an ordinary balance. */204 public let holding: Holding205 public let pause: Pause?206 public let estimate: Estimate?207 public let plannedExpectedDisplay: String208 public let plannedWorstDisplay: String209 /** What arrived in the destination asset; nil until the LAST leg settled. */210 public let receivedDisplay: String?211 public let legs: [Leg]212 /** The current leg's proposal, when it has one. */213 public let proposal: Proposal?214215 public var currentLeg: Leg? { legs.indices.contains(current) ? legs[current] : nil }216 /** True only when every leg settled (`state == done`). A stopped plan is finished, not complete. */217 public var isComplete: Bool { state == .done && !legs.isEmpty && legs.allSatisfy(\.isSettled) }218 /** Still running or waiting for a decision. */219 public var isOpen: Bool { state == .active || state == .paused }220}221222/** The answer of POST /plans/:id/prepare after verification. */223public struct PlanLegPreparation: Sendable {224 public let plan: PlanView225 /**226 The leg's proposal with its verified challenge. nil when the server PAUSED the plan instead of preparing the leg227 (no funds, estimate below the floor, the leg's preparation was refused): `plan.pause` says why; nothing was prepared.228 */229 public let operation: PreparedOperation?230}231232/** How POST /plans/:id/retry treats the overall floor. */233public enum PlanFloorChange: Sendable, Hashable {234 case unchanged235 case remove236 /** Decimal text in whole units of the destination asset. */237 case set(String)238}239