@joeywallet/gemwallet-compat 0.2.0

package/src/convert.ts

@@ -0,0 +1,183 @@
+/**
+ * GemWallet request shapes to XRPL transaction JSON.
+ *
+ * GemWallet's payloads are camelCase and its memo/signer wrappers are lowercase
+ * (`{ memo: { memoData } }`), while the ledger — and therefore everything Joey
+ * signs — uses XRPL's PascalCase field names. Every mapping here is mechanical;
+ * it is separated out because a mistake in it would show up as a transaction
+ * that silently loses a destination tag or a memo.
+ */
+import type {
+  AnyTransaction,
+  JoeyChain,
+  JoeyNetwork,
+  Memo as XrplMemo,
+  Signer as XrplSigner,
+} from '@joeywallet/wallet-sdk'
+
+import type {
+  BaseTransactionRequest,
+  Memo as GemMemo,
+  Network,
+  SendPaymentRequest,
+  SetTrustlineRequest,
+  Signer as GemSigner,
+} from './types.js'
+
+/** Drops keys whose value is `undefined` so the wire message stays minimal. */
+function defined<T extends Record<string, unknown>>(source: T): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(source)) {
+    if (value !== undefined) out[key] = value
+  }
+  return out
+}
+
+export function toXrplMemos(memos: GemMemo[] | undefined): XrplMemo[] | undefined {
+  if (memos === undefined) return undefined
+  return memos.map((entry) => ({
+    Memo: defined({
+      MemoData: entry.memo.memoData,
+      MemoType: entry.memo.memoType,
+      MemoFormat: entry.memo.memoFormat,
+    }) as XrplMemo['Memo'],
+  }))
+}
+
+export function toXrplSigners(signers: GemSigner[] | undefined): XrplSigner[] | undefined {
+  if (signers === undefined) return undefined
+  return signers.map((entry) => ({
+    Signer: {
+      Account: entry.signer.account,
+      TxnSignature: entry.signer.txnSignature,
+      SigningPubKey: entry.signer.signingPubKey,
+    },
+  }))
+}
+
+/** The fields every GemWallet transaction request shares. */
+export function toXrplCommonFields(request: BaseTransactionRequest): Record<string, unknown> {
+  return defined({
+    Fee: request.fee,
+    Sequence: request.sequence,
+    AccountTxnID: request.accountTxnID,
+    LastLedgerSequence: request.lastLedgerSequence,
+    Memos: toXrplMemos(request.memos),
+    NetworkID: request.networkID,
+    Signers: toXrplSigners(request.signers),
+    SourceTag: request.sourceTag,
+    SigningPubKey: request.signingPubKey,
+    TicketSequence: request.ticketSequence,
+    TxnSignature: request.txnSignature,
+  })
+}
+
+/**
+ * GemWallet's `sendPayment` payload as an XRPL `Payment`.
+ *
+ * **`amount` crosses untouched, and that is correct — checked, not assumed.**
+ * It is the one line in this package where being wrong costs a factor of a
+ * million, so the source is named rather than trusted to memory:
+ * `@gemwallet/api@3.8.0` types `SendPaymentRequest.amount` as xrpl.js's
+ * `Amount`, and `packages/constants/src/payload/payload.types.ts` documents it
+ * verbatim as *"A string representing the number of XRP to deliver, in drops."*
+ * Joey's `Payment.Amount` is drops. Same unit, no conversion, and a converting
+ * shim here would be the bug rather than the fix.
+ *
+ * The one place GemWallet does convert is its extension's `parseAmount`, and
+ * only for its deprecated v1 URL-parameter path, where `amount` arrives as a
+ * *number* of XRP. That path is not this API and never reaches this function:
+ * `amount` here is a `string` or an issued-currency object, both of which
+ * GemWallet forwards to the ledger exactly as this does.
+ *
+ * `convert.test.ts` pins both halves — drops for XRP, `value` untouched for an
+ * issued currency — so a future "helpful" `xrpToDrops` fails a test instead of
+ * a user's payment.
+ */
+export function toPaymentTransaction(
+  request: SendPaymentRequest,
+  account?: string,
+): AnyTransaction {
+  return {
+    TransactionType: 'Payment',
+    ...(account === undefined ? {} : { Account: account }),
+    ...toXrplCommonFields(request),
+    ...defined({
+      // Drops. See the note above before changing this.
+      Amount: request.amount,
+      Destination: request.destination,
+      DestinationTag: request.destinationTag,
+      InvoiceID: request.invoiceID,
+      Paths: request.paths,
+      SendMax: request.sendMax,
+      DeliverMin: request.deliverMin,
+      Flags: request.flags,
+    }),
+  } as AnyTransaction
+}
+
+export function toTrustSetTransaction(
+  request: SetTrustlineRequest,
+  account?: string,
+): AnyTransaction {
+  return {
+    TransactionType: 'TrustSet',
+    ...(account === undefined ? {} : { Account: account }),
+    ...toXrplCommonFields(request),
+    ...defined({
+      LimitAmount: request.limitAmount,
+      QualityIn: request.qualityIn,
+      QualityOut: request.qualityOut,
+      Flags: request.flags,
+    }),
+  } as AnyTransaction
+}
+
+/* ------------------------------------------------------------------ networks */
+
+/**
+ * The public endpoints for each chain.
+ *
+ * Duplicated from the extension's `shared/types.ts` `NETWORKS` rather than
+ * imported: this package is published to npm and cannot depend on the
+ * extension's source. GemWallet's `getNetwork()` contract promises a
+ * `websocket`, and dapps feed it straight into an xrpl.js `Client`, so
+ * answering with an empty string would break every migrating caller. They must
+ * be kept in step with the extension if an endpoint ever moves.
+ */
+const WEBSOCKET_BY_CHAIN: Record<JoeyChain, string> = {
+  'xrpl:0': 'wss://s1.ripple.com/',
+  'xrpl:1': 'wss://testnet.xrpl-labs.com/',
+  'xrpl:2': 'wss://s.devnet.rippletest.net:51233/',
+}
+
+const GEM_NAME_BY_CHAIN: Record<JoeyChain, Network> = {
+  'xrpl:0': 'Mainnet',
+  'xrpl:1': 'Testnet',
+  'xrpl:2': 'Devnet',
+}
+
+const DESCRIPTION_BY_CHAIN: Record<JoeyChain, string> = {
+  'xrpl:0': 'Main XRPL network',
+  'xrpl:1': 'XRPL Testnet',
+  'xrpl:2': 'XRPL Devnet',
+}
+
+/**
+ * Joey's network to GemWallet's `Network` string.
+ *
+ * GemWallet also has `Custom`, which Joey never returns: the extension ships a
+ * fixed set of three endpoints.
+ */
+export function toGemNetwork(network: JoeyNetwork): Network {
+  return GEM_NAME_BY_CHAIN[network.chain]
+}
+
+export function toGemWebsocket(network: JoeyNetwork): string {
+  return WEBSOCKET_BY_CHAIN[network.chain]
+}
+
+/** GemWallet's human-readable network description, for the event payload. */
+export function toGemNetworkDescription(network: JoeyNetwork): string {
+  return DESCRIPTION_BY_CHAIN[network.chain]
+}

