@joeywallet/gemwallet-compat 0.2.0

package/src/types.ts

@@ -0,0 +1,190 @@
+/**
+ * GemWallet's public types, restated.
+ *
+ * Copied by shape from `@gemwallet/api@3.8.0` rather than imported, so a
+ * migrating dapp can delete the `@gemwallet/api` dependency entirely — which is
+ * the whole point of this package. Field names, casing and optionality are
+ * deliberately identical to GemWallet's, including the parts that differ from
+ * XRPL's own JSON (lowercase `memos`, `{ memo: { memoData } }` instead of
+ * `{ Memo: { MemoData } }`); `../src/convert.ts` does the translation.
+ */
+import type { Amount, IssuedCurrencyAmount, Path, TransactionLike } from '@joeywallet/wallet-sdk'
+
+export type { Amount, IssuedCurrencyAmount, Path }
+
+/** GemWallet's envelope discriminant. `reject` means the user declined. */
+export type ResponseType = 'response' | 'reject'
+
+export interface BaseResponse<T> {
+  type: ResponseType
+  result?: T
+}
+
+/** GemWallet's own `Network` enum values, as string literals. */
+export type Network = 'Mainnet' | 'Testnet' | 'Devnet' | 'Custom'
+
+export type Chain = 'XRPL' | 'XAHAU'
+
+/** GemWallet spells memos lowercase and singular-nested. */
+export interface Memo {
+  memo: {
+    memoType?: string
+    memoData?: string
+    memoFormat?: string
+  }
+}
+
+export interface Signer {
+  signer: {
+    account: string
+    txnSignature: string
+    signingPubKey: string
+  }
+}
+
+export type PaymentFlags = number | object
+export type TrustSetFlags = number | object
+
+export interface BaseTransactionRequest {
+  fee?: string
+  sequence?: number
+  accountTxnID?: string
+  lastLedgerSequence?: number
+  memos?: Memo[]
+  networkID?: number
+  signers?: Signer[]
+  sourceTag?: number
+  signingPubKey?: string
+  ticketSequence?: number
+  txnSignature?: string
+}
+
+export interface SendPaymentRequest extends BaseTransactionRequest {
+  amount: Amount
+  destination: string
+  destinationTag?: number
+  invoiceID?: string
+  paths?: Path[]
+  sendMax?: Amount
+  deliverMin?: Amount
+  flags?: PaymentFlags
+}
+
+export interface SetTrustlineRequest extends BaseTransactionRequest {
+  limitAmount: IssuedCurrencyAmount
+  qualityIn?: number
+  qualityOut?: number
+  flags?: TrustSetFlags
+}
+
+/**
+ * GemWallet types this as xrpl.js's `SubmittableTransaction`. Restated as the
+ * SDK's structural constraint so this package stays free of xrpl.js, and left
+ * generic so a caller who has xrpl.js keeps full checking on their own side.
+ */
+export type Transaction = TransactionLike
+
+export type TransactionWithID = TransactionLike & { ID?: string }
+
+export interface SignTransactionRequest {
+  transaction: Transaction
+}
+
+export interface SubmitTransactionRequest {
+  transaction: Transaction
+}
+
+export type TransactionErrorHandling = 'abort' | 'continue'
+
+export const DEFAULT_SUBMIT_TX_BULK_ON_ERROR: TransactionErrorHandling = 'abort'
+
+export interface SubmitBulkTransactionsRequest {
+  transactions: TransactionWithID[]
+  /**
+   * Accepted for source compatibility. Joey always waits for the hashes it
+   * reports, so `false` does not make the call return early.
+   */
+  waitForHashes?: boolean
+  /**
+   * Accepted for source compatibility and ignored. Joey always aborts the batch
+   * at the first failure, which is GemWallet's own default and the safer of the
+   * two behaviours — `'continue'` would keep signing after a transaction the
+   * user or the ledger already refused.
+   */
+  onError?: TransactionErrorHandling
+}
+
+export interface IsInstalledResponse {
+  result: { isInstalled: boolean }
+}
+
+export interface GetAddressResponse extends BaseResponse<{ address: string }> {}
+
+export interface GetPublicKeyResponse
+  extends BaseResponse<{ address: string; publicKey: string }> {}
+
+export interface GetNetworkResponse
+  extends BaseResponse<{ chain: string; network: Network; websocket: string }> {}
+
+export interface SignMessageResponse extends BaseResponse<{ signedMessage: string }> {}
+
+export interface SendPaymentResponse extends BaseResponse<{ hash: string }> {}
+
+export interface SetTrustlineResponse extends BaseResponse<{ hash: string }> {}
+
+export interface SignTransactionResponse
+  extends BaseResponse<{ signature: string | null | undefined }> {}
+
+export interface SubmitTransactionResponse extends BaseResponse<{ hash: string }> {}
+
+export interface TransactionBulkResponse {
+  id?: string
+  accepted?: boolean
+  hash?: string
+  error?: string
+}
+
+export interface SubmitBulkTransactionsResponse
+  extends BaseResponse<{ transactions: TransactionBulkResponse[] }> {}
+
+/* -------------------------------------------------------------------- events */
+
+export interface EventLoginResponse {
+  loggedIn: boolean
+}
+
+export interface EventLogoutResponse {
+  loggedIn: boolean
+}
+
+export interface EventNetworkChangedResponse {
+  network: { name: string; server: string; description: string }
+}
+
+export interface EventWalletChangedResponse {
+  wallet: { publicAddress: string }
+}
+
+/**
+ * Event names.
+ *
+ * `@gemwallet/api`'s `on()` compares against the raw wire constants
+ * (`EVENT_LOGIN` and friends), while GemWallet's documentation and most dapp
+ * code use the short names. Both are accepted.
+ */
+export type GemEventType =
+  | 'login'
+  | 'logout'
+  | 'networkChanged'
+  | 'walletChanged'
+  | 'EVENT_LOGIN'
+  | 'EVENT_LOGOUT'
+  | 'EVENT_NETWORK_CHANGED'
+  | 'EVENT_WALLET_CHANGED'
+
+export interface GemEventPayloadMap {
+  login: EventLoginResponse
+  logout: EventLogoutResponse
+  networkChanged: EventNetworkChangedResponse
+  walletChanged: EventWalletChangedResponse
+}

