Repository Public
1// SP Wallet Core2// File: Sources/SPWalletCore/Domains/NFT/NFTTransferModels.swift3// Description: Models of NFT transfers, of the NFT destination allow-list and of the Bitcoin outpoint lock list4// (services/api/src/nft/transfer-routes.ts, transfer.ts, utxo.ts): the review the owner reads, the proposal an NFT5// transfer is (a row of the same table and states as a fund transfer), the requests, and the prepared approvals —6// which can only be built by `NFTAPI` after the served object was checked against the request and bound to the challenge.7//8// Author: Simon-Pierre Boucher9// Contact: contact@spboucher.ai10import Foundation1112/** What the server established and simulated for one NFT transfer: the sheet the owner reads before the passkey prompt. */13public struct NFTReview: Codable, Sendable, Hashable {14 public struct Fee: Codable, Sendable, Hashable {15 /** Base units of the network's native coin. */16 public let estimate: String17 public let max: String18 public let symbol: String19 public let decimals: Int20 /** Solana: lamports locked as rent in accounts this transfer creates (not a fee). */21 public let rent: String?22 public var maxDisplay: String? { (try? BaseUnits(max))?.formatted(decimals: decimals) }23 public var estimateDisplay: String? { (try? BaseUnits(estimate))?.formatted(decimals: decimals) }24 }25 public struct Change: Codable, Sendable, Hashable {26 /** English sentence; `code` (+ `params`, `beforeCode`, `afterCode`) is what the interface translates. */27 public let what: String28 public let before: String29 public let after: String30 public let code: String?31 public let params: [String: String]?32 public let beforeCode: String?33 public let afterCode: String?34 }35 public struct Simulation: Codable, Sendable, Hashable {36 public let ok: Bool37 public let detail: String38 /** Gas / compute units the simulation used. */39 public let used: String?40 public let changes: [Change]41 }42 public struct Verified: Codable, Sendable, Hashable {43 public let standard: String44 public let ownership: String45 /** Number of RPC endpoints that had to answer and agree. */46 public let endpoints: Int47 public let at: Date?48 }49 public struct Account: Codable, Sendable, Hashable { public let role: String; public let address: String; public let derived: String }50 /** What the CREATOR declares — UNTRUSTED, shown small and labelled unverified, never used to build anything. */51 public struct CreatorMetadata: Codable, Sendable, Hashable {52 public let name: String?53 public let collectionName: String?54 /** Media proxy id. */55 public let imageId: String?56 }5758 public let key: String59 public let network: String60 public let networkName: String61 public let standard: NFTStandard62 /** The one call the transfer is made with. */63 public let method: String64 /** Contract (EVM) / mint or asset address (Solana). */65 public let asset: String66 public let tokenId: String?67 public let quantity: String68 public let program: String69 public let from: String70 public let to: String71 /** `account`, `contract`, `new_account`. */72 public let toKind: String73 public let fee: Fee74 /** Codes the owner must read before sending (`contract_recipient`, `creates_token_account`, `mutable_metadata`, `pnft_rule_set`, `semi_fungible`, …). */75 public let warnings: [String]76 public let simulation: Simulation77 public let verified: Verified78 /** Solana: every account of the main instruction, by role. */79 public let accounts: [Account]80 public let creatorMetadata: CreatorMetadata?81}8283/** An NFT transfer: a proposal of kind `nft` (same states, expiry and finality rules as a fund transfer) with its review. */84public struct NFTTransfer: Codable, Sendable, Hashable, Identifiable {85 /** `asset` is the contract / mint, `symbol` is `NFT`, `decimals` 0 and `amount` the quantity. */86 public let proposal: Proposal87 public let review: NFTReview?8889 private enum CodingKeys: String, CodingKey { case nft }90 public init(from decoder: Decoder) throws {91 proposal = try Proposal(from: decoder)92 review = try decoder.container(keyedBy: CodingKeys.self).decodeIfPresent(NFTReview.self, forKey: .nft)93 }94 public func encode(to encoder: Encoder) throws { try proposal.encode(to: encoder) }9596 public var id: String { proposal.id }97 /** Only `finalized` is a success; `not_broadcast` means signed and deliberately not relayed — never shown as sent. */98 public var state: ProposalState { proposal.state }99}100101/** `GET /nfts/transfer/verdict`: the per-asset verdict, what the signer says about NFT transfers right now, and whether this server relays. */102public struct NFTTransferVerdictAnswer: Codable, Sendable, Hashable {103 public struct Signer: Codable, Sendable, Hashable {104 public let reachable: Bool105 public let halted: Bool?106 /** False for a signer that predates NFT transfers: nothing can be signed, so nothing is prepared. */107 public let supportsNft: Bool?108 public let signedToday: Int?109 public let maxPerDay: Int?110 public let allowlistOnly: Bool?111 public let maxErc1155Quantity: String?112 }113 public let transferable: Bool114 public let blockedBy: [String]115 public let warnings: [String]116 public let standard: NFTStandard117 public let route: String?118 public let signer: Signer119 /** False when this server signs but deliberately does not relay (test stacks): an approved transfer ends `not_broadcast`. */120 public let broadcast: Bool?121}122123/** What the owner asks: send this asset (by its key) to this destination. The standard is the one the item page showed. */124public struct NFTTransferRequest: Sendable, Equatable {125 public let key: String126 /** Checked against the intent, never sent: the server re-establishes the standard on-chain. */127 public let standard: NFTTransferStandard128 public let to: String129 /** Units to move: "1" for every standard except ERC-1155. */130 public let quantity: String131 /** The wallet's own address on that network when the caller knows it (`WalletAPI.accounts`): then checked against the intent. */132 public let from: String?133134 public init(key: String, standard: NFTTransferStandard, to: String, quantity: String = "1", from: String? = nil) {135 self.key = key; self.standard = standard; self.to = to.trimmingCharacters(in: .whitespacesAndNewlines); self.quantity = quantity; self.from = from136 }137 /** From the item on screen. Throws `ApprovalError.unsupported` when no transfer exists for its standard. */138 public init(item: NFTAsset, to: String, quantity: String = "1") throws {139 guard let std = item.standard.transferStandard else { throw ApprovalError.unsupported("no transfer is built for \(item.standard.rawValue)") }140 self.init(key: item.key, standard: std, to: to, quantity: quantity, from: item.ownership.heldByWallet ? item.ownerAddress : nil)141 }142}143144/** A prepared NFT transfer: the proposal, the review, and the exact intent bound to the verified challenge. Only `NFTAPI` builds it. */145public struct NFTTransferApproval: Sendable {146 public let transfer: NFTTransfer147 /** The review of this answer (the same object the proposal stores). */148 public let review: NFTReview?149 public let approval: VerifiedApproval<NFTIntent>150 /** True when the same Idempotency-Key had already prepared this transfer: the same proposal and challenge were answered again. */151 public let replayed: Bool152 public var intent: NFTIntent { approval.object }153}154155// MARK: - allow-list156157/** The signer's own list of destinations allowed to receive NFTs, and whether its policy restricts NFT transfers to it. */158public struct NFTAllowList: Codable, Sendable, Hashable {159 public struct Entry: Codable, Sendable, Hashable {160 public let network: String161 public let address: String162 /** Unix seconds. */163 public let approvedAt: Int?164 }165 /** True when the signer's policy only signs NFT transfers to listed destinations. */166 public let allowlistOnly: Bool167 public let entries: [Entry]168 /** False for a signer that predates NFT transfers. */169 public let supported: Bool170}171172public struct NFTAllowRequest: Codable, Sendable, Equatable {173 /** An EVM network or `solana`. */174 public let network: String175 public let address: String176 public let action: NFTAllowIntent.Action177 public init(network: String, address: String, action: NFTAllowIntent.Action) {178 self.network = network; self.address = address.trimmingCharacters(in: .whitespacesAndNewlines); self.action = action179 }180}181182/** The signer's answer to an approved allow-list change. */183public struct NFTAllowResult: Codable, Sendable, Hashable {184 public let network: String185 public let address: String186 public let action: String187 /** Entries in the list after the change. */188 public let entries: Int189 /** Hex SHA-256 of the canonical object the signer accepted. */190 public let hash: String191}192193// MARK: - Bitcoin-style outpoint locks194195/** One coin of the wallet and why it is (or is not) kept out of ordinary sends. */196public struct UTXOLockRow: Codable, Sendable, Hashable, Identifiable {197 public struct SignerLock: Codable, Sendable, Hashable { public let reason: String; public let at: Int }198 public struct Ord: Codable, Sendable, Hashable { public let inscriptions: [String]; public let runes: [String] }199 public let txid: String200 public let vout: Int201 /** `<txid>:<vout>`. */202 public let outpoint: String203 /** Base units (satoshis). */204 public let value: Int205 /** Set when the owner locked the outpoint on the signer (authoritative: the signer refuses it as an input). */206 public let signerLock: SignerLock?207 /** What the ord server reports on this output, when one is configured. */208 public let ord: Ord?209 /** `signer_locked`, `ord_inscription`, `ord_rune`, `ord_unindexed`, `ord_unlisted`, `ord_unavailable`, `heuristic_small`, `heuristic_envelope`. Empty = spendable by an ordinary send. */210 public let excludedBy: [String]211 /** True when the only reasons are heuristic and the owner declared the output an ordinary coin. */212 public let reviewed: Bool213 public let spendable: Bool214 public var id: String { outpoint }215}216217/** `GET /utxo-locks`: the wallet's coins on one Bitcoin-style network, classified. No inscription is listed or transferable. */218public struct UTXOLocksView: Codable, Sendable, Hashable {219 public struct StaleLock: Codable, Sendable, Hashable { public let outpoint: String; public let reason: String; public let at: Int }220 public let network: String221 public let address: String222 /** `ord` (an ord server decides), `heuristic` (size / envelope flags only — NOT a detection), `locks_only`, `ord_unavailable` (fail closed: nothing is spendable). */223 public let mode: String224 public let ordConfigured: Bool225 public let ordHost: String?226 public let ordError: String?227 /** False for a signer that predates outpoint locks. */228 public let signerSupportsLocks: Bool229 public let utxos: [UTXOLockRow]230 /** Locks whose outpoint is no longer among the wallet's coins: shown, removable. */231 public let staleLocks: [StaleLock]232 public let symbol: String233 public let decimals: Int234 /** `not_supported` as served: this wallet builds no inscription transfer. */235 public let transfer: String?236 public let transferReason: String?237}238239public struct UTXOLockRequest: Codable, Sendable, Equatable {240 public let network: String241 public let action: UTXOLockIntent.Action242 public let reason: UTXOLockIntent.Reason243 /** `<txid>:<vout>` strings, 1 to 100. */244 public let outpoints: [String]245 public init(network: String, action: UTXOLockIntent.Action, reason: UTXOLockIntent.Reason = .owner, outpoints: [String]) {246 self.network = network; self.action = action; self.reason = reason; self.outpoints = outpoints247 }248}249250/** The signer's answer to an approved lock-list change. */251public struct UTXOLockResult: Codable, Sendable, Hashable {252 public let network: String253 public let action: String254 /** Outpoints whose state changed. */255 public let changed: Int256 /** Outpoints locked on that network after the change. */257 public let locked: Int258 public let hash: String259}260