package/src/envelope.ts

@@ -0,0 +1,31 @@
+/**
+ * GemWallet's `{ type, result }` envelope, reconstructed on top of Joey's
+ * promise-rejection API.
+ *
+ * The two models disagree about exactly one thing, and this file is where that
+ * disagreement is resolved: GemWallet reports a user declining as a *resolved*
+ * `{ type: 'reject' }`, and reports everything else by throwing. Joey rejects
+ * with a `JoeyRpcError` in both cases. So a 4001 becomes `{ type: 'reject' }`
+ * and every other code is rethrown, which is what a GemWallet dapp's existing
+ * `if (result.type === 'reject')` branch and its `try`/`catch` already expect.
+ */
+import { JoeyRpcError, isUserRejection } from '@joeywallet/wallet-sdk'
+
+import type { BaseResponse } from './types.js'
+
+export function response<T>(result: T): BaseResponse<T> & { type: 'response'; result: T } {
+  return { type: 'response', result }
+}
+
+export function rejected<T>(): BaseResponse<T> & { type: 'reject' } {
+  return { type: 'reject', result: undefined }
+}
+
+export async function envelope<T>(run: () => Promise<T>): Promise<BaseResponse<T>> {
+  try {
+    return response(await run())
+  } catch (cause) {
+    if (isUserRejection(cause)) return rejected<T>()
+    throw JoeyRpcError.from(cause)
+  }
+}

package/src/index.ts

