@yallet/rwa-sdk 0.2.0

package/src/storage.ts

@@ -0,0 +1,364 @@
+/**
+ * Yallet RWA SDK - Storage Module
+ *
+ * Handles uploading encrypted data to Arweave via ArDrive Turbo
+ */
+
+import type { EncryptedPayload, AssetType } from './types.js';
+
+// ======================================
+//  Configuration
+// ======================================
+
+const ARWEAVE_GATEWAY = 'https://arweave.net';
+const ARWEAVE_FALLBACK_GATEWAYS = ['https://arweave.net', 'https://ar-io.net', 'https://turbo-gateway.com'];
+const ARWEAVE_TX_ID_RE = /^[A-Za-z0-9_-]{43}$/;
+const ARWEAVE_TXISH_RE = /^[A-Za-z0-9_-]{3,128}$/;
+
+/** Yallet backend upload API (proxy-api forwards to backend-api/ArDrive Turbo) */
+const YALLET_ARWEAVE_UPLOAD_URL = 'https://api.yallet.xyz/api/v1/storage/arweave/upload';
+
+const ARWEAVE_ENDPOINTS = {
+  mainnet: 'https://turbo.irys.xyz',
+  devnet: 'https://devnet.irys.xyz',
+};
+
+/** Uint8Array to base64 (chunked for large payloads) */
+function toBase64(bytes: Uint8Array): string {
+  const chunkSize = 32768;
+  let binary = '';
+  for (let i = 0; i < bytes.length; i += chunkSize) {
+    const chunk = bytes.subarray(i, Math.min(i + chunkSize, bytes.length));
+    binary += String.fromCharCode.apply(null, chunk as unknown as number[]);
+  }
+  return btoa(binary);
+}
+
+function extractArweaveTxId(input: string | null | undefined): string | null {
+  const raw = String(input || '').trim();
+  if (!raw) return null;
+
+  if (raw.startsWith('ar://')) {
+    const tx = raw.substring(5).split('/')[0] || '';
+    if (ARWEAVE_TX_ID_RE.test(tx)) return tx;
+    return ARWEAVE_TXISH_RE.test(tx) ? tx : null;
+  }
+  if (ARWEAVE_TX_ID_RE.test(raw)) {
+    return raw;
+  }
+  if (ARWEAVE_TXISH_RE.test(raw) && !raw.includes('/')) {
+    return raw;
+  }
+
+  try {
+    const u = new URL(raw);
+    const host = u.hostname.toLowerCase();
+    const [pathFirst = '', pathSecond = ''] = u.pathname.replace(/^\/+/, '').split('/');
+
+    if (ARWEAVE_TX_ID_RE.test(pathFirst)) return pathFirst;
+    if (ARWEAVE_TX_ID_RE.test(pathSecond)) return pathSecond;
+    if (ARWEAVE_TXISH_RE.test(pathFirst)) return pathFirst;
+    if (ARWEAVE_TXISH_RE.test(pathSecond)) return pathSecond;
+
+    const subdomainMatch = host.match(/^([a-z0-9_-]{43})\.arweave\.net$/i);
+    if (subdomainMatch && ARWEAVE_TX_ID_RE.test(subdomainMatch[1])) {
+      return subdomainMatch[1];
+    }
+  } catch (_) {
+    return null;
+  }
+
+  return null;
+}
+
+function buildArweaveFetchUrls(input: string): string[] {
+  const out: string[] = [];
+  const push = (u: string | null | undefined): void => {
+    if (!u) return;
+    const v = String(u).trim();
+    if (!v) return;
+    if (!out.includes(v)) out.push(v);
+  };
+
+  const raw = String(input || '').trim();
+  if (!raw) return out;
+
+  // Keep original URL first when caller passes full URL.
+  if (raw.startsWith('http://') || raw.startsWith('https://')) {
+    push(raw);
+  }
+
+  const txId = extractArweaveTxId(raw);
+  if (txId) {
+    for (const gw of ARWEAVE_FALLBACK_GATEWAYS) {
+      push(`${gw}/${txId}`);
+    }
+  }
+
+  return out;
+}
+
+// ======================================
+//  Arweave Upload
+// ======================================
+
+export interface UploadOptions {
+  /** Arweave API key (for ArDrive Turbo uploads) */
+  apiKey?: string;
+  /** Network: mainnet or devnet */
+  network?: 'mainnet' | 'devnet';
+  /** Custom endpoint */
+  endpoint?: string;
+  /** Content type */
+  contentType?: string;
+  /** Custom tags */
+  tags?: Record<string, string>;
+}
+
+export interface UploadResult {
+  /** Arweave transaction ID */
+  id: string;
+  /** Full Arweave URL */
+  url: string;
+  /** ar:// URI */
+  arweaveUri: string;
+  /** Upload timestamp */
+  timestamp: number;
+}
+
+/**
+ * Upload data to Arweave.
+ * Default: POST to Yallet backend (api.yallet.xyz → backend ArDrive Turbo).
+ * If options.endpoint is set to an Irys URL (e.g. turbo.irys.xyz), uses direct Irys /tx instead.
+ *
+ * @param data - Data to upload (string or Uint8Array)
+ * @param options - Upload options
+ * @returns Upload result with transaction ID
+ */
+export async function uploadToArweave(
+  data: string | Uint8Array,
+  options: UploadOptions = {}
+): Promise<UploadResult> {
+  const {
+    apiKey,
+    network = 'mainnet',
+    endpoint = YALLET_ARWEAVE_UPLOAD_URL,
+    contentType = 'application/octet-stream',
+    tags = {},
+  } = options;
+
+  const dataBytes = typeof data === 'string'
+    ? new TextEncoder().encode(data)
+    : data;
+
+  const allTags = {
+    'Content-Type': contentType,
+    'App-Name': 'Yallet-RWA-SDK',
+    'App-Version': '0.1.0',
+    ...tags,
+  };
+
+  const useYalletApi =
+    !endpoint ||
+    endpoint === YALLET_ARWEAVE_UPLOAD_URL ||
+    endpoint.includes('api.yallet.xyz');
+
+  if (useYalletApi) {
+    const response = await fetch(endpoint, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        data: toBase64(dataBytes),
+        contentType,
+        tags: allTags,
+      }),
+    });
+
+    const result = await response.json().catch(() => ({} as Record<string, unknown>));
+    if (!response.ok) {
+      const msg = (result as { message?: string }).message ?? response.statusText;
+      throw new Error(`Upload failed: ${response.status} - ${msg}`);
+    }
+    if ((result as { success?: boolean }).success !== true) {
+      const msg = (result as { message?: string }).message ?? 'Upload failed';
+      throw new Error(msg);
+    }
+
+    const rawId = (result as { id?: string }).id;
+    const rawUrl = (result as { url?: string }).url;
+    const id = extractArweaveTxId(rawId) || extractArweaveTxId(rawUrl);
+    if (!id) throw new Error('Upload response missing valid Arweave tx id');
+    const url = `${ARWEAVE_GATEWAY}/${id}`;
+
+    return {
+      id,
+      url,
+      arweaveUri: `ar://${id}`,
+      timestamp: Date.now(),
+    };
+  }
+
+  // Legacy: direct Irys/Turbo
+  const headers: Record<string, string> = { 'Content-Type': contentType };
+  if (apiKey) headers['Authorization'] = `Bearer ${apiKey}`;
+  const irysEndpoint = endpoint || ARWEAVE_ENDPOINTS[network];
+  const response = await fetch(`${irysEndpoint}/tx`, {
+    method: 'POST',
+    headers,
+    body: dataBytes as BodyInit,
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`Upload failed: ${response.status} - ${errorText}`);
+  }
+
+  const result = await response.json() as { id?: string; url?: string };
+  const txId = extractArweaveTxId(result.id) || extractArweaveTxId(result.url);
+  if (!txId) throw new Error('Upload response missing valid Arweave tx id');
+
+  return {
+    id: txId,
+    url: `${ARWEAVE_GATEWAY}/${txId}`,
+    arweaveUri: `ar://${txId}`,
+    timestamp: Date.now(),
+  };
+}
+
+/**
+ * Upload encrypted asset to Arweave
+ *
+ * @param encryptedPayload - Encrypted asset data (with extended fields)
+ * @param metadata - Additional metadata
+ * @param options - Upload options
+ * @returns Upload result
+ */
+export async function uploadEncryptedAsset(
+  encryptedPayload: EncryptedPayload & {
+    assetType: AssetType;
+    version: number;
+    uuid?: string;
+    timestamp?: number;
+    dataSize?: number;
+  },
+  metadata: {
+    assetType: AssetType;
+    direction?: 'owned' | 'sent' | 'received';
+    network?: 'mainnet' | 'devnet';
+  },
+  options: UploadOptions = {}
+): Promise<UploadResult> {
+  const payload = {
+    encrypted: {
+      ephemeral_pub: encryptedPayload.ephemeral_pub,
+      encrypted_aes_key: encryptedPayload.encrypted_aes_key,
+      iv: encryptedPayload.iv,
+      encrypted_data: encryptedPayload.encrypted_data,
+    },
+    metadata: {
+      ...metadata,
+      version: encryptedPayload.version,
+      uuid: encryptedPayload.uuid,
+      timestamp: encryptedPayload.timestamp,
+      dataSize: encryptedPayload.dataSize,
+      uploadedAt: Date.now(),
+    },
+  };
+
+  const jsonString = JSON.stringify(payload);
+
+  return uploadToArweave(jsonString, {
+    ...options,
+    contentType: 'application/json',
+    tags: {
+      'Yallet-Type': 'encrypted-asset',
+      'Asset-Type': metadata.assetType,
+      'Direction': metadata.direction || 'sent',
+      'Network': metadata.network || options.network || 'mainnet',
+      ...(encryptedPayload.uuid ? { 'UUID': encryptedPayload.uuid } : {}),
+      ...options.tags,
+    },
+  });
+}
+
+/**
+ * Upload NFT metadata to Arweave
+ *
+ * @param metadata - NFT metadata object
+ * @param options - Upload options
+ * @returns Upload result
+ */
+export async function uploadMetadata(
+  metadata: Record<string, unknown>,
+  options: UploadOptions = {}
+): Promise<UploadResult> {
+  const jsonString = JSON.stringify(metadata);
+
+  return uploadToArweave(jsonString, {
+    ...options,
+    contentType: 'application/json',
+    tags: {
+      'Content-Type': 'application/json',
+      'Type': 'nft-metadata',
+      ...options.tags,
+    },
+  });
+}
+
+/**
+ * Download data from Arweave
+ *
+ * @param txIdOrUri - Transaction ID or ar:// URI
+ * @returns Fetched data
+ */
+export async function downloadFromArweave(txIdOrUri: string): Promise<Response> {
+  const urls = buildArweaveFetchUrls(txIdOrUri);
+  if (urls.length === 0) {
+    throw new Error('Invalid Arweave tx id or URI');
+  }
+
+  let lastError: Error | null = null;
+
+  for (const url of urls) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 30000);
+
+    try {
+      const response = await fetch(url, { signal: controller.signal });
+      if (!response) {
+        if (!lastError) {
+          lastError = new Error('Download failed: empty response');
+        }
+        continue;
+      }
+      if (!response.ok) {
+        lastError = new Error(`Download failed: ${response.status}`);
+        continue;
+      }
+      return response;
+    } catch (err) {
+      if (err instanceof Error && err.name === 'AbortError') {
+        lastError = new Error('Download timeout');
+      } else {
+        lastError = err instanceof Error ? err : new Error(String(err));
+      }
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  throw lastError || new Error('Download failed');
+}
+
+/**
+ * Download and parse JSON from Arweave
+ *
+ * @param txIdOrUri - Transaction ID or ar:// URI
+ * @returns Parsed JSON
+ */
+export async function downloadJsonFromArweave<T = unknown>(
+  txIdOrUri: string
+): Promise<T> {
+  const response = await downloadFromArweave(txIdOrUri);
+  return response.json() as Promise<T>;
+}

