SPB Git

Repository Public

NFTTransferModels.swift 12.3 KB 260 lines swift

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

Theme