package/src/unsupported.ts

@@ -0,0 +1,62 @@
+/**
+ * The GemWallet methods Joey will not implement.
+ *
+ * `setRegularKey`, `setHook` and `setAccount` are account-control transactions.
+ * `SetRegularKey` combined with `AccountSet asfDisableMaster` hands the caller
+ * permanent, unrevokable control of an XRPL account, and the balance looks
+ * untouched while it drains over later ledgers; `SetHook` installs code that
+ * runs on every future transaction. Exposing any of them to an arbitrary
+ * website is how XRPL accounts get taken over, and no approval dialog makes
+ * that safe, because the user cannot evaluate the consequence from the
+ * transaction JSON.
+ *
+ * Joey supports all three from its own UI, behind a typed confirmation and
+ * step-up authentication. It does not expose them to dapps at all — the
+ * extension hard-rejects `SetRegularKey`, `SignerListSet` and `AccountDelete`
+ * at the deserialisation layer, so even a hand-rolled `signTransaction` call
+ * carrying one of these transaction types fails.
+ *
+ * `signMessage` is here for a different reason: Joey has no raw
+ * message-signing method at all. See below.
+ *
+ * The three account-control functions throw synchronously rather than returning
+ * a rejected promise or a `{ type: 'reject' }` envelope, so a migrating dapp
+ * finds out at the first call in development instead of shipping a silently
+ * dead code path.
+ */
+export const UNSUPPORTED_METHODS = [
+  'setRegularKey',
+  'setHook',
+  'setAccount',
+  'signMessage',
+] as const
+
+export type UnsupportedMethod = (typeof UNSUPPORTED_METHODS)[number]
+
+const REASONS: Record<UnsupportedMethod, string> = {
+  setRegularKey:
+    'SetRegularKey assigns an alternate signing key to the account. Together with AccountSet asfDisableMaster it is an irreversible account takeover, so Joey never exposes it to a website. Change your account keys from the Joey Wallet UI instead.',
+  setHook:
+    'SetHook installs code that runs on every future transaction for the account. Joey never exposes it to a website. Install hooks from the Joey Wallet UI instead.',
+  setAccount:
+    'AccountSet can disable the master key, set an NFT minter, or change the transfer rate. Joey never exposes it to a website. Change account settings from the Joey Wallet UI instead.',
+  signMessage:
+    'Joey does not sign arbitrary strings for a website: a bare signature carries no domain, nonce or timestamp, so it can be replayed against another site. Use signIn() from @joeywallet/wallet-sdk instead, which signs a CAIP-122 message bound to this origin.',
+}
+
+export class GemWalletUnsupportedError extends Error {
+  /** EIP-1193 "unsupported method". */
+  readonly code = 4200
+  readonly method: UnsupportedMethod
+
+  constructor(method: UnsupportedMethod) {
+    super(`@joeywallet/gemwallet-compat does not implement ${method}(). ${REASONS[method]}`)
+    this.name = 'GemWalletUnsupportedError'
+    this.method = method
+    Object.setPrototypeOf(this, GemWalletUnsupportedError.prototype)
+  }
+}
+
+export function refuse(method: UnsupportedMethod): never {
+  throw new GemWalletUnsupportedError(method)
+}