Idempotency keys

import {
  generateIdempotencyKey,
  isIdempotencyKeyReused,
  isIdempotencyRejection,
  PortalIdempotencyError,
  PortalIdempotencyErrorId,
} from '@portal-hq/utils'

generateIdempotencyKey(): string

import { Portal, PortalRequestMethod } from '@portal-hq/core'
import { generateIdempotencyKey } from '@portal-hq/utils'

const sendWithIdempotencyKey = async (portal: Portal, toAddress: string) => {
  const chainId = 'eip155:11155111' // Ethereum Sepolia

  // Build the transaction once
  const { transaction } = await portal.api.buildTransaction(
    toAddress, // recipient address
    'NATIVE', // token
    '0.0001', // amount
    chainId,
  )

  // One key per transfer. Store it with the transaction before you send.
  const idempotencyKey = generateIdempotencyKey()

  const txHash = await portal.request(
    PortalRequestMethod.EthSendTransaction,
    [transaction],
    chainId,
    { idempotencyKey },
  )

  console.log(`✅ Transaction hash: ${txHash}`)
}

import { Portal, PortalRequestMethod } from '@portal-hq/core'
import {
  isIdempotencyRejection,
  PortalIdempotencyErrorId,
  type PortalMpcError,
} from '@portal-hq/utils'

const sendOrRetry = async (
  portal: Portal,
  chainId: string,
  transaction: unknown, // The transaction object stored with the key
  idempotencyKey: string, // The key stored with this transfer
) => {
  try {
    const txHash = await portal.request(
      PortalRequestMethod.EthSendTransaction,
      [transaction],
      chainId,
      { idempotencyKey },
    )

    // A rejected signing request resolves without a hash instead of throwing.
    if (!txHash) {
      console.log('🚫 Signing request rejected. Nothing was sent.')
      return
    }

    console.log(`✅ Transaction hash: ${txHash}`)
  } catch (error) {
    if (isIdempotencyRejection(error)) {
      const { id } = error as PortalMpcError

      switch (id) {
        case PortalIdempotencyErrorId.RequestInProgress:
          console.log('⏳ Still processing. Retry later with the same key.')
          break
        case PortalIdempotencyErrorId.RequestAlreadyCompleted:
          console.log('✅ Already broadcast. Look the transaction up instead of sending it again.')
          break
        default:
          console.log(`⚠️ Outcome unconfirmed (${id}). Check the chain before sending again with a new key.`)
      }
      return
    }

    // A PortalIdempotencyError is thrown before anything is signed or sent:
    // fix the key or the method instead of retrying. After a transient failure,
    // such as a timeout or a dropped connection, the broadcast outcome is
    // unknown: retry with the same transaction and key, not a new key.
    console.error('❌ Send failed:', error)
  }
}

import { Portal } from '@portal-hq/core'
import { generateIdempotencyKey } from '@portal-hq/utils'

const sendTokensWithIdempotencyKey = async (portal: Portal) => {
  // One key per transfer. Store it with the pending transfer.
  const idempotencyKey = generateIdempotencyKey()

  const txHash = await portal.sendAsset(
    {
      to: '0xDestinationAddress',
      amount: '0.0001',
      token: 'NATIVE',
      signatureApprovalMemo: 'Send ETH',
      idempotencyKey,
    },
    'eip155:11155111', // Ethereum Sepolia
  )

  console.log(`✅ Transaction hash: ${txHash}`)
}