@unicitylabs/sphere-sdk 0.17.2-dev.1 → 0.17.2-dev.3

package/dist/modules/payments-v2/index.d.cts

@@ -4,6 +4,8 @@ declare const NFT_METADATA_TAG = 39052n;
 declare const NFT_MEDIA_TAG = 39053n;
 declare const NFT_LINK_TAG = 39054n;
 declare const NFT_SIGNED_TAG = 39055n;
+/** The media type of an NftLink that points at a metadata document instead of a media file. */
+declare const NFT_DOCUMENT_MEDIA_TYPE = "application/vnd.unicity.nft+cbor";
 /** An inline file. */
 interface NftMedia {
     readonly kind: 'media';
@@ -33,6 +35,8 @@ interface NftMetadata {
     readonly external_url: string | null;
     readonly attributes: readonly NftAttribute[];
     readonly collection: string | null;
+    /** The collection the item claims: 1–64 bytes as even-length hex (decoded lowercase). Never verified here. */
+    readonly collection_id: string | null;
 }
 type NftContent = NftMetadata | NftMedia | NftLink;
 type NftSignatureStatus = 'unsigned' | 'valid' | 'invalid';
@@ -45,10 +49,27 @@ interface ParsedNft {
         readonly signature: Uint8Array;
     } | null;
 }
+/** What an NftSigned signature binds besides its payload, exactly as the token's mint records it. */
+interface NftSignatureContext {
+    /** The network identifier α (`NetworkId.id`). */
+    readonly networkId: number | bigint;
+    /** The genesis recipient predicate, as `EncodedPredicate.toCBOR()` bytes. */
+    readonly recipientPredicate: Uint8Array;
+    /** The 32 raw token id bytes. */
+    readonly tokenId: Uint8Array;
+    readonly tokenType: Uint8Array;
+}
 /** Encode one unsigned item. Throws SphereError('…', 'VALIDATION_ERROR') naming the offending field. */
 declare function encodeNftContent(content: NftContent): Uint8Array;
 /** Structural parse of a genesis payload. NEVER throws; null = not a recognised NFT. */
 declare function parseNftPayload(data: Uint8Array | null): ParsedNft | null;
+/**
+ * Parse the file a document link points at: exactly one NftMetadata or NftMedia item.
+ * NEVER throws; null = not a document. Check the bytes with verifyNftLinkContent first.
+ */
+declare function parseNftDocument(bytes: Uint8Array): NftMetadata | NftMedia | null;
+/** Is this an NftLink to a metadata document ({@link NFT_DOCUMENT_MEDIA_TYPE}), resolved with parseNftDocument? */
+declare function isNftDocumentLink(content: NftContent): boolean;
 /** Does `bytes` match the link's sha256? Pure, sync. */
 declare function verifyNftLinkContent(link: NftLink, bytes: Uint8Array): boolean;
 
