@defuse-protocol/nearintents-mpp-sdk 0.0.0 → 0.1.0

package/src/Types.ts

@@ -0,0 +1,256 @@
+import { Receipt, z } from 'mppx'
+
+/** Payment method name for `nearintents` challenges. */
+export const paymentMethod = 'nearintents' as const
+
+/** Payment intent name for one-time cross-chain charges. */
+export const chargeIntent = 'charge' as const
+
+/** `methodDetails.settlementBackend` disclosure value for this method. */
+export const settlementBackend = 'near-intents' as const
+
+/** Credential types supported by this method (spec: the only valid value is "hash"). */
+export const credentialTypes = ['hash'] as const
+
+// ---------------------------------------------------------------------------
+// CAIP-2 / CAIP-19 identifiers
+//
+// The wire format uses CAIP-19 for `currency` and `methodDetails.destinationAsset`
+// and CAIP-2 for `methodDetails.originNetwork` / `methodDetails.destinationNetwork`.
+// Identifiers MUST be compared by parsed components, with the asset reference
+// compared in the chain's canonical form (EVM addresses case-insensitively).
+// ---------------------------------------------------------------------------
+
+const caip2Regex = /^([-a-z0-9]{3,8}):([-_a-zA-Z0-9]{1,32})$/
+const caip19Regex =
+  /^([-a-z0-9]{3,8}):([-_a-zA-Z0-9]{1,32})\/([-a-z0-9]{3,8}):([-.%a-zA-Z0-9]{1,128})$/
+
+/** Parsed CAIP-2 chain identifier. */
+export type Caip2 = {
+  namespace: string
+  reference: string
+}
+
+/** Parsed CAIP-19 asset identifier. */
+export type Caip19 = {
+  chain: Caip2
+  assetNamespace: string
+  assetReference: string
+}
+
+/** Parses a CAIP-2 chain identifier (e.g. `eip155:42161`). Throws on invalid input. */
+export function parseCaip2(id: string): Caip2 {
+  const match = caip2Regex.exec(id)
+  if (!match) throw new Error(`Invalid CAIP-2 chain identifier: "${id}".`)
+  return { namespace: match[1]!, reference: match[2]! }
+}
+
+/** Parses a CAIP-19 asset identifier (e.g. `eip155:42161/erc20:0xaf88…`). Throws on invalid input. */
+export function parseCaip19(id: string): Caip19 {
+  const match = caip19Regex.exec(id)
+  if (!match) throw new Error(`Invalid CAIP-19 asset identifier: "${id}".`)
+  return {
+    chain: { namespace: match[1]!, reference: match[2]! },
+    assetNamespace: match[3]!,
+    assetReference: match[4]!,
+  }
+}
+
+/** Returns the CAIP-2 chain component of a CAIP-19 asset identifier. */
+export function chainOf(assetId: string): string {
+  const { chain } = parseCaip19(assetId)
+  return `${chain.namespace}:${chain.reference}`
+}
+
+/**
+ * Non-throwing {@link chainOf} for schema refines: zod runs object-level
+ * checks even when a field-level check already failed, so a malformed
+ * CAIP-19 must yield `false` (a normal validation issue), not an exception.
+ */
+function chainOfSafe(assetId: string): string | undefined {
+  try {
+    return chainOf(assetId)
+  } catch {
+    return undefined
+  }
+}
+
+/** Compares two CAIP-2 identifiers by parsed components. */
+export function networkEqual(a: string, b: string): boolean {
+  let left: Caip2
+  let right: Caip2
+  try {
+    left = parseCaip2(a)
+    right = parseCaip2(b)
+  } catch {
+    return false
+  }
+  return left.namespace === right.namespace && left.reference === right.reference
+}
+
+/**
+ * Compares two CAIP-19 identifiers by parsed components.
+ *
+ * The asset reference is compared in the chain's canonical form: for `eip155`
+ * chains (hex addresses) the comparison is case-insensitive; for all other
+ * chains it is exact (e.g. base58 references are case-sensitive).
+ */
+export function assetEqual(a: string, b: string): boolean {
+  let left: Caip19
+  let right: Caip19
+  try {
+    left = parseCaip19(a)
+    right = parseCaip19(b)
+  } catch {
+    return false
+  }
+  if (left.chain.namespace !== right.chain.namespace) return false
+  if (left.chain.reference !== right.chain.reference) return false
+  if (left.assetNamespace !== right.assetNamespace) return false
+  if (left.chain.namespace === 'eip155')
+    return left.assetReference.toLowerCase() === right.assetReference.toLowerCase()
+  return left.assetReference === right.assetReference
+}
+
+/** Formats a payer identity as a `did:pkh` source (CAIP-2 network + payer address). */
+export function toSource(parameters: { network: string; address: string }): string {
+  return `did:pkh:${parameters.network}:${parameters.address}`
+}
+
+// ---------------------------------------------------------------------------
+// Schemas
+// ---------------------------------------------------------------------------
+
+/** Base-unit integer amount (e.g. "1000000" for 1 USDC at 6 decimals). */
+export function atomicAmount() {
+  return z.string().check(z.regex(/^\d+$/, 'Invalid base-unit amount'))
+}
+
+/** CAIP-2 chain identifier string. */
+export function caip2() {
+  return z.string().check(z.regex(caip2Regex, 'Invalid CAIP-2 chain identifier'))
+}
+
+/** CAIP-19 asset identifier string. */
+export function caip19() {
+  return z.string().check(z.regex(caip19Regex, 'Invalid CAIP-19 asset identifier'))
+}
+
+/** NEAR Intents-specific `methodDetails` for the charge request (spec §Method Details). */
+export const MethodDetailsSchema = z.object({
+  /** CAIP-2 identifier of the origin chain (where `recipient` lives and the deposit tx is anchored). */
+  originNetwork: caip2(),
+  /** CAIP-2 identifier of the chain where the merchant receives the destination asset. */
+  destinationNetwork: caip2(),
+  /** Destination asset the merchant receives, as CAIP-19; chain component MUST equal `destinationNetwork`. */
+  destinationAsset: caip19(),
+  /** Merchant address on the destination chain that receives `amountOut`. */
+  destinationRecipient: z.string().check(z.minLength(1)),
+  /** Exact amount the merchant receives, in base units of `destinationAsset` (EXACT_OUTPUT). */
+  amountOut: atomicAmount(),
+  /** Minimum deposit the backend accepts, in base units of `currency` — the verification threshold. */
+  minAmountIn: atomicAmount(),
+  /** Deposit memo required by some origin chains (e.g. Stellar). Absent or null when not required. */
+  depositMemo: z.optional(z.nullable(z.string())),
+  /** Slippage tolerance in basis points (e.g. 100 = 1%). */
+  slippageTolerance: z.optional(z.number()),
+  /** Estimated swap completion time in seconds, from the 1Click quote. */
+  timeEstimate: z.optional(z.number()),
+  /** Origin-chain address refunded if the swap fails or excess exists. */
+  refundTo: z.string().check(z.minLength(1)),
+  /** Settlement backend disclosure. Always "near-intents" for this method. */
+  settlementBackend: z.optional(z.literal(settlementBackend)),
+  /** Ordered list of accepted credential types. Only "hash" is valid for this method. */
+  credentialTypes: z.optional(z.array(z.literal('hash')).check(z.minLength(1))),
+})
+export type MethodDetails = z.infer<typeof MethodDetailsSchema>
+
+/**
+ * Canonical `nearintents` charge request (the decoded challenge `request` parameter).
+ *
+ * The standard fields describe the payment the client makes on the origin
+ * chain (`recipient` is the single-use 1Click deposit address); the merchant's
+ * destination leg is carried in `methodDetails`.
+ */
+export const ChargeRequestSchema = z
+  .object({
+    /**
+     * Deposit amount the client is asked to send, in base units of `currency`:
+     * the quote's maximum input that guarantees the merchant receives
+     * `methodDetails.amountOut` (the spec calls this `maxAmountIn`; the 1Click
+     * quote response field is `amountIn`).
+     */
+    amount: atomicAmount(),
+    /** Source asset the client pays with, as CAIP-19; chain component MUST equal `methodDetails.originNetwork`. */
+    currency: caip19(),
+    /** 1Click deposit address on the origin chain — the payee of the client's on-chain transfer. */
+    recipient: z.string().check(z.minLength(1)),
+    /** Human-readable payment description. MUST NOT be relied upon for verification. */
+    description: z.optional(z.string()),
+    /** Merchant reference (order ID, invoice number, etc.). */
+    externalId: z.optional(z.string()),
+    methodDetails: MethodDetailsSchema,
+  })
+  .check(
+    z.refine((request) => {
+      const chain = chainOfSafe(request.currency)
+      return chain !== undefined && networkEqual(chain, request.methodDetails.originNetwork)
+    }, 'currency chain component must equal methodDetails.originNetwork'),
+    z.refine((request) => {
+      const chain = chainOfSafe(request.methodDetails.destinationAsset)
+      return chain !== undefined && networkEqual(chain, request.methodDetails.destinationNetwork)
+    }, 'destinationAsset chain component must equal methodDetails.destinationNetwork'),
+  )
+export type ChargeRequest = z.infer<typeof ChargeRequestSchema>
+
+/** Push-mode credential payload: the confirmed origin-chain deposit transaction hash. */
+export const HashPayloadSchema = z.object({
+  type: z.literal('hash'),
+  /** Transaction hash of the client's deposit on `methodDetails.originNetwork` (chain-native format). */
+  hash: z.string().check(z.minLength(1)),
+})
+export type HashPayload = z.infer<typeof HashPayloadSchema>
+
+// ---------------------------------------------------------------------------
+// Receipt
+// ---------------------------------------------------------------------------
+
+/**
+ * `nearintents` Payment-Receipt payload (spec §Receipt).
+ *
+ * Extends the mppx base receipt with the method's REQUIRED `challengeId` and
+ * `originTxHash` fields (and optional `destinationNetwork`). `reference` is
+ * the destination-chain transaction hash of the merchant delivery.
+ */
+export type NearIntentsReceipt = Receipt.Receipt & {
+  method: typeof paymentMethod
+  /** The `id` from the original challenge. */
+  challengeId: string
+  /** The client's origin-chain deposit transaction hash (`payload.hash`). */
+  originTxHash: string
+  /** CAIP-2 identifier of the chain where the merchant was paid. */
+  destinationNetwork?: string | undefined
+}
+
+/** Builds a spec-conformant `nearintents` receipt through `Receipt.from`. */
+export function toReceipt(parameters: {
+  challengeId: string
+  /** Destination-chain transaction hash of the merchant delivery. */
+  reference: string
+  originTxHash: string
+  destinationNetwork?: string | undefined
+  externalId?: string | undefined
+  timestamp?: string | undefined
+}): NearIntentsReceipt {
+  const { challengeId, destinationNetwork, externalId, originTxHash, reference } = parameters
+  return Receipt.from({
+    method: paymentMethod,
+    reference,
+    status: 'success',
+    timestamp: parameters.timestamp ?? new Date().toISOString(),
+    challengeId,
+    originTxHash,
+    ...(destinationNetwork !== undefined && { destinationNetwork }),
+    ...(externalId !== undefined && { externalId }),
+  }) as NearIntentsReceipt
+}