package/src/types.ts

@@ -0,0 +1,318 @@
+/**
+ * Yallet RWA SDK - Type Definitions
+ */
+
+// ======================================
+//  Asset Types
+// ======================================
+
+/**
+ * Supported RWA asset types
+ * Matches chrome-extension RWA_ASSET_TYPES for compatibility (no statement/receipt in extension).
+ */
+export enum AssetType {
+  NOTE = 'note',
+  INVOICE = 'invoice',
+  PHOTO = 'photo',
+  FILE = 'file',
+  CONTACT = 'contact',
+}
+
+/**
+ * Invoice data structure
+ * Aligns with chrome-extension invoice format for decrypt compatibility.
+ */
+export interface InvoiceData {
+  /** Unique invoice ID/number (extension: invoiceNo) */
+  invoiceId: string;
+  /** Invoice amount / total */
+  amount: number;
+  /** Currency code (e.g., 'USD', 'EUR') */
+  currency: string;
+  /** Invoice date (ISO string) */
+  date: string;
+  /** Due date (ISO string) (extension: dueDate) */
+  dueDate?: string;
+  /** Invoice description */
+  description?: string;
+  /** Line items (extension: lineItems with name, price, qty, unit, total) */
+  items?: InvoiceItem[];
+  /** Additional notes (extension: notePayee) */
+  notes?: string;
+  /** Custom metadata */
+  metadata?: Record<string, unknown>;
+  /** Extension-compat: billTo contact id */
+  billTo?: string;
+  /** Extension-compat: PO number */
+  poNo?: string;
+  /** Extension-compat: discount rate 0-100 */
+  discountRate?: number;
+  /** Extension-compat: discount amount */
+  discountAmount?: number;
+  /** Extension-compat: tax rate 0-100 */
+  taxRate?: number;
+  /** Extension-compat: subtotal */
+  subtotal?: number;
+  /** Extension-compat: tax amount */
+  taxAmount?: number;
+  /** Extension-compat: total (same as amount) */
+  total?: number;
+  /** Extension-compat: payment method 'bank' | 'crypto' */
+  paymentMethod?: string;
+  /** Extension-compat: payment terms */
+  paymentTerms?: string;
+  /** Extension-compat: note to payee */
+  notePayee?: string;
+}
+
+export interface InvoiceItem {
+  description: string;
+  quantity: number;
+  unitPrice: number;
+  amount: number;
+  /** Extension-compat: line item name (same as description) */
+  name?: string;
+  /** Extension-compat: unit e.g. 'units' | 'hours' */
+  unit?: string;
+  /** Extension-compat: qty (same as quantity) */
+  qty?: number;
+  /** Extension-compat: total (same as amount) */
+  total?: number;
+}
+
+/**
+ * Note data structure
+ */
+export interface NoteData {
+  title: string;
+  content: string;
+  tags?: string[];
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Contact data structure
+ */
+export interface ContactData {
+  name: string;
+  email?: string;
+  phone?: string;
+  company?: string;
+  address?: string;
+  notes?: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * File data structure
+ */
+export interface FileData {
+  filename: string;
+  mimeType: string;
+  /** Base64 encoded file content */
+  content: string;
+  size: number;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Photo data structure
+ */
+export interface PhotoData {
+  filename: string;
+  mimeType: string;
+  /** Base64 encoded image content */
+  content: string;
+  width?: number;
+  height?: number;
+  metadata?: Record<string, unknown>;
+}
+
+// ======================================
+//  Encryption Types
+// ======================================
+
+/**
+ * Encrypted payload structure (ECIES)
+ */
+export interface EncryptedPayload {
+  /** Ephemeral public key (base64) */
+  ephemeral_pub: string;
+  /** Encrypted AES key (base64) */
+  encrypted_aes_key: string;
+  /** Initialization vector (base64) */
+  iv: string;
+  /** Encrypted data (base64) */
+  encrypted_data: string;
+}
+
+/**
+ * Asset envelope for encryption
+ */
+export interface AssetEnvelope {
+  version: number;
+  type: AssetType;
+  timestamp: number;
+  uuid: string;
+  schema?: string;
+  previousToken?: string;
+  data: unknown;
+}
+
+/**
+ * Encrypt function signature (compatible with WASM)
+ */
+export type EncryptFunction = (
+  recipientXidentityB64: string,
+  plaintext: Uint8Array
+) => string; // Returns JSON string or "error:..."
+
+// ======================================
+//  User Registry Types
+// ======================================
+
+/**
+ * Registered user with xidentity
+ */
+export interface RegisteredUser {
+  /** User's Solana wallet address */
+  solanaAddress: string;
+  /** User's xidentity public key (base64) */
+  xidentity: string;
+  /** Optional display name */
+  name?: string;
+  /** Optional email */
+  email?: string;
+  /** Registration timestamp */
+  registeredAt: number;
+  /** Additional metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * User registry interface
+ */
+export interface UserRegistry {
+  /** Get user by Solana address */
+  getUser(solanaAddress: string): Promise<RegisteredUser | null>;
+  /** Register a new user */
+  registerUser(user: RegisteredUser): Promise<void>;
+  /** Update user */
+  updateUser(solanaAddress: string, updates: Partial<RegisteredUser>): Promise<void>;
+  /** Delete user */
+  deleteUser(solanaAddress: string): Promise<void>;
+  /** List all users */
+  listUsers(): Promise<RegisteredUser[]>;
+}
+
+// ======================================
+//  Minting Types
+// ======================================
+
+/**
+ * Mint request parameters
+ */
+export interface MintRequest {
+  /** Asset type */
+  assetType: AssetType;
+  /** Asset data (InvoiceData, NoteData, ContactData, FileData, PhotoData) */
+  assetData: InvoiceData | NoteData | ContactData | FileData | PhotoData;
+  /** Recipient's Solana address */
+  recipientAddress: string;
+  /** NFT name */
+  name: string;
+  /** NFT description */
+  description?: string;
+  /** Additional NFT attributes */
+  attributes?: Array<{ trait_type: string; value: string }>;
+  /** Unique identifier for tracking (auto-generated if not provided) */
+  uuid?: string;
+  /** Previous token address for version chain (null for first version) */
+  previousToken?: string;
+  /** Schema identifier for data format validation */
+  schema?: string;
+  /** MIME type of the asset content */
+  mimeType?: string;
+  /** Size of the encrypted data in bytes */
+  dataSize?: number;
+}
+
+/**
+ * Mint result
+ */
+export interface MintResult {
+  /** Whether minting was successful */
+  success: boolean;
+  /** Asset ID (Solana address of the NFT) */
+  assetId?: string;
+  /** Transaction signature */
+  signature?: string;
+  /** Arweave transaction ID for encrypted data */
+  arweaveTxId?: string;
+  /** Arweave transaction ID for metadata */
+  metadataArweaveTxId?: string;
+  /** UUID used for this mint */
+  uuid?: string;
+  /** Error message if failed */
+  error?: string;
+}
+
+// ======================================
+//  Tree Management Types
+// ======================================
+
+/**
+ * Merkle tree configuration
+ */
+export interface TreeConfig {
+  /** Tree address (Solana pubkey) */
+  treeAddress: string;
+  /** Tree authority address */
+  treeAuthority: string;
+  /** Maximum depth */
+  maxDepth: number;
+  /** Total capacity */
+  capacity: number;
+  /** Current usage */
+  used: number;
+  /** Remaining slots */
+  remaining: number;
+  /** Usage percentage */
+  usagePercent: number;
+}
+
+// ======================================
+//  SDK Configuration Types
+// ======================================
+
+/**
+ * SDK configuration options
+ */
+export interface SDKConfig {
+  /** Solana RPC endpoint */
+  rpcEndpoint: string;
+  /** Network: 'mainnet' or 'devnet' */
+  network: 'mainnet' | 'devnet';
+  /** Merkle tree address (optional, will use backend if not provided) */
+  merkleTreeAddress?: string;
+  /** Merkle tree authority */
+  merkleTreeAuthority?: string;
+  /** Arweave upload endpoint */
+  arweaveEndpoint?: string;
+  /** Arweave API key for uploads (ArDrive Turbo) */
+  arweaveApiKey?: string;
+  /** Backend API URL for tree management */
+  backendApiUrl?: string;
+}
+
+/**
+ * Signer interface for transaction signing
+ */
+export interface Signer {
+  /** Solana public key (base58) */
+  publicKey: string;
+  /** Sign transaction */
+  signTransaction(tx: Uint8Array): Promise<Uint8Array>;
+  /** Sign message */
+  signMessage(message: Uint8Array): Promise<Uint8Array>;
+}

package/wasm/README.md

@@ -0,0 +1,33 @@
+# ACEGF WASM directory
+
+This directory holds the WASM build artifacts from [acegf-wallet](https://github.com/phaykhe/yallet-chrome), used by the RWA SDK at runtime for end-to-end encryption compatible with the Yallet extension.
+
+## How to build and place WASM
+
+1. In the **acegf-wallet** repo root, run:
+   ```bash
+   wasm-pack build --target web
+   ```
+2. Copy the generated artifacts into this SDK's `wasm/` directory:
+   ```bash
+   cp /path/to/acegf-wallet/pkg/acegf_bg.wasm /path/to/dev.yallet.rwa-sdk/wasm/
+   cp /path/to/acegf-wallet/pkg/acegf.js       /path/to/dev.yallet.rwa-sdk/wasm/
+   cp /path/to/acegf-wallet/pkg/acegf.d.ts     /path/to/dev.yallet.rwa-sdk/wasm/
+   ```
+3. When publishing or packing the SDK, the `wasm/` directory is included via the `files` field in `package.json`.
+
+## Initializing WASM in your app
+
+The SDK does not load WASM automatically; the caller must initialize acegf and pass the encrypt function:
+
+```ts
+import init from '@yallet/rwa-sdk/wasm/acegf.js';  // or your copy path
+import { createRWASDK, createWasmEncryptor } from '@yallet/rwa-sdk';
+
+const acegf = await init();  // optional wasm path: init('/path/to/acegf_bg.wasm')
+const encryptFn = createWasmEncryptor(acegf.acegf_encrypt_for_xidentity);
+
+const sdk = createRWASDK(config, { wasmEncryptFn: encryptFn });
+```
+
+If you do not pass `wasmEncryptFn`, the SDK uses its built-in pure JS ECIES implementation (decryption in the Yallet extension may not match exactly; prefer WASM in production).