@@ -1425,4 +1446,4 @@ declare class PaymentsFacade implements PaymentsV2 {
 declare const HEARTBEAT_SEED_MS = 5000;
 declare const HEARTBEAT_CAP_MS = 120000;
 
-export { ATTENTION_MINT_UNRESOLVED, ATTENTION_RECIPIENT_NETWORK_UNVERIFIED, ATTENTION_RESEED_REJECTED, type AckOutcome, type AckRequest, type ApplyDeltaResult, type CheckpointReseeder, type ConnectionStatus, type DeliverOptions, type DeliveryJournalEntry, type DeliveryPort, type DeliveryReceipt, type DeterministicMintCapable, type FacadeClient, type FacadeSession, HEARTBEAT_CAP_MS, HEARTBEAT_SEED_MS, type HistoryEntry, type HistoryPage, type IncomingDelivery, type IntentBackstopEntry, type IntentPayload, type InventoryAsset, type InventoryItem, type InventoryPage, MAX_RESELECT, type MintJournalEntry, type MintNftRequest, type MintResult, NFT_LINK_TAG, NFT_MAX_PAYLOAD_BYTES, NFT_MEDIA_TAG, NFT_METADATA_TAG, NFT_SIGNED_TAG, type NftAttribute, type NftContent, type NftLink, type NftMedia, type NftMediaRef, type NftMetadata, type NftMintJournalEntry, type NftSignatureStatus, type NftView, type OpOutcome, type OutcomeClass, type PaymentRequestStatus, type PaymentRequestView, PaymentsFacade, type PaymentsFacadeDeps, type PaymentsRequestsApi, type PaymentsV2, type PaymentsV2Events, type PendingTransfer, type PlannedOp, type RecipientInfo, type RetryableAckError, STORE_KEYS, type ScopedKV, type SendCoinlessRequest, type SendRequest, type SendWholeTokenRequest, type SettlingLink, type ShortfallEntry, type StoragePort, type StreamCursor, type StreamName, createScopedKV, encodeNftContent, isRetryableAckError, parseNftPayload, supportsDeterministicMint, sweepSupersededState, verifyNftLinkContent };
+export { ATTENTION_MINT_UNRESOLVED, ATTENTION_RECIPIENT_NETWORK_UNVERIFIED, ATTENTION_RESEED_REJECTED, type AckOutcome, type AckRequest, type ApplyDeltaResult, type CheckpointReseeder, type ConnectionStatus, type DeliverOptions, type DeliveryJournalEntry, type DeliveryPort, type DeliveryReceipt, type DeterministicMintCapable, type FacadeClient, type FacadeSession, HEARTBEAT_CAP_MS, HEARTBEAT_SEED_MS, type HistoryEntry, type HistoryPage, type IncomingDelivery, type IntentBackstopEntry, type IntentPayload, type InventoryAsset, type InventoryItem, type InventoryPage, MAX_RESELECT, type MintJournalEntry, type MintNftRequest, type MintResult, NFT_DOCUMENT_MEDIA_TYPE, NFT_LINK_TAG, NFT_MAX_PAYLOAD_BYTES, NFT_MEDIA_TAG, NFT_METADATA_TAG, NFT_SIGNED_TAG, type NftAttribute, type NftContent, type NftLink, type NftMedia, type NftMediaRef, type NftMetadata, type NftMintJournalEntry, type NftSignatureContext, type NftSignatureStatus, type NftView, type OpOutcome, type OutcomeClass, type PaymentRequestStatus, type PaymentRequestView, PaymentsFacade, type PaymentsFacadeDeps, type PaymentsRequestsApi, type PaymentsV2, type PaymentsV2Events, type PendingTransfer, type PlannedOp, type RecipientInfo, type RetryableAckError, STORE_KEYS, type ScopedKV, type SendCoinlessRequest, type SendRequest, type SendWholeTokenRequest, type SettlingLink, type ShortfallEntry, type StoragePort, type StreamCursor, type StreamName, createScopedKV, encodeNftContent, isNftDocumentLink, isRetryableAckError, parseNftDocument, parseNftPayload, supportsDeterministicMint, sweepSupersededState, verifyNftLinkContent };

package/dist/modules/payments-v2/index.d.ts

@@ -4,6 +4,8 @@ declare const NFT_METADATA_TAG = 39052n;
 declare const NFT_MEDIA_TAG = 39053n;
 declare const NFT_LINK_TAG = 39054n;
 declare const NFT_SIGNED_TAG = 39055n;
+/** The media type of an NftLink that points at a metadata document instead of a media file. */
+declare const NFT_DOCUMENT_MEDIA_TYPE = "application/vnd.unicity.nft+cbor";
 /** An inline file. */
 interface NftMedia {
     readonly kind: 'media';
@@ -33,6 +35,8 @@ interface NftMetadata {
     readonly external_url: string | null;
     readonly attributes: readonly NftAttribute[];
     readonly collection: string | null;
+    /** The collection the item claims: 1–64 bytes as even-length hex (decoded lowercase). Never verified here. */
+    readonly collection_id: string | null;
 }
 type NftContent = NftMetadata | NftMedia | NftLink;
 type NftSignatureStatus = 'unsigned' | 'valid' | 'invalid';
@@ -45,10 +49,27 @@ interface ParsedNft {
         readonly signature: Uint8Array;
     } | null;
 }
+/** What an NftSigned signature binds besides its payload, exactly as the token's mint records it. */
+interface NftSignatureContext {
+    /** The network identifier α (`NetworkId.id`). */
+    readonly networkId: number | bigint;
+    /** The genesis recipient predicate, as `EncodedPredicate.toCBOR()` bytes. */
+    readonly recipientPredicate: Uint8Array;
+    /** The 32 raw token id bytes. */
+    readonly tokenId: Uint8Array;
+    readonly tokenType: Uint8Array;
+}
 /** Encode one unsigned item. Throws SphereError('…', 'VALIDATION_ERROR') naming the offending field. */
 declare function encodeNftContent(content: NftContent): Uint8Array;
 /** Structural parse of a genesis payload. NEVER throws; null = not a recognised NFT. */
 declare function parseNftPayload(data: Uint8Array | null): ParsedNft | null;
+/**
+ * Parse the file a document link points at: exactly one NftMetadata or NftMedia item.
+ * NEVER throws; null = not a document. Check the bytes with verifyNftLinkContent first.
+ */
+declare function parseNftDocument(bytes: Uint8Array): NftMetadata | NftMedia | null;
+/** Is this an NftLink to a metadata document ({@link NFT_DOCUMENT_MEDIA_TYPE}), resolved with parseNftDocument? */
+declare function isNftDocumentLink(content: NftContent): boolean;
 /** Does `bytes` match the link's sha256? Pure, sync. */
 declare function verifyNftLinkContent(link: NftLink, bytes: Uint8Array): boolean;
 
@@ -1425,4 +1446,4 @@ declare class PaymentsFacade implements PaymentsV2 {
 declare const HEARTBEAT_SEED_MS = 5000;
 declare const HEARTBEAT_CAP_MS = 120000;
 
-export { ATTENTION_MINT_UNRESOLVED, ATTENTION_RECIPIENT_NETWORK_UNVERIFIED, ATTENTION_RESEED_REJECTED, type AckOutcome, type AckRequest, type ApplyDeltaResult, type CheckpointReseeder, type ConnectionStatus, type DeliverOptions, type DeliveryJournalEntry, type DeliveryPort, type DeliveryReceipt, type DeterministicMintCapable, type FacadeClient, type FacadeSession, HEARTBEAT_CAP_MS, HEARTBEAT_SEED_MS, type HistoryEntry, type HistoryPage, type IncomingDelivery, type IntentBackstopEntry, type IntentPayload, type InventoryAsset, type InventoryItem, type InventoryPage, MAX_RESELECT, type MintJournalEntry, type MintNftRequest, type MintResult, NFT_LINK_TAG, NFT_MAX_PAYLOAD_BYTES, NFT_MEDIA_TAG, NFT_METADATA_TAG, NFT_SIGNED_TAG, type NftAttribute, type NftContent, type NftLink, type NftMedia, type NftMediaRef, type NftMetadata, type NftMintJournalEntry, type NftSignatureStatus, type NftView, type OpOutcome, type OutcomeClass, type PaymentRequestStatus, type PaymentRequestView, PaymentsFacade, type PaymentsFacadeDeps, type PaymentsRequestsApi, type PaymentsV2, type PaymentsV2Events, type PendingTransfer, type PlannedOp, type RecipientInfo, type RetryableAckError, STORE_KEYS, type ScopedKV, type SendCoinlessRequest, type SendRequest, type SendWholeTokenRequest, type SettlingLink, type ShortfallEntry, type StoragePort, type StreamCursor, type StreamName, createScopedKV, encodeNftContent, isRetryableAckError, parseNftPayload, supportsDeterministicMint, sweepSupersededState, verifyNftLinkContent };
+export { ATTENTION_MINT_UNRESOLVED, ATTENTION_RECIPIENT_NETWORK_UNVERIFIED, ATTENTION_RESEED_REJECTED, type AckOutcome, type AckRequest, type ApplyDeltaResult, type CheckpointReseeder, type ConnectionStatus, type DeliverOptions, type DeliveryJournalEntry, type DeliveryPort, type DeliveryReceipt, type DeterministicMintCapable, type FacadeClient, type FacadeSession, HEARTBEAT_CAP_MS, HEARTBEAT_SEED_MS, type HistoryEntry, type HistoryPage, type IncomingDelivery, type IntentBackstopEntry, type IntentPayload, type InventoryAsset, type InventoryItem, type InventoryPage, MAX_RESELECT, type MintJournalEntry, type MintNftRequest, type MintResult, NFT_DOCUMENT_MEDIA_TYPE, NFT_LINK_TAG, NFT_MAX_PAYLOAD_BYTES, NFT_MEDIA_TAG, NFT_METADATA_TAG, NFT_SIGNED_TAG, type NftAttribute, type NftContent, type NftLink, type NftMedia, type NftMediaRef, type NftMetadata, type NftMintJournalEntry, type NftSignatureContext, type NftSignatureStatus, type NftView, type OpOutcome, type OutcomeClass, type PaymentRequestStatus, type PaymentRequestView, PaymentsFacade, type PaymentsFacadeDeps, type PaymentsRequestsApi, type PaymentsV2, type PaymentsV2Events, type PendingTransfer, type PlannedOp, type RecipientInfo, type RetryableAckError, STORE_KEYS, type ScopedKV, type SendCoinlessRequest, type SendRequest, type SendWholeTokenRequest, type SettlingLink, type ShortfallEntry, type StoragePort, type StreamCursor, type StreamName, createScopedKV, encodeNftContent, isNftDocumentLink, isRetryableAckError, parseNftDocument, parseNftPayload, supportsDeterministicMint, sweepSupersededState, verifyNftLinkContent };

package/dist/modules/payments-v2/index.js

@@ -454,7 +454,8 @@ var NFT_MEDIA_TAG = 39053n;
 var NFT_LINK_TAG = 39054n;
 var NFT_SIGNED_TAG = 39055n;
 var NFT_FORMAT_VERSION = 1n;
-var METADATA_ARITY = 8;
+var NFT_DOCUMENT_MEDIA_TYPE = "application/vnd.unicity.nft+cbor";
+var METADATA_ARITY = 9;
 var MEDIA_ARITY = 3;
 var LINK_ARITY = 4;
 var SIGNED_ARITY = 4;
@@ -462,11 +463,15 @@ var CREATOR_BYTES = 33;
 var SIGNATURE_BYTES = 65;
 var MAX_URI_LENGTH = 2048;
 var LINK_SCHEMES = ["https://", "ipfs://", "ar://"];
+var SIGNED_DOMAIN = new TextEncoder().encode("UNICITY_NFT_SIGNED");
 var MEDIA_TYPE_PATTERN = /^[a-z0-9][a-z0-9!#$&^_.+-]{0,126}\/[a-z0-9][a-z0-9!#$&^_.+-]{0,126}$/;
 var SHA256_HEX_PATTERN = /^[0-9a-f]{64}$/i;
+var COLLECTION_ID_PATTERN = /^(?:[0-9a-f]{2}){1,64}$/i;
 var LONE_SURROGATE = /\p{Cs}/u;
 var CBOR_MAJOR_TYPE_MASK = 224;
 var ATTRIBUTE_VALUE_RULE = "must be non-empty text or an integer within \xB1(2^53 \u2212 1) \u2014 write decimals and larger numbers as text";
+var COLLECTION_ID_RULE = "must be null or 1\u201364 bytes as even-length hex (2\u2013128 characters)";
+var DOCUMENT_AS_MEDIA_RULE = `must not be ${NFT_DOCUMENT_MEDIA_TYPE}: a document link is a token's content, never media`;
 var UTF8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
 function refuse(field, rule, cause) {
   return new SphereError(`Invalid NFT ${field}: ${rule}`, "VALIDATION_ERROR", cause);
@@ -478,6 +483,7 @@ var fieldName = (prefix, name) => prefix === "" ? name : `${prefix}.${name}`;
 var isText = (value) => typeof value === "string" && value.length > 0 && !LONE_SURROGATE.test(value);
 var isBytes2 = (value, length) => value instanceof Uint8Array && (length === void 0 ? value.length > 0 : value.length === length);
 var isMediaType = (value) => typeof value === "string" && MEDIA_TYPE_PATTERN.test(value);
+var isCollectionId = (value) => typeof value === "string" && COLLECTION_ID_PATTERN.test(value);
 var isAttributeValue = (value) => typeof value === "number" ? Number.isSafeInteger(value) : isText(value);
 function hasSpaceOrControl(value) {
   for (let i = 0; i < value.length; i++) {
@@ -520,8 +526,9 @@ function checkLink(prefix, link) {
 function checkMediaRef(field, ref) {
   if (ref === null) return;
   if (ref?.kind === "media") return checkMedia(field, ref);
-  if (ref?.kind === "link") return checkLink(field, ref);
-  throw refuse(field, "must be an NftMedia, an NftLink or null");
+  if (ref?.kind !== "link") throw refuse(field, "must be an NftMedia, an NftLink or null");
+  checkLink(field, ref);
+  ensure(!isNftDocumentLink(ref), fieldName(field, "media_type"), DOCUMENT_AS_MEDIA_RULE);
 }
 function checkAttributes(attributes) {
   ensure(Array.isArray(attributes), "attributes", "must be an array \u2014 [] when there are none");
@@ -538,6 +545,7 @@ function checkMetadata(metadata) {
   checkOptionalText("external_url", metadata.external_url);
   checkAttributes(metadata.attributes);
   checkOptionalText("collection", metadata.collection);
+  ensure(metadata.collection_id === null || isCollectionId(metadata.collection_id), "collection_id", COLLECTION_ID_RULE);
 }
 function checkContent(content) {
   switch (content?.kind) {
@@ -595,6 +603,7 @@ function arrayCbor(items) {
   }
   return out;
 }
+var optionalHexBytes = (value) => CborSerializer.encodeNullable(value, (hex) => CborSerializer.encodeByteString(HexConverter.decode(hex.toLowerCase())));
 function metadataCbor(metadata) {
   return versioned(
     NFT_METADATA_TAG,
@@ -604,7 +613,8 @@ function metadataCbor(metadata) {
     mediaRefCbor(metadata.animation_url),
     optionalText(metadata.external_url),
     arrayCbor(metadata.attributes.map(attributeCbor)),
-    optionalText(metadata.collection)
+    optionalText(metadata.collection),
+    optionalHexBytes(metadata.collection_id)
   );
 }
 function encodeNftContent(content) {
@@ -645,13 +655,14 @@ function decodeMedia(body) {
   const [, mediaType, bytes] = versionedFields(body, MEDIA_ARITY);
   return { kind: "media", media_type: decodeText(mediaType), bytes: CborDeserializer.decodeByteString(bytes) };
 }
+var decodeHex = (item) => HexConverter.encode(CborDeserializer.decodeByteString(item));
 function decodeLink(body) {
   const [, mediaType, uri, digest] = versionedFields(body, LINK_ARITY);
   return {
     kind: "link",
     media_type: decodeText(mediaType),
     uri: decodeText(uri),
-    sha256: HexConverter.encode(CborDeserializer.decodeByteString(digest))
+    sha256: decodeHex(digest)
   };
 }
 function decodeMetadata(body) {
@@ -664,7 +675,8 @@ function decodeMetadata(body) {
     animation_url: decodeMediaRef("animation_url", fields[4]),
     external_url: decodeOptionalText(fields[5]),
     attributes: decodeAttributes(fields[6]),
-    collection: decodeOptionalText(fields[7])
+    collection: decodeOptionalText(fields[7]),
+    collection_id: CborDeserializer.decodeNullable(fields[8], decodeHex)
   };
 }
 var MEDIA_REF_DECODERS = /* @__PURE__ */ new Map([
@@ -676,6 +688,10 @@ var UNSIGNED_DECODERS = /* @__PURE__ */ new Map([
   [NFT_MEDIA_TAG, decodeMedia],
   [NFT_LINK_TAG, decodeLink]
 ]);
+var DOCUMENT_DECODERS = /* @__PURE__ */ new Map([
+  [NFT_METADATA_TAG, decodeMetadata],
+  [NFT_MEDIA_TAG, decodeMedia]
+]);
 function decodeBody(decoders, field, tag, body) {
   const decode = decoders.get(tag);
   if (decode === void 0) throw refuse(field, `tag ${tag} is not allowed here`);
@@ -710,6 +726,18 @@ function parseNftPayload(data) {
     return null;
   }
 }
+function parseNftDocument(bytes) {
+  try {
+    const document = decodeItem(DOCUMENT_DECODERS, "document", bytes);
+    checkContent(document);
+    return document;
+  } catch {
+    return null;
+  }
+}
+function isNftDocumentLink(content) {
+  return content?.kind === "link" && content.media_type === NFT_DOCUMENT_MEDIA_TYPE;
+}
 function verifyNftLinkContent(link, bytes) {
   return HexConverter.encode(sha256(bytes)) === link.sha256.toLowerCase();
 }
@@ -5737,6 +5765,7 @@ export {
   HEARTBEAT_CAP_MS,
   HEARTBEAT_SEED_MS,
   MAX_RESELECT,
+  NFT_DOCUMENT_MEDIA_TYPE,
   NFT_LINK_TAG,
   NFT_MAX_PAYLOAD_BYTES,
   NFT_MEDIA_TAG,
@@ -5746,7 +5775,9 @@ export {
   STORE_KEYS,
   createScopedKV,
   encodeNftContent,
+  isNftDocumentLink,
   isRetryableAckError,
+  parseNftDocument,
   parseNftPayload,
   supportsDeterministicMint,
   sweepSupersededState,