package/src/client/Charge.ts

@@ -0,0 +1,268 @@
+import { Credential, Errors, Expires, Method, z } from 'mppx'
+
+import * as Methods from '../Methods.js'
+import * as Types from '../Types.js'
+
+/**
+ * Creates a `nearintents` charge method for usage on the client.
+ *
+ * The client pays before delivery, so the spec's client-side MUSTs are
+ * enforced as assertions: the challenge request is schema-validated, `expires`
+ * is refused when passed, and the configured payment policy (allowed origin
+ * networks/assets, per-asset `maxAmountIn` caps, expected destination leg) is
+ * checked before any deposit is made.
+ *
+ * The deposit itself is provided one of three ways (first match wins):
+ * 1. `context.hash` — the deposit was already broadcast; present its tx hash.
+ * 2. `sendDeposit` — a callback that pays the origin-chain leg and resolves
+ *    with the confirmed tx hash (bring-your-own-chain).
+ * 3. `walletClient` (config or context) — built-in EVM broadcast for
+ *    `eip155:*` origins (native transfers and ERC-20 `transfer`); any viem
+ *    WalletClient extended with public actions satisfies the interface.
+ *
+ * @example
+ * ```ts
+ * import { Mppx } from 'mppx/client'
+ * import { nearintents } from '@defuse-protocol/nearintents-mpp-sdk/client'
+ *
+ * const mppx = Mppx.create({
+ *   methods: [
+ *     nearintents.charge({
+ *       walletClient,
+ *       policy: {
+ *         allowedOriginNetworks: ['eip155:42161'],
+ *         maxAmountIn: { 'eip155:42161/erc20:0xaf88…5831': '5000000' },
+ *       },
+ *     }),
+ *   ],
+ * })
+ * const response = await mppx.fetch('https://api.example.com/paid-resource')
+ * ```
+ */
+export function charge(parameters: charge.Parameters = {}) {
+  return Method.toClient(Methods.charge, {
+    context: z.object({
+      /** Tx hash of an already-broadcast deposit (push mode, bring-your-own-broadcast). */
+      hash: z.optional(z.string()),
+      /** Per-request EVM wallet client (overrides the configured one). */
+      walletClient: z.optional(z.custom<charge.EvmWalletClient>()),
+    }),
+
+    canHandleChallenge({ challenge }) {
+      if (challenge.method !== Types.paymentMethod || challenge.intent !== Types.chargeIntent)
+        return false
+      const parsed = Types.ChargeRequestSchema.safeParse(challenge.request)
+      if (!parsed.success) return false
+      try {
+        assertPolicy(parameters.policy, parsed.data)
+        return true
+      } catch {
+        return false
+      }
+    },
+
+    async createCredential({ challenge, context }) {
+      // Spec §Amount and Asset Verification: decode and verify the challenge
+      // request before paying; never rely on `description`.
+      const request = Types.ChargeRequestSchema.parse(challenge.request)
+      // Spec §Expiry: MUST NOT broadcast a deposit after `expires`.
+      Expires.assert(challenge.expires, challenge.id)
+      assertPolicy(parameters.policy, request)
+
+      const walletClient = context?.walletClient ?? parameters.walletClient
+      const hash = await (async () => {
+        if (context?.hash) return context.hash
+        if (parameters.sendDeposit) return parameters.sendDeposit({ challenge, request })
+        if (walletClient) return broadcastEvmDeposit(walletClient, request)
+        throw new Error(
+          'nearintents-mpp-sdk: no way to pay — provide context.hash, a sendDeposit callback, or a walletClient.',
+        )
+      })()
+
+      const source =
+        parameters.source ??
+        (walletClient?.account?.address
+          ? Types.toSource({
+              network: request.methodDetails.originNetwork,
+              address: walletClient.account.address,
+            })
+          : undefined)
+
+      return Credential.serialize(
+        Credential.from({
+          challenge,
+          payload: { type: 'hash', hash },
+          ...(source && { source }),
+        }),
+      )
+    },
+  })
+}
+
+export declare namespace charge {
+  /**
+   * Payment policy — the client's safety surface (it pays before delivery).
+   * Every configured list is an allowlist; `maxAmountIn` entries double as a
+   * currency allowlist when present.
+   */
+  type Policy = {
+    /** CAIP-2 origin networks the client is willing to pay on. */
+    allowedOriginNetworks?: readonly string[] | undefined
+    /** CAIP-19 source assets the client is willing to pay with. */
+    allowedCurrencies?: readonly string[] | undefined
+    /**
+     * Per-asset deposit caps in base units, keyed by CAIP-19 id. When set,
+     * a challenge whose `currency` has no entry is refused.
+     */
+    maxAmountIn?: Record<string, string> | undefined
+    /** Expected merchant destination leg; mismatches are refused. */
+    expectedDestination?:
+      | {
+          destinationAsset?: string | undefined
+          destinationRecipient?: string | undefined
+          amountOut?: string | undefined
+        }
+      | undefined
+  }
+
+  /**
+   * Minimal EVM wallet surface for the built-in `eip155:*` deposit broadcast.
+   * A viem `WalletClient` created with `account` and `chain` (so both default
+   * per call) and extended with public actions satisfies it;
+   * `waitForTransactionReceipt` is optional but strongly recommended — the
+   * spec expects a *confirmed* deposit hash.
+   */
+  type EvmWalletClient = {
+    account?: { address: string } | undefined
+    chain?: { id: number } | undefined
+    sendTransaction: (args: {
+      to: `0x${string}`
+      value?: bigint | undefined
+      data?: `0x${string}` | undefined
+    }) => Promise<string>
+    waitForTransactionReceipt?:
+      | ((args: { hash: `0x${string}` }) => Promise<{ status?: string | undefined }>)
+      | undefined
+  }
+
+  type SendDeposit = (parameters: {
+    challenge: { id: string; expires?: string | undefined }
+    request: Types.ChargeRequest
+  }) => Promise<string>
+
+  type Parameters = {
+    /** Payment policy asserted before every deposit. */
+    policy?: Policy | undefined
+    /** Pays the origin-chain leg and resolves with the confirmed tx hash. */
+    sendDeposit?: SendDeposit | undefined
+    /** EVM wallet for the built-in `eip155:*` broadcast. */
+    walletClient?: EvmWalletClient | undefined
+    /** Payer DID for the credential `source` (defaults to did:pkh from the wallet). */
+    source?: string | undefined
+  }
+}
+
+/** @internal */
+function assertPolicy(policy: charge.Policy | undefined, request: Types.ChargeRequest): void {
+  if (!policy) return
+  const { methodDetails } = request
+
+  if (
+    policy.allowedOriginNetworks &&
+    !policy.allowedOriginNetworks.some((network) =>
+      Types.networkEqual(network, methodDetails.originNetwork),
+    )
+  )
+    throw new PolicyError(`origin network ${methodDetails.originNetwork} is not allowed`)
+
+  if (
+    policy.allowedCurrencies &&
+    !policy.allowedCurrencies.some((asset) => Types.assetEqual(asset, request.currency))
+  )
+    throw new PolicyError(`currency ${request.currency} is not allowed`)
+
+  if (policy.maxAmountIn) {
+    const cap = Object.entries(policy.maxAmountIn).find(([asset]) =>
+      Types.assetEqual(asset, request.currency),
+    )?.[1]
+    if (cap === undefined)
+      throw new PolicyError(`currency ${request.currency} has no maxAmountIn entry`)
+    if (BigInt(request.amount) > BigInt(cap))
+      throw new PolicyError(`amount ${request.amount} exceeds the ${cap} cap for this asset`)
+  }
+
+  const expected = policy.expectedDestination
+  if (expected) {
+    if (
+      expected.destinationAsset !== undefined &&
+      !Types.assetEqual(expected.destinationAsset, methodDetails.destinationAsset)
+    )
+      throw new PolicyError('destination asset does not match the expected destination')
+    if (
+      expected.destinationRecipient !== undefined &&
+      expected.destinationRecipient !== methodDetails.destinationRecipient
+    )
+      throw new PolicyError('destination recipient does not match the expected destination')
+    if (expected.amountOut !== undefined && expected.amountOut !== methodDetails.amountOut)
+      throw new PolicyError('amountOut does not match the expected destination')
+  }
+}
+
+/** @internal Policy violations map to invalid-payload problems client-side. */
+class PolicyError extends Errors.PaymentError {
+  override readonly name = 'PolicyError'
+  readonly title = 'Payment Policy Violation'
+  readonly type = 'https://paymentauth.org/problems/invalid-payload'
+
+  constructor(reason: string) {
+    super(`Payment policy violation: ${reason}.`)
+  }
+}
+
+/** @internal Broadcasts the deposit for `eip155:*` origins and returns the confirmed hash. */
+async function broadcastEvmDeposit(
+  walletClient: charge.EvmWalletClient,
+  request: Types.ChargeRequest,
+): Promise<string> {
+  const currency = Types.parseCaip19(request.currency)
+  if (currency.chain.namespace !== 'eip155')
+    throw new Error(
+      `nearintents-mpp-sdk: the built-in wallet broadcast only supports eip155 origins (got ${request.methodDetails.originNetwork}); use sendDeposit or context.hash.`,
+    )
+  if (request.methodDetails.depositMemo != null)
+    throw new Error('nearintents-mpp-sdk: EVM deposits cannot carry a deposit memo.')
+
+  const expectedChainId = Number(currency.chain.reference)
+  if (walletClient.chain?.id !== expectedChainId)
+    throw new Error(
+      `nearintents-mpp-sdk: wallet is on chain ${walletClient.chain?.id ?? 'unknown'} but the challenge origin is eip155:${expectedChainId}.`,
+    )
+
+  const amount = BigInt(request.amount)
+  const recipient = request.recipient as `0x${string}`
+
+  // account/chain are intentionally omitted — the wallet's own defaults apply
+  // (and the chain-id assertion above already pinned the network).
+  const hash = await (async () => {
+    if (currency.assetNamespace === 'slip44')
+      return walletClient.sendTransaction({ to: recipient, value: amount })
+    // ERC-20 transfer(address,uint256) calldata — 0xa9059cbb + padded args.
+    const data =
+      `0xa9059cbb${recipient.slice(2).toLowerCase().padStart(64, '0')}${amount.toString(16).padStart(64, '0')}` as `0x${string}`
+    return walletClient.sendTransaction({
+      to: currency.assetReference as `0x${string}`,
+      data,
+    })
+  })()
+
+  // Present a *confirmed* hash when the client can wait for inclusion.
+  if (walletClient.waitForTransactionReceipt) {
+    const receipt = await walletClient.waitForTransactionReceipt({
+      hash: hash as `0x${string}`,
+    })
+    if (receipt.status && receipt.status !== 'success')
+      throw new Error(`nearintents-mpp-sdk: deposit transaction ${hash} reverted.`)
+  }
+
+  return hash
+}

package/src/client/index.ts

@@ -0,0 +1,4 @@
+export * as Errors from '../Errors.js'
+export * as Methods from '../Methods.js'
+export * as Types from '../Types.js'
+export * as nearintents from './Charge.js'

package/src/index.ts

@@ -0,0 +1,4 @@
+export * as Errors from './Errors.js'
+export * as OneClick from './internal/OneClick.js'
+export * as Methods from './Methods.js'
+export * as Types from './Types.js'