@@ -0,0 +1,394 @@
+/**
+ * `@joeywallet/gemwallet-compat` — GemWallet's `@gemwallet/api` surface over Joey.
+ *
+ *   - import { isInstalled, getAddress, sendPayment } from '@gemwallet/api'
+ *   + import { isInstalled, getAddress, sendPayment } from '@joeywallet/gemwallet-compat'
+ *
+ * Function names, argument shapes and the `{ type, result }` envelope match
+ * `@gemwallet/api@3.8.0`. Four functions deliberately do not exist as working
+ * calls — see `./unsupported.ts`.
+ */
+import {
+  JOEY_ERROR_CODES,
+  JoeyRpcError,
+  getJoey,
+  waitForJoey,
+  type Joey,
+  type JoeyAccount,
+  type JoeyNetwork,
+} from '@joeywallet/wallet-sdk'
+
+import {
+  toGemNetwork,
+  toGemNetworkDescription,
+  toGemWebsocket,
+  toPaymentTransaction,
+  toTrustSetTransaction,
+} from './convert.js'
+import { envelope } from './envelope.js'
+import { refuse } from './unsupported.js'
+import type {
+  EventLoginResponse,
+  EventLogoutResponse,
+  EventNetworkChangedResponse,
+  EventWalletChangedResponse,
+  GemEventPayloadMap,
+  GemEventType,
+  GetAddressResponse,
+  GetNetworkResponse,
+  GetPublicKeyResponse,
+  IsInstalledResponse,
+  SendPaymentRequest,
+  SendPaymentResponse,
+  SetTrustlineRequest,
+  SetTrustlineResponse,
+  SignMessageResponse,
+  SignTransactionRequest,
+  SignTransactionResponse,
+  SubmitBulkTransactionsRequest,
+  SubmitBulkTransactionsResponse,
+  SubmitTransactionRequest,
+  SubmitTransactionResponse,
+  TransactionBulkResponse,
+} from './types.js'
+
+/**
+ * How long to wait for a provider that has not been injected yet.
+ *
+ * 1000ms is GemWallet's own number, and dapps written against it already treat
+ * a slower answer as "not installed".
+ */
+const DETECT_TIMEOUT_MS = 1000
+
+async function requireProvider(): Promise<Joey> {
+  const immediate = getJoey()
+  if (immediate !== null) return immediate
+  return await waitForJoey({ timeoutMs: DETECT_TIMEOUT_MS })
+}
+
+/**
+ * The account this origin may use, connecting first if it has to.
+ *
+ * `connect({ silent: true })` rather than `getAccounts()` because GemWallet's
+ * `getPublicKey()` needs the public key, and only the connect result carries
+ * it — `getAccounts()` answers with bare addresses. A silent connect resolves
+ * with an empty list rather than throwing when the origin has no grant, so the
+ * non-silent call below is what actually opens the approval window, matching
+ * GemWallet's behaviour of prompting from `getAddress()`.
+ */
+async function requireAccount(): Promise<{ joey: Joey; account: JoeyAccount }> {
+  const joey = await requireProvider()
+
+  let result = await joey.connect({ silent: true })
+  if (result.accounts.length === 0) result = await joey.connect()
+
+  const account = result.accounts[0]
+  if (account === undefined) {
+    throw new JoeyRpcError(
+      JOEY_ERROR_CODES.UNAUTHORIZED,
+      'Joey Wallet connected without sharing an account.',
+    )
+  }
+  return { joey, account }
+}
+
+/* ------------------------------------------------------------------ detection */
+
+/**
+ * Never rejects, and answers immediately when the provider is already present.
+ *
+ * Matches GemWallet's contract, including its 1-second budget for a provider
+ * that has not been injected yet.
+ */
+export async function isInstalled(): Promise<IsInstalledResponse> {
+  if (getJoey() !== null) return { result: { isInstalled: true } }
+  try {
+    await waitForJoey({ timeoutMs: DETECT_TIMEOUT_MS })
+    return { result: { isInstalled: true } }
+  } catch {
+    return { result: { isInstalled: false } }
+  }
+}
+
+/* -------------------------------------------------------------------- account */
+
+export async function getAddress(): Promise<GetAddressResponse> {
+  return await envelope(async () => {
+    const { account } = await requireAccount()
+    return { address: account.address }
+  })
+}
+
+export async function getPublicKey(): Promise<GetPublicKeyResponse> {
+  return await envelope(async () => {
+    const { account } = await requireAccount()
+    if (account.publicKey === undefined) {
+      throw new JoeyRpcError(
+        JOEY_ERROR_CODES.UNAUTHORIZED,
+        'The selected Joey account is watch-only and has no public key.',
+      )
+    }
+    return { address: account.address, publicKey: account.publicKey }
+  })
+}
+
+export async function getNetwork(): Promise<GetNetworkResponse> {
+  return await envelope(async () => {
+    const joey = await requireProvider()
+    const network = await joey.getNetwork()
+    return {
+      // Joey is XRPL-only. GemWallet's other value, XAHAU, is never returned.
+      chain: 'XRPL',
+      network: toGemNetwork(network),
+      websocket: toGemWebsocket(network),
+    }
+  })
+}
+
+/* -------------------------------------------------------------------- signing */
+
+/**
+ * Not implemented. Throws {@link GemWalletUnsupportedError} synchronously.
+ *
+ * Joey has no raw message-signing method: a bare signature over a string
+ * carries no domain, nonce or timestamp and is replayable against another site.
+ * Use `signIn()` from `@joeywallet/wallet-sdk`, which signs a CAIP-122 message bound
+ * to this origin.
+ */
+export function signMessage(_message: string, _isHex?: boolean): Promise<SignMessageResponse> {
+  return refuse('signMessage')
+}
+
+export async function sendPayment(
+  paymentPayload: SendPaymentRequest,
+): Promise<SendPaymentResponse> {
+  return await envelope(async () => {
+    const { joey, account } = await requireAccount()
+    const result = await joey.signAndSubmitTransaction({
+      tx_json: toPaymentTransaction(paymentPayload, account.address),
+    })
+    return { hash: result.hash }
+  })
+}
+
+export async function setTrustline(
+  payload: SetTrustlineRequest,
+): Promise<SetTrustlineResponse> {
+  return await envelope(async () => {
+    const { joey, account } = await requireAccount()
+    const result = await joey.signAndSubmitTransaction({
+      tx_json: toTrustSetTransaction(payload, account.address),
+    })
+    return { hash: result.hash }
+  })
+}
+
+export async function signTransaction(
+  payload: SignTransactionRequest,
+): Promise<SignTransactionResponse> {
+  return await envelope(async () => {
+    const { joey } = await requireAccount()
+    const result = await joey.signTransaction({ tx_json: payload.transaction })
+    // GemWallet calls the signed blob `signature`. It is the full signed
+    // transaction, not the `TxnSignature` field.
+    return { signature: result.tx_blob }
+  })
+}
+
+export async function submitTransaction(
+  payload: SubmitTransactionRequest,
+): Promise<SubmitTransactionResponse> {
+  return await envelope(async () => {
+    const { joey } = await requireAccount()
+    const result = await joey.signAndSubmitTransaction({ tx_json: payload.transaction })
+    return { hash: result.hash }
+  })
+}
+
+export async function submitBulkTransactions(
+  payload: SubmitBulkTransactionsRequest,
+): Promise<SubmitBulkTransactionsResponse> {
+  return await envelope(async () => {
+    const { joey } = await requireAccount()
+
+    // GemWallet correlates results by an `ID` field carried inside each
+    // transaction. `ID` is not an XRPL field and would break serialisation, so
+    // it is stripped here and re-attached by position — Joey signs the batch in
+    // the order it was given.
+    const ids: Array<string | undefined> = []
+    const tx_list = payload.transactions.map((entry) => {
+      const { ID, ...tx_json } = entry
+      ids.push(ID)
+      return { tx_json }
+    })
+
+    const results = await joey.signTransactionBulk({ tx_list, submit: true })
+
+    const transactions: TransactionBulkResponse[] = ids.map((id, index) => {
+      const result = results[index]
+      return {
+        ...(id === undefined ? {} : { id }),
+        // A resolved bulk request carries one entry per transaction, so every
+        // one of these is `true`. The guard stays because the alternative
+        // reading — an index with no entry silently becoming `accepted: true`
+        // with no hash — is the failure this shape exists to prevent.
+        //
+        // A batch that fails part way *rejects*, and `envelope` turns that into
+        // GemWallet's error response. The signed blobs and the failing index
+        // are on the error's `data` (`SignTransactionBulkFailure`); mapping
+        // them onto per-transaction `accepted` flags would be a better answer
+        // for a GemWallet dapp than an error, and is deliberately left as a
+        // change to this package's own contract rather than smuggled in with
+        // the wallet's.
+        accepted: result !== undefined,
+        ...(result === undefined ? {} : { hash: result.hash }),
+      }
+    })
+
+    return { transactions }
+  })
+}
+
+/* --------------------------------------------------------------- unsupported */
+
+/**
+ * Not implemented. Throws {@link GemWalletUnsupportedError} synchronously.
+ *
+ * @see ./unsupported.ts for why.
+ */
+export function setRegularKey(_payload?: unknown): Promise<never> {
+  return refuse('setRegularKey')
+}
+
+/** Not implemented. Throws {@link GemWalletUnsupportedError} synchronously. */
+export function setHook(_payload?: unknown): Promise<never> {
+  return refuse('setHook')
+}
+
+/** Not implemented. Throws {@link GemWalletUnsupportedError} synchronously. */
+export function setAccount(_payload?: unknown): Promise<never> {
+  return refuse('setAccount')
+}
+
+/* -------------------------------------------------------------------- events */
+
+type NormalisedEvent<E extends GemEventType> = E extends 'login' | 'EVENT_LOGIN'
+  ? 'login'
+  : E extends 'logout' | 'EVENT_LOGOUT'
+    ? 'logout'
+    : E extends 'networkChanged' | 'EVENT_NETWORK_CHANGED'
+      ? 'networkChanged'
+      : E extends 'walletChanged' | 'EVENT_WALLET_CHANGED'
+        ? 'walletChanged'
+        : never
+
+function normaliseEvent(eventType: GemEventType): keyof GemEventPayloadMap {
+  switch (eventType) {
+    case 'login':
+    case 'EVENT_LOGIN':
+      return 'login'
+    case 'logout':
+    case 'EVENT_LOGOUT':
+      return 'logout'
+    case 'networkChanged':
+    case 'EVENT_NETWORK_CHANGED':
+      return 'networkChanged'
+    case 'walletChanged':
+    case 'EVENT_WALLET_CHANGED':
+      return 'walletChanged'
+  }
+}
+
+function toGemNetworkEvent(network: JoeyNetwork): EventNetworkChangedResponse {
+  return {
+    network: {
+      name: toGemNetwork(network),
+      server: toGemWebsocket(network),
+      description: toGemNetworkDescription(network),
+    },
+  }
+}
+
+function attach(
+  joey: Joey,
+  event: keyof GemEventPayloadMap,
+  callback: (payload: never) => void,
+): () => void {
+  const emit = (payload: unknown): void => {
+    ;(callback as (value: unknown) => void)(payload)
+  }
+
+  switch (event) {
+    case 'login':
+      return joey.on('connect', () => emit({ loggedIn: true } satisfies EventLoginResponse))
+    case 'logout':
+      return joey.on('disconnect', () => emit({ loggedIn: false } satisfies EventLogoutResponse))
+    case 'networkChanged':
+      return joey.on('networkChanged', (network) => {
+        if (network !== null) emit(toGemNetworkEvent(network))
+      })
+    case 'walletChanged':
+      return joey.on('accountsChanged', (accounts) =>
+        emit({
+          wallet: { publicAddress: accounts[0]?.address ?? '' },
+        } satisfies EventWalletChangedResponse),
+      )
+  }
+}
+
+/**
+ * Subscribe to a wallet event.
+ *
+ * `@gemwallet/api`'s `on()` returns `void`; this returns an unsubscribe
+ * function. That is a superset — existing call sites that ignore the return
+ * value are unaffected — and it is what a single-page app needs to avoid
+ * leaking a listener on every route change.
+ */
+export function on<E extends GemEventType>(
+  eventType: E,
+  callback: (payload: GemEventPayloadMap[NormalisedEvent<E>]) => void,
+): () => void {
+  const event = normaliseEvent(eventType)
+  let detach: (() => void) | null = null
+  let cancelled = false
+
+  const bind = (joey: Joey): void => {
+    if (cancelled) return
+    detach = attach(joey, event, callback as (payload: never) => void)
+  }
+
+  const immediate = getJoey()
+  if (immediate !== null) bind(immediate)
+  else {
+    void waitForJoey({ timeoutMs: DETECT_TIMEOUT_MS })
+      .then(bind)
+      .catch(() => {
+        /* no wallet, nothing to listen to */
+      })
+  }
+
+  return () => {
+    cancelled = true
+    detach?.()
+    detach = null
+  }
+}
+
+/* -------------------------------------------------------------------- exports */
+
+export {
+  GemWalletUnsupportedError,
+  UNSUPPORTED_METHODS,
+  type UnsupportedMethod,
+} from './unsupported.js'
+export { envelope, rejected, response } from './envelope.js'
+export {
+  toGemNetwork,
+  toGemWebsocket,
+  toPaymentTransaction,
+  toTrustSetTransaction,
+  toXrplMemos,
+  toXrplSigners,
+} from './convert.js'
+export { DEFAULT_SUBMIT_TX_BULK_ON_ERROR } from './types.js'
+export type * from './types.js'