SPB Git

Repository Public

PlanModels.swift 12.2 KB 239 lines swift

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

Theme