lampamazaza-new-intents-sdk 0.47.1

package/dist/src/shared-types.d.ts

@@ -0,0 +1,378 @@
+import { HotBridgeEVMChain } from "./bridges/hot-bridge/hot-bridge-chains.js";
+import { BridgeNameEnumValues } from "./constants/bridge-name-enum.js";
+import { RouteEnum, RouteEnumValues } from "./constants/route-enum.js";
+import { IntentHash, IntentPayloadFactory, IntentPrimitive, IntentRelayParamsFactory, MultiPayload } from "./intents/shared-types.js";
+import { IIntentSigner } from "./intents/interfaces/intent-signer.js";
+import { OnBeforePublishIntentHook } from "./intents/intent-executer-impl/intent-executer.js";
+import { Chain, Chains } from "./lib/caip2.js";
+import { ILogger, solverRelay } from "lampamazaza-internal-utils";
+
+//#region src/shared-types.d.ts
+interface IntentPublishResult {
+  intentHash: IntentHash;
+}
+interface WithdrawalResult {
+  feeEstimation: FeeEstimation;
+  intentHash: IntentHash;
+  intentTx: NearTxInfo;
+  destinationTx: TxInfo | TxNoInfo;
+}
+interface BatchWithdrawalResult {
+  feeEstimation: FeeEstimation[];
+  intentHash: IntentHash;
+  intentTx: NearTxInfo;
+  destinationTx: (TxInfo | TxNoInfo)[];
+}
+type IntentSettlementStatus = solverRelay.GetStatusReturnType;
+/**
+ * Configuration for including pre-signed intents to be published atomically.
+ *
+ * Pre-signed intents can be included in two ways:
+ * - `before`: Pre-signed intents that execute before the newly created intent
+ * - `after`: Pre-signed intents that execute after the newly created intent
+ *
+ * The execution order is guaranteed: before → new intent → after
+ *
+ * @example
+ * ```typescript
+ * // Include pre-signed intents from other users
+ * const signedIntents: SignedIntents = {
+ *   before: [signedIntent1, signedIntent2],
+ *   after: [cleanupIntent],
+ * };
+ *
+ * await sdk.signAndSendIntent({
+ *   intents: [myNewIntent],
+ *   signedIntents,
+ * });
+ * ```
+ */
+interface SignedIntentsComposition {
+  /**
+   * Pre-signed intents (MultiPayload) to execute before the newly created intent.
+   * Useful for dependencies that must be executed first.
+   */
+  before?: MultiPayload[];
+  /**
+   * Pre-signed intents (MultiPayload) to execute after the newly created intent.
+   * Useful for cleanup or follow-up actions.
+   */
+  after?: MultiPayload[];
+}
+interface SignAndSendArgs {
+  intents: IntentPrimitive[];
+  /**
+   * Factory function to modify the intent payload draft before signing.
+   * Use this to add or modify intent primitives in the payload.
+   *
+   * @example
+   * ```typescript
+   * payload: (draft) => ({
+   *   intents: [...draft.intents, { intent: "transfer", ... }]
+   * })
+   * ```
+   */
+  payload?: IntentPayloadFactory;
+  relayParams?: IntentRelayParamsFactory;
+  signer?: IIntentSigner;
+  onBeforePublishIntent?: OnBeforePublishIntentHook;
+  /**
+   * Pre-signed intents for atomic execution.
+   * The newly created intent will be published together with these pre-signed intents.
+   */
+  signedIntents?: SignedIntentsComposition;
+  logger?: ILogger;
+}
+type SignAndSendWithdrawalArgs<T extends WithdrawalParams | WithdrawalParams[]> = {
+  withdrawalParams: T;
+  feeEstimation: T extends WithdrawalParams[] ? FeeEstimation[] : FeeEstimation;
+  referral?: string;
+  intent?: Omit<SignAndSendArgs, "logger" | "intents">;
+  logger?: ILogger;
+};
+type ProcessWithdrawalArgs<T extends WithdrawalParams | WithdrawalParams[]> = {
+  withdrawalParams: T;
+  feeEstimation?: T extends WithdrawalParams[] ? FeeEstimation[] : FeeEstimation;
+  intent?: {
+    /** @see SignAndSendArgs.payload */
+    payload?: IntentPayloadFactory;
+    /** @see SignAndSendArgs.relayParams */
+    relayParams?: IntentRelayParamsFactory;
+    /** @see SignAndSendArgs.signer */
+    signer?: IIntentSigner;
+    /** @see SignAndSendArgs.onBeforePublishIntent */
+    onBeforePublishIntent?: OnBeforePublishIntentHook;
+    /** @see SignAndSendArgs.signedIntents */
+    signedIntents?: SignedIntentsComposition;
+  };
+  referral?: string;
+  logger?: ILogger;
+};
+interface IIntentsSDK {
+  setIntentSigner(signer: IIntentSigner): void;
+  sendSignedIntents(args: {
+    multiPayloads: MultiPayload[];
+    quoteHashes?: string[];
+    logger?: ILogger;
+  }): Promise<{
+    tickets: IntentHash[];
+  }>;
+  signAndSendIntent(args: SignAndSendArgs): Promise<IntentPublishResult>;
+  waitForIntentSettlement(args: {
+    intentHash: IntentHash;
+    /** AbortSignal for cancellation/timeout. Use AbortSignal.timeout(ms) for timeout. */
+    signal?: AbortSignal;
+    logger?: ILogger;
+  }): Promise<NearTxInfo>;
+  getIntentStatus(args: {
+    intentHash: IntentHash;
+    logger?: ILogger;
+  }): Promise<IntentSettlementStatus>;
+  invalidateNonces(args: {
+    nonces: string[];
+    signer?: IIntentSigner;
+    logger?: ILogger;
+  }): Promise<void>;
+  estimateWithdrawalFee(args: {
+    withdrawalParams: WithdrawalParams;
+    quoteOptions?: QuoteOptions;
+    logger?: ILogger;
+  }): Promise<FeeEstimation>;
+  estimateWithdrawalFee(args: {
+    withdrawalParams: WithdrawalParams[];
+    quoteOptions?: QuoteOptions;
+    logger?: ILogger;
+  }): Promise<FeeEstimation[]>;
+  signAndSendWithdrawalIntent(args: SignAndSendWithdrawalArgs<WithdrawalParams> | SignAndSendWithdrawalArgs<WithdrawalParams[]>): Promise<IntentPublishResult>;
+  waitForWithdrawalCompletion(args: {
+    withdrawalParams: WithdrawalParams;
+    intentTx: NearTxInfo;
+    signal?: AbortSignal;
+    logger?: ILogger;
+  }): Promise<TxInfo | TxNoInfo>;
+  waitForWithdrawalCompletion(args: {
+    withdrawalParams: WithdrawalParams[];
+    intentTx: NearTxInfo;
+    signal?: AbortSignal;
+    logger?: ILogger;
+  }): Promise<Array<TxInfo | TxNoInfo>>;
+  createWithdrawalCompletionPromises(params: CreateWithdrawalCompletionPromisesParams): Array<Promise<TxInfo | TxNoInfo>>;
+  createWithdrawalIntents(args: {
+    withdrawalParams: WithdrawalParams;
+    feeEstimation: FeeEstimation;
+    referral?: string;
+    logger?: ILogger;
+  }): Promise<IntentPrimitive[]>;
+  parseAssetId(assetId: string): ParsedAssetInfo;
+  processWithdrawal(args: ProcessWithdrawalArgs<WithdrawalParams>): Promise<WithdrawalResult>;
+  processWithdrawal(args: ProcessWithdrawalArgs<WithdrawalParams[]>): Promise<BatchWithdrawalResult>;
+}
+interface QuoteOptions {
+  waitMs?: number;
+  minWaitMs?: number;
+  maxWaitMs?: number;
+  trustedMetadata?: unknown;
+}
+interface NearTxInfo {
+  hash: string;
+  accountId: string;
+}
+interface TxInfo {
+  hash: string;
+}
+interface TxNoInfo {
+  hash: null;
+}
+interface CreateWithdrawalCompletionPromisesParams {
+  withdrawalParams: WithdrawalParams[];
+  intentTx: NearTxInfo;
+  signal?: AbortSignal;
+  logger?: ILogger;
+}
+interface WithdrawalParams {
+  assetId: string;
+  amount: bigint;
+  destinationAddress: string;
+  /**
+   * XRP Leger chain specific. MEMO IS NOT SUPPORTED FOR STELLAR AND TON.
+   */
+  destinationMemo?: string | undefined;
+  feeInclusive: boolean;
+  routeConfig?: RouteConfig | undefined;
+}
+type NearWithdrawalRouteConfig = {
+  route: RouteEnum["NearWithdrawal"];
+  msg?: string;
+};
+type InternalTransferRouteConfig = {
+  route: RouteEnum["InternalTransfer"];
+};
+type VirtualChainRouteConfig = {
+  route: RouteEnum["VirtualChain"];
+  auroraEngineContractId: string;
+  proxyTokenContractId: string | null;
+};
+type PoaBridgeRouteConfig = {
+  route: RouteEnum["PoaBridge"];
+};
+type HotBridgeRouteConfig = {
+  route: RouteEnum["HotBridge"];
+  chain: Chain;
+};
+type OmniBridgeRouteConfig = {
+  route: RouteEnum["OmniBridge"];
+  chain?: Chain;
+};
+type RouteConfig = NearWithdrawalRouteConfig | InternalTransferRouteConfig | VirtualChainRouteConfig | PoaBridgeRouteConfig | HotBridgeRouteConfig | OmniBridgeRouteConfig;
+/**
+ * Fee structure definitions for each route type.
+ */
+interface RouteFeeStructures {
+  [RouteEnum.HotBridge]: {
+    /** Relayer fee for processing the withdrawal on destination chain, taken in base token of destination chain. */
+    relayerFee: bigint;
+    /** Block number at the time of fee estimation, required for building gasless withdraw intent. */
+    blockNumber: bigint;
+  };
+  [RouteEnum.PoaBridge]: {
+    /** Relayer fee for POA bridge transfers, taken in transferred token. */
+    relayerFee: bigint;
+  };
+  [RouteEnum.NearWithdrawal]: {
+    /** Fee for nep141 storage deposit in NEAR blockchain, taken in wrap.near token. Paid for a token recipient. */
+    storageDepositFee: bigint;
+  };
+  [RouteEnum.OmniBridge]: {
+    /** Fee for nep141 storage deposit in NEAR blockchain, taken in wrap.near token. Paid for omni bridge contract. */
+    storageDepositFee: bigint;
+    /** Relayer fee for transferring tokens via Omni Bridge to other supported blockchains, taken in wrap.near token. */
+    relayerFee: bigint;
+    /** Fee taken when making a withdrawal via UTXO connector (e.g., btc-connector.bridge.near), taken in transferred token. */
+    utxoProtocolFee?: bigint;
+    /** Maximum amount of tokens that can be spent on gas when making a withdrawal via UTXO connector (e.g., btc-connector.bridge.near), taken in transferred token. */
+    utxoMaxGasFee?: bigint;
+  };
+  [RouteEnum.VirtualChain]: {
+    /** Fee for nep141 storage deposit in NEAR blockchain, taken in wrap.near token. Paid for virtual chain contract */
+    storageDepositFee: bigint;
+  };
+  /** Internal transfers have no fees */
+  [RouteEnum.InternalTransfer]: null;
+}
+/**
+ * Represents the different categories of fees that may apply across various withdrawal operations.
+ * Each route type has an optional fee structure. Uses a mapped type to ensure all RouteEnum values are covered.
+ */
+type UnderlyingFees = { [K in RouteEnumValues]?: RouteFeeStructures[K] };
+interface FeeEstimation {
+  amount: bigint;
+  /**
+   * @internal Implementation detail - do not use directly.
+   * This field may change or be removed without notice.
+   */
+  quote: null | solverRelay.Quote;
+  /**
+   * @internal Implementation detail - do not use directly.
+   * This field may change or be removed without notice.
+   */
+  underlyingFees: UnderlyingFees;
+}
+interface Bridge {
+  readonly route: RouteEnumValues;
+  supports(params: Pick<WithdrawalParams, "assetId" | "routeConfig">): Promise<boolean>;
+  parseAssetId(assetId: string): ParsedAssetInfo | null;
+  /**
+   * Validates withdrawal constraints for the bridge.
+   * Each bridge implementation may have different withdrawal requirements.
+   * Some bridges (like Aurora Engine, Intents) have no restrictions and will always pass.
+   * Others (like POA) check minimum amounts, and HOT Bridge checks trustlines for Stellar.
+   * @throws {MinWithdrawalAmountError} If the amount is below the minimum required
+   * @throws {TrustlineNotFoundError} If destination address lacks required trustline
+   */
+  validateWithdrawal(args: {
+    assetId: string;
+    amount: bigint;
+    destinationAddress: string;
+    feeEstimation: FeeEstimation;
+    routeConfig?: RouteConfig;
+    logger?: ILogger;
+  }): Promise<void>;
+  estimateWithdrawalFee<T extends Pick<WithdrawalParams, "assetId" | "destinationAddress" | "routeConfig" | "amount">>(args: {
+    withdrawalParams: T;
+    quoteOptions?: QuoteOptions;
+    logger?: ILogger;
+  }): Promise<FeeEstimation>;
+  createWithdrawalIntents(args: {
+    withdrawalParams: WithdrawalParams;
+    feeEstimation: FeeEstimation;
+    referral?: string;
+  }): Promise<IntentPrimitive[]>;
+  /**
+   * Creates a complete withdrawal identifier with all required info.
+   * Derives landingChain from withdrawalParams.routeConfig.chain if available, otherwise from assetId.
+   */
+  createWithdrawalIdentifier(args: {
+    withdrawalParams: WithdrawalParams;
+    index: number;
+    tx: NearTxInfo;
+  }): WithdrawalIdentifier;
+  /**
+   * One-shot status check for a withdrawal.
+   * Returns the current status without polling.
+   */
+  describeWithdrawal(args: WithdrawalIdentifier & {
+    logger?: ILogger;
+  }): Promise<WithdrawalStatus>;
+}
+interface WithdrawalIdentifier {
+  /** Actual chain where funds arrive; Near for virtual/internal routes */
+  landingChain: Chain;
+  /** Per-bridge withdrawal sequence number */
+  index: number;
+  withdrawalParams: WithdrawalParams;
+  tx: NearTxInfo;
+}
+/**
+ * Represents the current state of a withdrawal as returned by bridge adapters.
+ *
+ * Error handling follows AWS SDK "describe" API patterns:
+ * - **Thrown errors**: Infrastructure failures (network, auth, service unavailable).
+ *   Meaning: "I couldn't check the status."
+ * - **`failed` status**: Job-level failure reported by the bridge.
+ *   Meaning: "I checked, and the withdrawal failed."
+ *
+ * @see https://docs.aws.amazon.com/AmazonS3/latest/userguide/batch-ops-job-status.html
+ */
+type WithdrawalStatus = {
+  status: "pending";
+} | {
+  status: "completed";
+  txHash: string | null;
+} | {
+  status: "failed";
+  reason: string;
+};
+type ParsedAssetInfo = ({
+  blockchain: Chain;
+  bridgeName: BridgeNameEnumValues;
+  standard: "nep141";
+  contractId: string;
+} | {
+  blockchain: Chain;
+  bridgeName: BridgeNameEnumValues;
+  standard: "nep245";
+  contractId: string;
+  tokenId: string;
+}) & ({
+  native: true;
+} | {
+  address: string;
+});
+type RPCEndpointMap = Record<typeof Chains.Near | HotBridgeEVMChain, string[]> & { [K in typeof Chains.Stellar]: {
+  soroban: string[];
+  horizon: string[];
+} };
+type DeepPartial<T> = T extends object ? T extends Array<infer U> ? Array<DeepPartial<U>> : T extends Function ? T : { [P in keyof T]?: DeepPartial<T[P]> } : T;
+type PartialRPCEndpointMap = DeepPartial<RPCEndpointMap>;
+//#endregion
+export { BatchWithdrawalResult, Bridge, CreateWithdrawalCompletionPromisesParams, FeeEstimation, HotBridgeRouteConfig, IIntentsSDK, IntentPublishResult, IntentSettlementStatus, InternalTransferRouteConfig, NearTxInfo, NearWithdrawalRouteConfig, OmniBridgeRouteConfig, ParsedAssetInfo, PartialRPCEndpointMap, PoaBridgeRouteConfig, ProcessWithdrawalArgs, QuoteOptions, RouteConfig, SignAndSendArgs, SignAndSendWithdrawalArgs, SignedIntentsComposition, TxInfo, TxNoInfo, VirtualChainRouteConfig, WithdrawalIdentifier, WithdrawalParams, WithdrawalResult };

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "lampamazaza-new-intents-sdk",
+  "version": "0.47.1",
+  "private": false,
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/defuse-protocol/sdk-monorepo.git",
+    "directory": "packages/intents-sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/defuse-protocol/sdk-monorepo/issues"
+  },
+  "homepage": "https://github.com/defuse-protocol/sdk-monorepo/tree/main/packages/intents-sdk#readme",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@hot-labs/omni-sdk": "2.24.7",
+    "@isaacs/ttlcache": "^1.0.0",
+    "@lifeomic/attempt": "^3.0.0",
+    "@omni-bridge/core": "0.2.3",
+    "@omni-bridge/near": "0.2.3",
+    "@noble/hashes": "^1.7.1",
+    "@scure/base": "^1.0.0",
+    "@solana/web3.js": "^1.0.0",
+    "borsher": "^4.0.0",
+    "lru-cache": "^11",
+    "near-api-js": "^4.0.0 || ^5.0.0",
+    "ripple-address-codec": "^5.0.0",
+    "valibot": "^1.0.0",
+    "viem": "^2.0.0",
+    "lampamazaza-new-contract-types": "0.6.0",
+    "lampamazaza-new-internal-utils": "0.24.3"
+  },
+  "devDependencies": {
+    "tsdown": "0.19.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "typecheck": "npx tsc --noEmit"
+  }
+}