SPB Git

Repository Public

NFTMarketModels.swift 18.7 KB 404 lines swift

1// SP Wallet Core2// File: Sources/SPWalletCore/Domains/NFT/NFTMarketModels.swift3// Description: Models of the NFT market READ API (services/api/src/nft/market/routes.ts, service.ts; packages/nft/src/market.ts).4//              One row PER SOURCE: nothing is merged, averaged or picked, and two sources that disagree are two rows and a named5//              contradiction. A market value is a marketplace's statement with its source and its date — never chain truth, and a6//              collection floor is never the value of an item. There is NO market write: every action is served as unavailable7//              with its reason, and that is modelled as served, not assumed.8//9// Author: Simon-Pierre Boucher10// Contact: contact@spboucher.ai11import Foundation1213/** An exact amount of an exactly identified currency. `precision` says how the source gave it. */14public struct NFTMoney: Codable, Sendable, Hashable {15    public let amount: String16    public let currency: NFTCurrency17    /** `exact`: the source gave base units. `source_decimal`: the source gave a decimal number, converted digit by digit. */18    public let precision: String19    public var units: BaseUnits? { try? BaseUnits(amount) }20    /** Exact decimal text in the amount's own currency (no fiat conversion). */21    public var display: String? { units.map { $0.formatted(decimals: currency.decimals) } }22}2324/** One fee line a source reports for an order or a collection — market information, not something this wallet pays. */25public struct NFTMarketFee: Codable, Sendable, Hashable {26    /** `marketplace`, `creator_royalty`, `other`. */27    public let kind: String28    public let bps: Double?29    public let amount: NFTMoney?30    public let recipient: String?31    public let required: Bool?32}3334public struct NFTMarketProtocol: Codable, Sendable, Hashable { public let name: String; public let address: String? }3536public struct NFTMarketListing: Codable, Sendable, Hashable {37    /** The source's own identifier of the order; never a key across sources, and nothing here can act on it. */38    public let orderId: String?39    /** Total asked for `quantity` units. */40    public let price: NFTMoney41    public let quantity: String42    public let seller: String?43    public let venue: String?44    public let `protocol`: NFTMarketProtocol?45    public let createdAt: String?46    public let expiresAt: String?47    public let fees: [NFTMarketFee]?48}4950public struct NFTMarketOffer: Codable, Sendable, Hashable {51    public let orderId: String?52    public let price: NFTMoney53    public let quantity: String54    public let bidder: String?55    public let venue: String?56    /** `item`: an offer on this item; `collection` / `trait`: an offer any matching item could accept. */57    public let scope: String58    public let createdAt: String?59    public let expiresAt: String?60    public let fees: [NFTMarketFee]?61}6263public struct NFTMarketSale: Codable, Sendable, Hashable {64    public let price: NFTMoney65    public let quantity: String66    public let at: String?67    public let tx: String?68    public let buyer: String?69    public let seller: String?70    public let venue: String?71}7273public struct NFTAttribution: Codable, Sendable, Hashable { public let text: String; public let url: String }7475/** What one market source says about itself for one request: the SOURCE and the DATE of every figure of its row. */76public struct NFTMarketSourceStatus: Codable, Sendable, Hashable {77    public let provider: String78    public let name: String79    /** `ok`, `needs_key`, `off`, `not_covered`, `error`. Only `ok` rows carry figures. */80    public let state: String81    /** Stable code when not ok (`provider_rate_limited`, `budget_exhausted`, `not_found`, `chain_not_covered`, `no_api_key`, …) or the failure behind a stale row. */82    public let code: String?83    /** NAME of the server variable that would turn the source on — never a value. */84    public let unlockedBy: String?85    /** True when the row was served from the cache after a failure of the source (at most a day old). */86    public let stale: Bool87    /** Category `market`, with the time the server obtained the answer. */88    public let stamp: NFTSourceStamp?89    /** Attribution the source's terms ask for. */90    public let attribution: NFTAttribution?9192    public var isOK: Bool { state == "ok" }93    /** When the source's answer was obtained; nil when the source gave none. */94    public var fetchedAt: Date? { stamp?.fetchedAt }95}9697/** How a source qualifies a collection. Only `verified`, with the source NAMED, may be shown as a badge: it is that source's statement. */98public struct NFTMarketVerification: Codable, Sendable, Hashable {99    /** `verified`, `not_verified`, `unknown`. */100    public let state: String101    public let providerValue: String?102    public let by: String103}104105public struct NFTMarketRarity: Codable, Sendable, Hashable { public let rank: String; public let outOf: String?; public let method: String; public let calculatedAt: String? }106public struct NFTMarketItemFlags: Codable, Sendable, Hashable { public let suspicious: NFTKnown<Bool>; public let disabled: NFTKnown<Bool>; public let nsfw: NFTKnown<Bool> }107public struct NFTMarketCollectionName: Codable, Sendable, Hashable { public let slug: String; public let name: String? }108109/** One source's view of one item. The five price notions are five fields and are never substituted for one another. */110public struct NFTItemMarket: Codable, Sendable, Hashable {111    public let status: NFTMarketSourceStatus112    /** The item's page on the marketplace: opened outside the app only. */113    public let url: String?114    public let listed: NFTKnown<Bool>115    /** A live asking price. */116    public let ask: NFTKnown<NFTMarketListing>117    public let bestOffer: NFTKnown<NFTMarketOffer>118    /** A sale the source reports. */119    public let lastSale: NFTKnown<NFTMarketSale>120    /** The marketplace's own identifier and name of the collection — never copied into the on-chain collection. */121    public let collection: NFTMarketCollectionName?122    /** A statistic of the collection — never the value of this item. */123    public let collectionFloor: NFTKnown<NFTMoney>124    public let verification: NFTMarketVerification?125    public let flags: NFTMarketItemFlags?126    public let rarity: NFTKnown<NFTMarketRarity>?127}128129/** The rate of one currency from the wallet's own price sources, with ITS source and date. Secondary by construction. */130public struct NFTRate: Codable, Sendable, Hashable {131    public let currency: NFTCurrency?132    public let symbol: String133    /** Exact decimal text; nil when unavailable or withheld. */134    public let usd: String?135    public let cad: String?136    public let source: String137    public let priceAt: String?138    public let stale: Bool139    /** Set when the rate may not be answered to this caller (a licence of the price source). */140    public let withheld: String?141}142143/** One market action and why it cannot be done here. `available` is `false` as served for every action of this version. */144public struct NFTMarketAction: Codable, Sendable, Hashable, Identifiable {145    /** `buy`, `sell`, `create_listing`, `cancel_listing`, `make_offer`, `cancel_offer`, `accept_offer`. */146    public let id: String147    public let available: Bool148    /** `market_writes_not_built`. */149    public let reason: String?150}151152/** What is true about acting on a marketplace's own site with this wallet (shown with every external link). */153public struct NFTExternalNotice: Codable, Sendable, Hashable {154    public let outsideWallet: Bool155    /** `false` as served: the wallet offers no wallet connection. */156    public let walletConnect: Bool157    /** `false` as served: the wallet never exports a key. */158    public let keyExport: Bool159    public let code: String160}161162public struct NFTContradiction: Codable, Sendable, Hashable {163    /** `listed`, `ask`, `collection_floor`, `verification`. */164    public let field: String165    public let providers: [String]166    public let note: String167}168169/** `GET /nfts/market`: the market snapshot of one asset. */170public struct NFTMarketAnswer: Codable, Sendable, Hashable {171    public struct External: Codable, Sendable, Hashable { public let links: [NFTExternalLink]; public let notice: NFTExternalNotice }172    public let key: String173    public let sources: [NFTItemMarket]174    /** Where two `ok` sources say different things about the same notion: named, never resolved. */175    public let contradictions: [NFTContradiction]176    /** Keyed by `NFTCurrency.id`. */177    public let rates: [String: NFTRate]178    public let asOf: Date?179    public let actions: [NFTMarketAction]180    public let external: External?181    /** `state` is `unavailable` as served: an item has no value this wallet can establish from a floor or a single quote. */182    public let value: NFTValuationState?183184    /** True only if the server says an action can be done. No version of the backend does. */185    public var anyActionAvailable: Bool { actions.contains { $0.available } }186}187188/** `GET /nfts/market/listings` and `/offers`: one page per source. A cursor belongs to its source. */189public struct NFTMarketOrders<Item: Codable & Sendable & Hashable>: Codable, Sendable, Hashable {190    public struct Source: Codable, Sendable, Hashable { public let status: NFTMarketSourceStatus; public let items: [Item]; public let cursor: String? }191    public let key: String?192    /** `listings` or `offers`. */193    public let kind: String?194    public let sources: [Source]195    public let rates: [String: NFTRate]196    public let asOf: Date?197    public let actions: [NFTMarketAction]198}199200public struct NFTMarketEvent: Codable, Sendable, Hashable {201    public struct Flags: Codable, Sendable, Hashable { public let washTrade: NFTKnown<Bool> }202    /** `sale`, `list`, `delist`, `offer`, `cancel-offer`, `accept-offer`, `transfer`, `mint`, `unknown`. */203    public let type: String204    /** The source's own event name, kept beside the normalised type. */205    public let providerType: String206    public let at: String?207    public let tx: String?208    public let index: String?209    public let from: String?210    public let to: String?211    public let quantity: String212    public let price: NFTMoney?213    public let venue: String?214    public let orderId: String?215    /** Wash / self trade as the SOURCE reports it — passed through, never filtered. */216    public let flags: Flags?217    public let fees: [NFTMarketFee]?218    public var date: Date? { at.flatMap(ISO8601.parse) }219}220221/** `GET /nfts/market/activity`: market statements, listed apart from the chain's transfers. */222public struct NFTMarketEvents: Codable, Sendable, Hashable {223    public struct Source: Codable, Sendable, Hashable { public let status: NFTMarketSourceStatus; public let events: [NFTMarketEvent]; public let cursor: String? }224    public let key: String?225    public let sources: [Source]226    public let rates: [String: NFTRate]227    public let asOf: Date?228}229230/** The market event types `GET /nfts/market/activity` filters on. */231public enum NFTMarketEventType: String, Sendable, CaseIterable {232    case sale, list, delist, offer, cancelOffer = "cancel-offer", acceptOffer = "accept-offer", transfer, mint, unknown233}234235/** Filters of `GET /nfts/market/activity`. A cursor is a position in ONE source's list: it is only accepted with that source. */236public struct NFTMarketEventQuery: Sendable, Equatable {237    public var provider: String?238    public var cursor: String?239    public var types: [NFTMarketEventType]?240    public var after: Date?241    public var before: Date?242    /** 1…50. */243    public var limit: Int?244    public init(provider: String? = nil, cursor: String? = nil, types: [NFTMarketEventType]? = nil, after: Date? = nil, before: Date? = nil, limit: Int? = nil) {245        self.provider = provider; self.cursor = cursor; self.types = types; self.after = after; self.before = before; self.limit = limit246    }247}248249public struct NFTTraitCount: Codable, Sendable, Hashable { public let value: String; public let count: String }250public struct NFTCollectionTraits: Codable, Sendable, Hashable {251    public struct Category: Codable, Sendable, Hashable { public let type: String; public let values: [NFTTraitCount] }252    /** The stated number of items the counts were computed over. */253    public let total: String254    public let categories: [Category]255    /** True when the server cut the document (at most 40 categories of 12 values). */256    public let truncated: Bool?257}258259public struct NFTCollectionVolume: Codable, Sendable, Hashable {260    public struct Reported: Codable, Sendable, Hashable { public let value: String; public let symbol: String }261    /** `all`, `1d`, `7d`, `30d`. */262    public let interval: String263    public let volume: NFTMoney?264    /** The figure as the source words it when its unit is named by a symbol only: shown as reported, never converted or summed. */265    public let reported: Reported?266    public let sales: String?267}268269/** One source's view of one collection. */270public struct NFTCollectionMarket: Codable, Sendable, Hashable {271    public let status: NFTMarketSourceStatus272    public let slug: String?273    public let name: String?274    public let description: String?275    public let url: String?276    /** Media proxy ids: the marketplace's image URLs stay on the server. */277    public let imageId: String?278    public let bannerId: String?279    public let verification: NFTMarketVerification?280    public let floor: NFTKnown<NFTMoney>281    public let volumes: [NFTCollectionVolume]282    public let listedCount: NFTKnown<String>283    public let owners: NFTKnown<String>284    public let totalSupply: NFTKnown<String>285    public let fees: [NFTMarketFee]?286    /** Trait counts ONLY with a stated item total. */287    public let traits: NFTKnown<NFTCollectionTraits>288    /** What each figure means according to the source, when it says. */289    public let definitions: [String: String]?290}291292public struct NFTCollectionMarketAnswer: Codable, Sendable, Hashable {293    public let key: String?294    public let sources: [NFTCollectionMarket]295    public let rates: [String: NFTRate]296    public let asOf: Date?297}298299/** `GET /nfts/market/traits`: the frequency of each trait value of ONE item, per source, with its denominator, source and date. */300public struct NFTTraitAnswer: Codable, Sendable, Hashable {301    public struct Frequency: Codable, Sendable, Hashable {302        public let count: String303        public let total: String304        /** Exact to a hundredth of a percent, as text. */305        public let percent: String306    }307    public struct Row: Codable, Sendable, Hashable { public let traitType: String; public let value: String; public let frequency: Frequency? }308    public struct Source: Codable, Sendable, Hashable {309        public let provider: String310        public let name: String311        public let computed: Bool312        public let reason: String?313        public let total: String?314        public let fetchedAt: Date?315        public let stale: Bool?316        public let method: String?317        public let rows: [Row]318    }319    public let key: String?320    /** False when no source gives collection-level counts with a stated item total: nothing is computed from a partial sample. */321    public let computed: Bool322    public let reason: String?323    public let sources: [Source]324    public let mutableMetadata: Bool?325}326327/** One market provider slot of the server: on / needs key / off, what it would unlock, and its request budget. */328public struct NFTMarketProvider: Codable, Sendable, Hashable, Identifiable {329    public struct Terms: Codable, Sendable, Hashable { public let url: String; public let readAt: String; public let note: String }330    public struct Window: Codable, Sendable, Hashable { public let used: Int; public let limit: Int; public let date: String? }331    public struct Budget: Codable, Sendable, Hashable {332        public let provider: String?333        public let minute: Window334        public let day: Window335        public let refused: Int336        public let lastRefusedAt: String?337        public let upstreamLimited: Int338        public let lastUpstreamLimitedAt: String?339    }340    public let id: String341    public let name: String342    /** `on`, `needs_key`, `off`. */343    public let state: String344    public let unlockedBy: String?345    public let unlocks: String?346    public let chains: [String]347    /** What leaves the server when the provider is asked: `mint_only`, `contract_and_token_id`, `nothing`, `nothing_until_enabled`. Never the wallet address. */348    public let sends: String349    public let attribution: NFTAttribution?350    public let terms: Terms?351    /** `live`: the adapter was run against the real API; `documentation`: coded against the documented shapes only. */352    public let verification: String?353    public let budget: Budget?354    /** Cache lifetime of each data type, in seconds. */355    public let ttlSeconds: [String: Double]?356}357358public struct NFTMarketProviders: Codable, Sendable, Hashable {359    public let providers: [NFTMarketProvider]360    public let actions: [NFTMarketAction]361    public let notice: NFTExternalNotice?362}363364/**365 `GET /nfts/valuation`: the opt-in "indicative floor-based estimate". Default OFF. It is NOT a valuation and is never added to the366 wallet's total: per collection, the number of items held × the lowest floor a source reports, with that source and its age.367 */368public struct NFTFloorEstimate: Codable, Sendable, Hashable {369    public struct Floor: Codable, Sendable, Hashable { public let provider: String; public let name: String; public let floor: NFTMoney; public let fetchedAt: Date?; public let stale: Bool }370    public struct Used: Codable, Sendable, Hashable { public let provider: String; public let floor: NFTMoney; public let fetchedAt: Date?; public let stale: Bool; public let indicative: NFTMoney }371    public struct Collection: Codable, Sendable, Hashable {372        public let collectionKey: String373        public let chain: String374        public let name: String?375        public let items: Int376        /** Every source's figure, listed beside the one used. */377        public let floors: [Floor]378        public let used: Used?379        /** Why no floor was used (`no_floor_reported`, `market_unavailable`, a source code). */380        public let reason: String?381    }382    public struct Estimate: Codable, Sendable, Hashable {383        public let label: String384        public let method: String?385        public let collections: [Collection]386        public let rates: [String: NFTRate]387        /** Exact decimal text with two decimals; nil when no collection could be counted. */388        public let indicativeUsd: String?389        public let collectionsCounted: Int390        public let collectionsWithoutFloor: Int391        public let itemsWithoutCollection: String?392        public let asOf: Date?393    }394    public let enabled: Bool395    /** `unavailable` as served, whether the estimate is on or off. */396    public let state: String397    public let reason: String?398    /** `true` as served. */399    public let excludedFromWalletTotal: Bool400    public let estimate: Estimate?401}402403public struct NFTFloorEstimateSetting: Codable, Sendable, Hashable { public let enabled: Bool }404
Files main
Menu

Theme