@yallet/rwa-sdk 0.2.0

package/src/index.ts

@@ -0,0 +1,151 @@
+/**
+ * Yallet RWA SDK
+ *
+ * SDK for minting encrypted RWA (Real World Assets) as Solana cNFTs
+ *
+ * Features:
+ * - End-to-end encryption using xidentity (X25519) public keys
+ * - Permanent storage on Arweave via ArDrive Turbo
+ * - Compressed NFT minting via Metaplex Bubblegum
+ * - User registry for xidentity management
+ *
+ * @example
+ * ```typescript
+ * import { createRWASDK, AssetType } from '@yallet/rwa-sdk';
+ *
+ * // Create SDK instance
+ * const sdk = createRWASDK({
+ *   rpcEndpoint: 'https://api.mainnet-beta.solana.com',
+ *   network: 'mainnet',
+ *   merkleTreeAddress: 'YOUR_TREE_ADDRESS',
+ * });
+ *
+ * // Register a user with their xidentity
+ * await sdk.registerUser({
+ *   solanaAddress: 'RECIPIENT_ADDRESS',
+ *   xidentity: 'BASE64_XIDENTITY_PUBLIC_KEY',
+ *   name: 'Customer Name',
+ * });
+ *
+ * // Mint an encrypted invoice
+ * const result = await sdk.mintInvoice(
+ *   {
+ *     invoiceId: 'INV-001',
+ *     amount: 100,
+ *     currency: 'USD',
+ *     date: new Date().toISOString(),
+ *   },
+ *   'RECIPIENT_ADDRESS'
+ * );
+ *
+ * console.log('Minted:', result.assetId);
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// Main SDK
+export { YalletRWASDK, createRWASDK } from './sdk.js';
+
+// Types
+export {
+  AssetType,
+  type SDKConfig,
+  type MintRequest,
+  type MintResult,
+  type RegisteredUser,
+  type UserRegistry,
+  type InvoiceData,
+  type InvoiceItem,
+  type NoteData,
+  type ContactData,
+  type FileData,
+  type PhotoData,
+  type EncryptedPayload,
+  type EncryptFunction,
+  type TreeConfig,
+  type Signer,
+} from './types.js';
+
+// Payload builders (extension-compatible JSON)
+export {
+  buildInvoicePayload,
+  buildFilePayload,
+  buildMessagePayload,
+  buildPhotoPayload,
+  type InvoicePayloadBundle,
+  type ExtensionInvoicePayload,
+  type ExtensionLineItem,
+  type ExtensionFilePayload,
+  type ExtensionNotePayload,
+  type ExtensionPhotoPayload,
+} from './payloads.js';
+
+// Encryption
+export {
+  ECIESEncryptor,
+  createWasmEncryptor,
+  createAcegfEncryptor,
+  encryptAsset,
+  prepareAssetData,
+  type PrepareAssetOptions,
+  type EncryptAssetOptions,
+  type EncryptedAssetResult,
+} from './encryption.js';
+
+// Storage
+export {
+  uploadToArweave,
+  uploadEncryptedAsset,
+  uploadMetadata,
+  downloadFromArweave,
+  downloadJsonFromArweave,
+  type UploadOptions,
+  type UploadResult,
+} from './storage.js';
+
+// Metadata
+export {
+  generateNFTMetadata,
+  generateInvoiceMetadata,
+  parseRWAMetadata,
+  type NFTMetadata,
+  type NFTMetadataParams,
+  type ParsedRWAMetadata,
+} from './metadata.js';
+
+// Minting
+export {
+  CNFTMinter,
+  createMinter,
+  estimateMintCost,
+} from './minting.js';
+
+// Registry
+export {
+  InMemoryRegistry,
+  HTTPRegistry,
+  createRegistry,
+  isValidSolanaAddress,
+  isValidXidentity,
+  validateUser,
+  type HTTPRegistryConfig,
+  type RegistryOptions,
+} from './registry.js';
+
+// Yault credential NFT (mint user_cred + mnemonic as encrypted note cNFT)
+export {
+  mintCredentialNft,
+  type CredentialNftPayload,
+  type CredentialMintResult,
+} from './credential-nft.js';
+
+// Server-side mint (no registry/signer; caller provides xidentity)
+export {
+  mintCredentialNftViaServer,
+  prepareCredentialNftPayload,
+  RWA_UPLOAD_AND_MINT_ENDPOINTS,
+  type MintCredentialNftViaServerOptions,
+  type PrepareCredentialNftPayloadOptions,
+  type PreparedCredentialNftPayload,
+} from './credential-nft-server.js';

package/src/metadata.ts

@@ -0,0 +1,336 @@
+/**
+ * Yallet RWA SDK - NFT Metadata Module
+ *
+ * Generates Metaplex-compatible NFT metadata for RWA assets
+ */
+
+import { AssetType } from './types.js';
+
+// ======================================
+//  Metadata Generation
+// ======================================
+
+export interface NFTMetadataParams {
+  /** NFT name */
+  name: string;
+  /** NFT description */
+  description?: string;
+  /** Asset type */
+  assetType: AssetType;
+  /** Arweave URI for encrypted data */
+  encryptedDataUri: string;
+  /** Owner's Solana address */
+  owner: string;
+  /** Direction: owned, sent, or received */
+  direction?: 'owned' | 'sent' | 'received';
+  /** Additional attributes */
+  additionalAttributes?: Array<{ trait_type: string; value: string }>;
+  /** External URL */
+  externalUrl?: string;
+  /** Unique identifier for tracking */
+  uuid?: string;
+  /** Creation timestamp (Unix epoch seconds) */
+  timestamp?: number;
+  /** Previous token address for version chain */
+  previousToken?: string;
+  /** Schema identifier for data format */
+  schema?: string;
+  /** MIME type of the content */
+  mimeType?: string;
+  /** Size of the data in bytes */
+  dataSize?: number;
+}
+
+export interface NFTMetadata {
+  name: string;
+  symbol: string;
+  description: string;
+  image: string;
+  external_url: string;
+  attributes: Array<{ trait_type: string; value: string }>;
+  properties: {
+    files: Array<{ uri: string; type: string }>;
+    category: string;
+    creators: Array<{ address: string; share: number }>;
+  };
+  yallet_rwa: {
+    version: number;
+    assetType: AssetType;
+    direction: string;
+    encryptedDataUri: string;
+    /** Unique identifier for tracking */
+    uuid: string;
+    /** Creation timestamp (Unix epoch seconds) */
+    timestamp: number;
+    /** Previous token address for version chain (null for first version) */
+    previousToken: string | null;
+    /** Schema identifier for data format */
+    schema: string | null;
+    /** MIME type of the content */
+    mimeType: string | null;
+    /** Size of the data in bytes */
+    dataSize: number | null;
+  };
+}
+
+/**
+ * Get icon URL for asset type
+ */
+function getAssetTypeIcon(assetType: AssetType): string {
+  const icons: Record<AssetType, string> = {
+    [AssetType.NOTE]: 'https://yallet.app/icons/rwa-note.png',
+    [AssetType.INVOICE]: 'https://yallet.app/icons/rwa-invoice.png',
+    [AssetType.PHOTO]: 'https://yallet.app/icons/rwa-photo.png',
+    [AssetType.FILE]: 'https://yallet.app/icons/rwa-file.png',
+    [AssetType.CONTACT]: 'https://yallet.app/icons/rwa-contact.png',
+  };
+  return icons[assetType] || icons[AssetType.FILE];
+}
+
+/**
+ * Get default description for asset type
+ */
+function getDefaultDescription(assetType: AssetType, direction: string): string {
+  const descriptions: Record<AssetType, string> = {
+    [AssetType.NOTE]: 'Encrypted note',
+    [AssetType.INVOICE]: 'Encrypted invoice',
+    [AssetType.PHOTO]: 'Encrypted photo',
+    [AssetType.FILE]: 'Encrypted file',
+    [AssetType.CONTACT]: 'Encrypted contact',
+  };
+
+  const base = descriptions[assetType] || 'Encrypted asset';
+  const directionSuffix = direction === 'received' ? ' (Received)' : '';
+
+  return `${base}${directionSuffix} - Decryptable only by the owner`;
+}
+
+/**
+ * Generate a UUID v4
+ */
+function generateUUID(): string {
+  if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+  // Fallback for environments without crypto.randomUUID
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0;
+    const v = c === 'x' ? r : (r & 0x3) | 0x8;
+    return v.toString(16);
+  });
+}
+
+/**
+ * Generate Metaplex-compatible NFT metadata
+ *
+ * @param params - Metadata parameters
+ * @returns NFT metadata object
+ */
+export function generateNFTMetadata(params: NFTMetadataParams): NFTMetadata {
+  const {
+    name,
+    description,
+    assetType,
+    encryptedDataUri,
+    owner,
+    direction = 'sent',
+    additionalAttributes = [],
+    externalUrl = 'https://yallet.app',
+    // New fields with defaults
+    uuid = generateUUID(),
+    timestamp = Math.floor(Date.now() / 1000),
+    previousToken = null,
+    schema = null,
+    mimeType = null,
+    dataSize = null,
+  } = params;
+
+  const finalDescription = description || getDefaultDescription(assetType, direction);
+
+  // Build attributes array with required and optional fields
+  const attributes: Array<{ trait_type: string; value: string }> = [
+    { trait_type: 'Asset Type', value: assetType },
+    { trait_type: 'Direction', value: direction },
+    { trait_type: 'Encrypted', value: 'true' },
+    { trait_type: 'Version', value: '1' },
+    { trait_type: 'UUID', value: uuid },
+    { trait_type: 'Timestamp', value: String(timestamp) },
+  ];
+
+  // Add optional attributes only if they have values
+  if (previousToken) {
+    attributes.push({ trait_type: 'Previous Token', value: previousToken });
+  }
+  if (schema) {
+    attributes.push({ trait_type: 'Schema', value: schema });
+  }
+  if (mimeType) {
+    attributes.push({ trait_type: 'MIME Type', value: mimeType });
+  }
+  if (dataSize !== null && dataSize !== undefined) {
+    attributes.push({ trait_type: 'Data Size', value: String(dataSize) });
+  }
+
+  // Add any additional custom attributes
+  attributes.push(...additionalAttributes);
+
+  return {
+    name,
+    symbol: 'YRWA', // Yallet RWA
+    description: finalDescription,
+    image: getAssetTypeIcon(assetType),
+    external_url: externalUrl,
+    attributes,
+    properties: {
+      files: [
+        {
+          uri: encryptedDataUri,
+          type: mimeType || 'application/octet-stream',
+        },
+      ],
+      category: 'document',
+      creators: [
+        {
+          address: owner,
+          share: 100,
+        },
+      ],
+    },
+    yallet_rwa: {
+      version: 1,
+      assetType,
+      direction,
+      encryptedDataUri,
+      uuid,
+      timestamp,
+      previousToken,
+      schema,
+      mimeType,
+      dataSize,
+    },
+  };
+}
+
+/**
+ * Generate invoice-specific NFT metadata
+ *
+ * @param invoiceData - Invoice data
+ * @param encryptedDataUri - Arweave URI
+ * @param owner - Owner's Solana address
+ * @param options - Additional options
+ * @returns NFT metadata
+ */
+export function generateInvoiceMetadata(
+  invoiceData: {
+    invoiceId: string;
+    amount: number;
+    currency: string;
+    description?: string;
+  },
+  encryptedDataUri: string,
+  owner: string,
+  options: {
+    uuid?: string;
+    timestamp?: number;
+    previousToken?: string;
+    schema?: string;
+    dataSize?: number;
+  } = {}
+): NFTMetadata {
+  return generateNFTMetadata({
+    name: `Invoice #${invoiceData.invoiceId}`,
+    description: invoiceData.description || `Invoice for ${invoiceData.amount} ${invoiceData.currency}`,
+    assetType: AssetType.INVOICE,
+    encryptedDataUri,
+    owner,
+    direction: 'sent',
+    additionalAttributes: [
+      { trait_type: 'Invoice ID', value: invoiceData.invoiceId },
+      { trait_type: 'Amount', value: `${invoiceData.amount} ${invoiceData.currency}` },
+    ],
+    mimeType: 'application/json',
+    schema: options.schema || 'yallet-invoice-v1',
+    ...options,
+  });
+}
+
+/**
+ * Parsed RWA metadata structure
+ */
+export interface ParsedRWAMetadata {
+  id: string;
+  name: string;
+  description: string;
+  assetType: AssetType | null;
+  direction: string | null;
+  encrypted: boolean;
+  version: string | null;
+  image: string | null;
+  encryptedDataUri: string | null;
+  owner: string | null;
+  // New fields
+  uuid: string | null;
+  timestamp: number | null;
+  previousToken: string | null;
+  schema: string | null;
+  mimeType: string | null;
+  dataSize: number | null;
+}
+
+/**
+ * Parse RWA NFT metadata from on-chain data
+ *
+ * @param nftData - NFT data from DAS API
+ * @returns Parsed RWA metadata
+ */
+export function parseRWAMetadata(nftData: {
+  id: string;
+  content?: {
+    metadata?: {
+      name?: string;
+      description?: string;
+      attributes?: Array<{ trait_type?: string; name?: string; value?: string }>;
+      properties?: {
+        files?: Array<{ uri?: string; type?: string }>;
+      };
+    };
+    links?: {
+      image?: string;
+    };
+  };
+  ownership?: {
+    owner?: string;
+  };
+}): ParsedRWAMetadata {
+  const attributes = nftData.content?.metadata?.attributes || [];
+
+  const getAttr = (traitType: string): string | null => {
+    const attr = attributes.find(
+      (a) => (a.trait_type || a.name) === traitType
+    );
+    return attr?.value || null;
+  };
+
+  const timestampStr = getAttr('Timestamp');
+  const dataSizeStr = getAttr('Data Size');
+
+  return {
+    id: nftData.id,
+    name: nftData.content?.metadata?.name || 'Unnamed',
+    description: nftData.content?.metadata?.description || '',
+    assetType: getAttr('Asset Type') as AssetType | null,
+    direction: getAttr('Direction'),
+    encrypted: getAttr('Encrypted') === 'true',
+    version: getAttr('Version'),
+    image: nftData.content?.links?.image || null,
+    encryptedDataUri: nftData.content?.metadata?.properties?.files?.[0]?.uri || null,
+    owner: nftData.ownership?.owner || null,
+    // New fields
+    uuid: getAttr('UUID'),
+    timestamp: timestampStr ? parseInt(timestampStr, 10) : null,
+    previousToken: getAttr('Previous Token'),
+    schema: getAttr('Schema'),
+    mimeType: getAttr('MIME Type') || nftData.content?.metadata?.properties?.files?.[0]?.type || null,
+    dataSize: dataSizeStr ? parseInt(dataSizeStr, 10) : null,
+  };
+}