@totemsdk/core 1.0.0

package/src/scripts/dapp-types.ts

@@ -0,0 +1,240 @@
+export const TOTEM_SEND_TRANSACTION_VERSION = 1;
+
+export type DAppTransactionIntent =
+  | 'send'
+  | 'token_send'
+  | 'swap'
+  | 'liquidity_add'
+  | 'liquidity_remove'
+  | 'contract_call'
+  | 'multisig'
+  | 'timelock'
+  | 'htlc'
+  | 'custom';
+
+export interface DAppStateVariable {
+  port: number;
+  value: string;
+  type?: 'number' | 'string' | 'hex' | 'address';
+}
+
+export interface DAppTransactionOutput {
+  address: string;
+  amount: string;
+  tokenId?: string;
+  state?: DAppStateVariable[];
+  storeState?: boolean;
+  script?: string;
+  scriptRef?: string;
+}
+
+export interface DAppTransactionInput {
+  coinId: string;
+  address?: string;
+  amount?: string;
+  tokenId?: string;
+}
+
+export interface DAppSwapParams {
+  fromTokenId: string;
+  toTokenId: string;
+  amountIn: string;
+  minAmountOut: string;
+  slippageBps?: number;
+  poolAddress?: string;
+}
+
+export interface DAppLiquidityParams {
+  poolAddress: string;
+  tokenAId: string;
+  tokenBId: string;
+  amountA?: string;
+  amountB?: string;
+  lpTokenAmount?: string;
+}
+
+export interface DAppMultisigParams {
+  requiredSignatures: number;
+  publicKeys: string[];
+  timeoutBlocks?: number;
+}
+
+export interface DAppTimelockParams {
+  releaseBlock: number;
+  fallbackAddress?: string;
+}
+
+export interface DAppHtlcParams {
+  hashlock: string;
+  timeoutBlocks: number;
+  recipientAddress: string;
+  refundAddress: string;
+}
+
+export interface DAppContractCallParams {
+  contractAddress: string;
+  method?: string;
+  args?: Record<string, string>;
+  script?: string;
+}
+
+export interface TotemSendTransactionRequest {
+  version: typeof TOTEM_SEND_TRANSACTION_VERSION;
+  intent: DAppTransactionIntent;
+  outputs: DAppTransactionOutput[];
+  inputs?: DAppTransactionInput[];
+  burn?: string;
+  memo?: string;
+  metadata?: {
+    appName?: string;
+    description?: string;
+    iconUrl?: string;
+  };
+  options?: {
+    verifyWithTotemidea?: boolean;
+    skipPreview?: boolean;
+    useSourceAddress?: string;
+    excludeAddresses?: string[];
+  };
+  swap?: DAppSwapParams;
+  liquidity?: DAppLiquidityParams;
+  multisig?: DAppMultisigParams;
+  timelock?: DAppTimelockParams;
+  htlc?: DAppHtlcParams;
+  contract?: DAppContractCallParams;
+}
+
+export interface TotemSendTransactionResponse {
+  success: boolean;
+  txpowid?: string;
+  status?: 'pending' | 'submitted' | 'confirmed' | 'rejected';
+  artifactId?: string;
+  digestHex?: string;
+  error?: string;
+  errorCode?: TotemTransactionErrorCode;
+  verification?: {
+    totemideaValid?: boolean;
+    totemideaWarnings?: string[];
+    totemideaNotes?: string[];
+  };
+}
+
+export type TotemTransactionErrorCode =
+  | 'INVALID_REQUEST'
+  | 'INSUFFICIENT_FUNDS'
+  | 'PERMISSION_DENIED'
+  | 'USER_REJECTED'
+  | 'SITE_NOT_CONNECTED'
+  | 'SPENDING_LIMIT_EXCEEDED'
+  | 'TOKEN_NOT_ALLOWED'
+  | 'VERIFICATION_FAILED'
+  | 'BUILD_FAILED'
+  | 'SIGN_FAILED'
+  | 'BROADCAST_FAILED'
+  | 'TIMEOUT';
+
+export interface SiteTransactionPermission {
+  origin: string;
+  grantedAt: number;
+  expiresAt: number;
+  scopes: TransactionScope[];
+}
+
+export interface TransactionScope {
+  tokenId: string;
+  tokenSymbol?: string;
+  maxAmountPerTx: string;
+  maxDailyAmount: string;
+  dailyUsed: string;
+  lastResetDate: string;
+  allowedIntents: DAppTransactionIntent[];
+}
+
+export function validateSendTransactionRequest(request: unknown): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  if (!request || typeof request !== 'object') {
+    return { valid: false, errors: ['Request must be an object'] };
+  }
+
+  const req = request as Record<string, unknown>;
+
+  if (req.version !== TOTEM_SEND_TRANSACTION_VERSION) {
+    errors.push(`Invalid version: expected ${TOTEM_SEND_TRANSACTION_VERSION}, got ${req.version}`);
+  }
+
+  const validIntents: DAppTransactionIntent[] = [
+    'send', 'token_send', 'swap', 'liquidity_add', 'liquidity_remove',
+    'contract_call', 'multisig', 'timelock', 'htlc', 'custom'
+  ];
+  if (!validIntents.includes(req.intent as DAppTransactionIntent)) {
+    errors.push(`Invalid intent: ${req.intent}. Must be one of: ${validIntents.join(', ')}`);
+  }
+
+  if (!Array.isArray(req.outputs) || req.outputs.length === 0) {
+    errors.push('outputs must be a non-empty array');
+  } else {
+    for (let i = 0; i < req.outputs.length; i++) {
+      const output = req.outputs[i] as Record<string, unknown>;
+      if (!output.address || typeof output.address !== 'string') {
+        errors.push(`outputs[${i}].address is required and must be a string`);
+      }
+      if (!output.amount || typeof output.amount !== 'string') {
+        errors.push(`outputs[${i}].amount is required and must be a string`);
+      }
+      const amountNum = parseFloat(output.amount as string);
+      if (isNaN(amountNum) || amountNum <= 0) {
+        errors.push(`outputs[${i}].amount must be a positive number`);
+      }
+    }
+  }
+
+  if (req.burn !== undefined) {
+    const burnNum = parseFloat(req.burn as string);
+    if (isNaN(burnNum) || burnNum < 0) {
+      errors.push('burn must be a non-negative number string');
+    }
+  }
+
+  if (req.intent === 'swap' && !req.swap) {
+    errors.push('swap params required for swap intent');
+  }
+
+  if ((req.intent === 'liquidity_add' || req.intent === 'liquidity_remove') && !req.liquidity) {
+    errors.push('liquidity params required for liquidity intent');
+  }
+
+  if (req.intent === 'multisig' && !req.multisig) {
+    errors.push('multisig params required for multisig intent');
+  }
+
+  if (req.intent === 'timelock' && !req.timelock) {
+    errors.push('timelock params required for timelock intent');
+  }
+
+  if (req.intent === 'htlc' && !req.htlc) {
+    errors.push('htlc params required for htlc intent');
+  }
+
+  if (req.intent === 'contract_call' && !req.contract) {
+    errors.push('contract params required for contract_call intent');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+export function simpleTotemSendRequest(
+  to: string,
+  amount: string,
+  tokenId?: string
+): TotemSendTransactionRequest {
+  return {
+    version: TOTEM_SEND_TRANSACTION_VERSION,
+    intent: tokenId && tokenId !== '0x00' ? 'token_send' : 'send',
+    outputs: [{
+      address: to,
+      amount,
+      tokenId: tokenId || '0x00'
+    }]
+  };
+}

package/src/scripts/index.ts

@@ -0,0 +1,22 @@
+export * from './types.js';
+export * from './dapp-types.js';
+export {
+  encodeMiniNumber,
+  encodeMiniData,
+  encodeMiniString,
+  serializeMMRProofChunk,
+  serializeScriptProofWithProof,
+  STATETYPE_HEX,
+  STATETYPE_NUMBER,
+  STATETYPE_STRING,
+  STATETYPE_BOOL,
+  encodeStateValue,
+  serializeStateVariables,
+  buildScriptProofFromDescriptor,
+  deduplicateScriptDescriptors,
+  serializeExtraScripts,
+  aggregateSignatures,
+  validateExternalSignature,
+  computeScriptAddress,
+} from './witness-serializer.js';
+export * from './contract-helpers.js';

package/src/scripts/types.ts

@@ -0,0 +1,247 @@
+import type { MMRData, MMRProofChunk, MMRProof } from '../mmr.js';
+export type { MMRProof };
+
+function kissHex(hex: string): string {
+  const raw = hex.startsWith('0x') || hex.startsWith('0X') ? hex.slice(2) : hex;
+  return '0x' + raw.toUpperCase();
+}
+
+export type StateVariableType = 'STATE' | 'PREVSTATE' | 'SAMESTATE';
+
+export interface StateValue {
+  port: number;
+  value: string | bigint | Uint8Array | boolean;
+  type: 'bool' | 'number' | 'hex' | 'string';
+}
+
+export interface VerifyOutExpectation {
+  inputIndex: number | '@INPUT';
+  outputAddress: string;
+  amount: string | bigint;
+  tokenId: string;
+  keepState: boolean;
+}
+
+export type ScriptType =
+  | 'signedby'
+  | 'multisig'
+  | 'multisig_mofn'
+  | 'timelock'
+  | 'htlc'
+  | 'mast'
+  | 'exchange'
+  | 'vault'
+  | 'flashcash'
+  | 'slowcash'
+  | 'stateful'
+  | 'custom';
+
+export interface ScriptDescriptor {
+  address: string;
+  scriptType: ScriptType;
+  script: string;
+  wotsRootPublicKey?: string;
+  mastProof?: MMRProof;
+  extraScripts?: Map<string, string>;
+  stateVariables?: StateValue[];
+  storeState?: boolean;
+  verifyOutExpectations?: VerifyOutExpectation[];
+  timelockBlock?: bigint;
+  htlcHash?: string;
+  htlcPreimage?: string;
+  multisigKeys?: string[];
+  multisigThreshold?: number;
+  externalSignatures?: ExternalSignature[];
+}
+
+export interface ExternalSignature {
+  publicKey: string;
+  signature: string;
+  proof?: MMRProof;
+  signatureType: 'wots' | 'standard';
+  validated?: boolean;
+}
+
+export interface ScriptCatalogEntry {
+  address: string;
+  script: string;
+  scriptType: ScriptType;
+  createdAt: number;
+  lastUsed: number;
+}
+
+export interface ScriptProofResult {
+  script: string;
+  proof: MMRProof;
+  serialized: Uint8Array;
+}
+
+export interface TransactionRoundState {
+  round: number;
+  previousRound: number;
+  preservedPorts: number[];
+  newStates: StateValue[];
+}
+
+export interface FlatMMRProofChunk {
+  isLeft: boolean;
+  data: Uint8Array;
+}
+
+export interface LegacyMMRProof {
+  blockTime: bigint;
+  proofChain: FlatMMRProofChunk[];
+}
+
+export function convertFlatChunkToSDK(chunk: FlatMMRProofChunk): MMRProofChunk {
+  return {
+    isLeft: chunk.isLeft,
+    mmrData: { data: chunk.data, value: 0n }
+  };
+}
+
+export function convertLegacyProofToSDK(legacy: LegacyMMRProof): { proof: MMRProof; blockTime: bigint } {
+  return {
+    proof: {
+      chunks: legacy.proofChain.map(convertFlatChunkToSDK)
+    },
+    blockTime: legacy.blockTime
+  };
+}
+
+export function createEmptyMMRProof(): MMRProof {
+  return { chunks: [] };
+}
+
+export function createSignedByDescriptor(address: string, wotsRootPublicKey: string): ScriptDescriptor {
+  return {
+    address,
+    scriptType: 'signedby',
+    script: `RETURN SIGNEDBY(${kissHex(wotsRootPublicKey)})`,
+    wotsRootPublicKey,
+    mastProof: createEmptyMMRProof(),
+    storeState: false
+  };
+}
+
+export function createMultisigDescriptor(address: string, publicKey1: string, publicKey2: string, ownPublicKey: string): ScriptDescriptor {
+  return {
+    address,
+    scriptType: 'multisig',
+    script: `RETURN SIGNEDBY(${kissHex(publicKey1)}) AND SIGNEDBY(${kissHex(publicKey2)})`,
+    wotsRootPublicKey: ownPublicKey,
+    multisigKeys: [publicKey1, publicKey2],
+    multisigThreshold: 2,
+    mastProof: createEmptyMMRProof(),
+    storeState: false
+  };
+}
+
+export function createMofNMultisigDescriptor(address: string, threshold: number, publicKeys: string[], ownPublicKey: string): ScriptDescriptor {
+  const formattedKeys = publicKeys.map(pk => kissHex(pk)).join(' ');
+  return {
+    address,
+    scriptType: 'multisig_mofn',
+    script: `RETURN MULTISIG(${threshold} ${formattedKeys})`,
+    wotsRootPublicKey: ownPublicKey,
+    multisigKeys: publicKeys,
+    multisigThreshold: threshold,
+    mastProof: createEmptyMMRProof(),
+    storeState: false
+  };
+}
+
+export function createTimelockDescriptor(address: string, publicKey: string, unlockBlock: bigint): ScriptDescriptor {
+  return {
+    address,
+    scriptType: 'timelock',
+    script: `RETURN SIGNEDBY(${kissHex(publicKey)}) AND @BLOCK GT ${unlockBlock}`,
+    wotsRootPublicKey: publicKey,
+    timelockBlock: unlockBlock,
+    mastProof: createEmptyMMRProof(),
+    storeState: false
+  };
+}
+
+export function createHTLCDescriptor(address: string, ownerPublicKey: string, recipientPublicKey: string, hashLock: string, timeoutBlock: bigint, isOwner: boolean, preimage?: string): ScriptDescriptor {
+  const script = `IF @BLOCK GT ${timeoutBlock} AND SIGNEDBY(${kissHex(ownerPublicKey)}) THEN RETURN TRUE ENDIF RETURN (SIGNEDBY(${kissHex(recipientPublicKey)}) AND SHA3(STATE(1)) EQ ${kissHex(hashLock)})`;
+  const descriptor: ScriptDescriptor = {
+    address,
+    scriptType: 'htlc',
+    script,
+    wotsRootPublicKey: isOwner ? ownerPublicKey : recipientPublicKey,
+    htlcHash: hashLock,
+    timelockBlock: timeoutBlock,
+    mastProof: createEmptyMMRProof(),
+    storeState: false
+  };
+  if (preimage) {
+    descriptor.htlcPreimage = preimage;
+    descriptor.stateVariables = [{ port: 1, value: preimage, type: 'string' }];
+  }
+  return descriptor;
+}
+
+export function createMASTDescriptor(address: string, rootHash: string, branchScript: string, branchProof: string, wotsPublicKey?: string): ScriptDescriptor {
+  return {
+    address,
+    scriptType: 'mast',
+    script: `MAST ${kissHex(rootHash)}`,
+    wotsRootPublicKey: wotsPublicKey,
+    extraScripts: new Map([[branchScript, branchProof]]),
+    mastProof: createEmptyMMRProof(),
+    storeState: false
+  };
+}
+
+export function createExchangeDescriptor(address: string, ownerPublicKey: string, desiredAddress: string, desiredAmount: string, desiredTokenId: string): ScriptDescriptor {
+  const ownerPk = kissHex(ownerPublicKey);
+  const script = `IF SIGNEDBY(PREVSTATE(0)) THEN RETURN TRUE ENDIF ASSERT VERIFYOUT(@INPUT PREVSTATE(1) PREVSTATE(2) PREVSTATE(3) TRUE) RETURN TRUE`;
+  return {
+    address,
+    scriptType: 'exchange',
+    script,
+    wotsRootPublicKey: ownerPublicKey,
+    stateVariables: [
+      { port: 0, value: ownerPk, type: 'hex' },
+      { port: 1, value: desiredAddress, type: 'hex' },
+      { port: 2, value: desiredAmount, type: 'number' },
+      { port: 3, value: desiredTokenId, type: 'hex' }
+    ],
+    verifyOutExpectations: [{
+      inputIndex: '@INPUT',
+      outputAddress: desiredAddress,
+      amount: desiredAmount,
+      tokenId: desiredTokenId,
+      keepState: true
+    }],
+    mastProof: createEmptyMMRProof(),
+    storeState: true
+  };
+}
+
+export function createFlashCashDescriptor(address: string, ownerPublicKey: string, interestMultiplier: string = '1.01'): ScriptDescriptor {
+  const script = `IF SIGNEDBY(PREVSTATE(1)) THEN RETURN TRUE ENDIF ASSERT SAMESTATE(1 1) RETURN VERIFYOUT(@INPUT @ADDRESS @AMOUNT*${interestMultiplier} @TOKENID TRUE)`;
+  return {
+    address,
+    scriptType: 'flashcash',
+    script,
+    wotsRootPublicKey: ownerPublicKey,
+    stateVariables: [{ port: 1, value: ownerPublicKey, type: 'hex' }],
+    mastProof: createEmptyMMRProof(),
+    storeState: true
+  };
+}
+
+export function createSlowCashDescriptor(address: string, ownerPublicKey: string, withdrawalPercent: string = '0.9', cooldownBlocks: bigint = 10000n): ScriptDescriptor {
+  const script = `IF @COINAGE LT ${cooldownBlocks} THEN RETURN FALSE ENDIF ASSERT SIGNEDBY(${kissHex(ownerPublicKey)}) AND VERIFYOUT(@INPUT @ADDRESS @AMOUNT*${withdrawalPercent} @TOKENID TRUE)`;
+  return {
+    address,
+    scriptType: 'slowcash',
+    script,
+    wotsRootPublicKey: ownerPublicKey,
+    timelockBlock: cooldownBlocks,
+    mastProof: createEmptyMMRProof(),
+    storeState: false
+  };
+}