@txwallet/graz-connector 0.1.0

package/index.js

@@ -0,0 +1,921 @@
+export const TX_WALLET_GRAZ_CONNECTOR_VERSION = '0.1.0';
+export const TX_WALLET_GRAZ_DEFAULT_SIGNIN_CREATE_ENDPOINT = '/api/tx-wallet/signin/requests';
+export const TX_WALLET_GRAZ_DEFAULT_TRANSACTION_CREATE_ENDPOINT = '/api/tx-wallet/requests';
+
+const TERMINAL_SIGN_STATUSES = Object.freeze(['approved', 'rejected', 'failed']);
+const AUTH_FINAL_STATUSES = Object.freeze(['approved', 'rejected', 'failed', 'expired']);
+
+const DEFAULT_WALLET_BASE_URL = 'https://txwallet.tesbert.com';
+const DEFAULT_POLL_INTERVAL_MS = 1500;
+const DEFAULT_POLL_TIMEOUT_MS = 5 * 60 * 1000;
+const DEFAULT_WINDOW_TARGET = 'txwallet-auth-approval';
+const DEFAULT_WINDOW_FEATURES = 'popup,width=430,height=760';
+const DEFAULT_TRANSACTION_CREATE_ENDPOINT = TX_WALLET_GRAZ_DEFAULT_TRANSACTION_CREATE_ENDPOINT;
+const REVIEW_ONLY_TRANSACTION_CATEGORIES = Object.freeze([]);
+const TRANSACTION_FINAL_STATUSES = Object.freeze(['broadcasted', 'confirmed', 'rejected', 'failed', 'expired', 'unsupported', 'invalid', 'error']);
+const DEFAULT_SUPPORTED_CHAINS = Object.freeze(['coreum-mainnet-1', 'coreum-testnet-1']);
+
+const toStringValue = (value) => String(value || '').trim();
+
+const normalizeSdkMetadata = (metadata, providerId) => {
+  if (!metadata || typeof metadata !== 'object') {
+    return null;
+  }
+
+  const normalized = {
+    ...metadata,
+    provider_id: toStringValue(metadata.provider_id || metadata.providerId || providerId),
+  };
+
+  return Object.values(normalized).some((value) => value !== '' && value !== undefined && value !== null)
+    ? normalized
+    : null;
+};
+
+const normalizeCode = (inputCode) => {
+  const code = toStringValue(inputCode).toUpperCase();
+  if (!code) return 'INTERNAL_ERROR';
+  return code;
+};
+
+const normalizeSupportedChains = (supportedChains) => {
+  const source = Array.isArray(supportedChains) ? supportedChains : DEFAULT_SUPPORTED_CHAINS;
+  const normalized = source
+    .map((chainId) => toStringValue(chainId))
+    .filter(Boolean);
+  return normalized.length > 0 ? normalized : [...DEFAULT_SUPPORTED_CHAINS];
+};
+
+const assertSupportedChain = (chainId, supportedChains) => {
+  if (!supportedChains.includes(chainId)) {
+    throw new TxWalletGrazConnectorError(
+      `Unsupported chain ${chainId}. Supported chains: ${supportedChains.join(', ')}`,
+      { code: 'UNSUPPORTED_CHAIN' },
+    );
+  }
+};
+
+const isAbortError = (error) => {
+  if (!error) return false;
+  if (error instanceof DOMException) {
+    return error.name === 'AbortError';
+  }
+  return toStringValue(error.name) === 'AbortError';
+};
+
+const looksLikeNetworkError = (error) => {
+  if (!error) return false;
+
+  if (error instanceof TypeError) {
+    return true;
+  }
+
+  const name = toStringValue(error.name).toLowerCase();
+  if (name === 'networkerror') {
+    return true;
+  }
+
+  const message = toStringValue(error.message).toLowerCase();
+  return message.includes('failed to fetch')
+    || message.includes('network request failed')
+    || message.includes('load failed')
+    || message.includes('network error')
+    || message.includes('ecconnrefused')
+    || message.includes('econnreset')
+    || message.includes('enotfound')
+    || message.includes('timed out');
+};
+
+const normalizeTransactionStatus = (statusPayload) => {
+  if (!isObject(statusPayload)) {
+    throw new TxWalletGrazConnectorError('Transaction status payload must be an object.', {
+      code: 'REQUEST_FAILED',
+    });
+  }
+
+  const requestId = toStringValue(statusPayload?.request_id || statusPayload?.requestId);
+  const status = toStringValue(statusPayload?.status).toLowerCase();
+  if (!requestId || !status) {
+    throw new TxWalletGrazConnectorError('Transaction status payload is missing request_id or status.', {
+      code: 'REQUEST_FAILED',
+      details: statusPayload,
+    });
+  }
+
+  return {
+    ...statusPayload,
+    request_id: requestId,
+    status,
+    receipt_url: toStringValue(statusPayload?.receipt_url || statusPayload?.receiptUrl),
+    tx_hash: toStringValue(statusPayload?.tx_hash || statusPayload?.txHash),
+  };
+};
+
+const normalizeTransactionReceipt = (receiptPayload) => {
+  if (!isObject(receiptPayload)) {
+    throw new TxWalletGrazConnectorError('Transaction receipt payload must be an object.', {
+      code: 'REQUEST_FAILED',
+    });
+  }
+
+  const receiptId = toStringValue(receiptPayload?.receipt_id || receiptPayload?.receiptId);
+  const requestId = toStringValue(receiptPayload?.request_id || receiptPayload?.requestId);
+  const status = toStringValue(receiptPayload?.status).toLowerCase();
+  if (!receiptId || !requestId || !status) {
+    throw new TxWalletGrazConnectorError('Transaction receipt payload is missing receipt_id, request_id, or status.', {
+      code: 'REQUEST_FAILED',
+      details: receiptPayload,
+    });
+  }
+
+  return {
+    ...receiptPayload,
+    receipt_id: receiptId,
+    request_id: requestId,
+    status,
+  };
+};
+
+const normalizeTransactionRequest = (requestPayload) => {
+  if (!isObject(requestPayload)) {
+    throw new TxWalletGrazConnectorError('Transaction request payload must be an object.', {
+      code: 'REQUEST_FAILED',
+    });
+  }
+
+  const requestId = toStringValue(requestPayload?.request_id || requestPayload?.requestId);
+  const fallbackUrl = toStringValue(requestPayload?.fallback_url || requestPayload?.fallbackUrl);
+  const statusUrl = toStringValue(requestPayload?.status_url || requestPayload?.statusUrl);
+  if (!requestId || !fallbackUrl || !statusUrl) {
+    throw new TxWalletGrazConnectorError('Transaction request payload is missing request_id, fallback_url, or status_url.', {
+      code: 'REQUEST_FAILED',
+      details: requestPayload,
+    });
+  }
+
+  return {
+    ...requestPayload,
+    requestId,
+    fallbackUrl,
+    statusUrl,
+    status: toStringValue(requestPayload?.status) || 'pending',
+  };
+};
+
+const pollTransactionStatus = async ({ requestFetch, statusUrl, credentials, intervalMs, timeoutMs }) => {
+  const startedAt = Date.now();
+
+  while (Date.now() - startedAt < timeoutMs) {
+    const response = await requestFetch(statusUrl, {
+      method: 'GET',
+      credentials,
+      cache: 'no-store',
+      headers: {
+        Accept: 'application/json',
+      },
+    });
+
+    const statusPayload = await parseJsonResponse(response);
+    if (!response.ok) {
+      throw new TxWalletGrazConnectorError(statusPayload.error || `Transaction status request failed with HTTP ${response.status}.`, {
+        code: normalizeCode(statusPayload.code),
+        details: statusPayload,
+      });
+    }
+
+    const normalizedStatus = normalizeTransactionStatus(statusPayload);
+    if (TRANSACTION_FINAL_STATUSES.includes(normalizedStatus.status)) {
+      return normalizedStatus;
+    }
+
+    await delay(intervalMs);
+  }
+
+  throw new TxWalletGrazConnectorError('Transaction status polling timed out.', {
+    code: 'REQUEST_FAILED',
+  });
+};
+
+const isObject = (value) => value && typeof value === 'object';
+
+const getBrowserWindow = () => (typeof window !== 'undefined' ? window : undefined);
+
+const getFetch = (fetchImpl) => {
+  if (typeof fetchImpl === 'function') return fetchImpl;
+  if (typeof fetch === 'function') return fetch.bind(globalThis);
+  throw new TxWalletGrazConnectorError('TX Wallet Graz connector requires a fetch implementation.', {
+    code: 'INTERNAL_ERROR',
+  });
+};
+
+const parseJsonResponse = async (response) => response.json().catch(() => ({}));
+
+const delay = (intervalMs, signal) => new Promise((resolve, reject) => {
+  const timer = setTimeout(resolve, intervalMs);
+  if (!signal) return;
+
+  const abort = () => {
+    clearTimeout(timer);
+    reject(new DOMException('TX Wallet Graz polling aborted.', 'AbortError'));
+  };
+
+  signal.addEventListener('abort', abort, { once: true });
+});
+
+const resolveRequestOrigin = (requestOrigin) => {
+  const trimmed = toStringValue(requestOrigin);
+  if (trimmed) return trimmed.replace(/\/$/, '');
+
+  const browserWindow = getBrowserWindow();
+  if (browserWindow?.location?.origin) {
+    return browserWindow.location.origin;
+  }
+
+  return 'https://example.invalid';
+};
+
+const resolveOrigin = (inputUrl, label) => {
+  try {
+    return new URL(inputUrl).origin;
+  } catch {
+    throw new TxWalletGrazConnectorError(`${label} must be an absolute URL.`, {
+      code: 'REQUEST_FAILED',
+    });
+  }
+};
+
+const assertOriginMatch = (inputUrl, expectedOrigin, label) => {
+  const actualOrigin = resolveOrigin(inputUrl, label);
+  if (actualOrigin !== expectedOrigin) {
+    throw new TxWalletGrazConnectorError(
+      `${label} origin mismatch. Expected ${expectedOrigin} but received ${actualOrigin}.`,
+      { code: 'CALLBACK_ORIGIN_MISMATCH' },
+    );
+  }
+};
+
+const assertRequestIdMatch = (expectedRequestId, actualRequestId, label) => {
+  const expected = toStringValue(expectedRequestId);
+  const actual = toStringValue(actualRequestId);
+  if (!expected || !actual) return;
+  if (expected !== actual) {
+    throw new TxWalletGrazConnectorError(
+      `${label} request id mismatch. Expected ${expected} but received ${actual}.`,
+      { code: 'REQUEST_FAILED' },
+    );
+  }
+};
+
+const resolveAccountAddress = (statusPayload) => {
+  const fromObject = toStringValue(statusPayload?.account?.address || statusPayload?.account?.accountAddress);
+  if (fromObject) return fromObject;
+  return toStringValue(statusPayload?.accountAddress || statusPayload?.account);
+};
+
+const extractStatusCode = (statusPayload) => {
+  const requestCode = normalizeCode(statusPayload?.code);
+  if (requestCode !== 'INTERNAL_ERROR') return requestCode;
+
+  const status = toStringValue(statusPayload?.status).toLowerCase();
+  if (status === 'rejected') return 'USER_REJECTED';
+  if (status === 'expired') return 'REQUEST_EXPIRED';
+  return 'REQUEST_FAILED';
+};
+
+const buildSignInFallbackUrl = ({ walletBaseUrl, appId, requestId, callbackUrl }) => {
+  const fallbackUrl = new URL('/', walletBaseUrl);
+  fallbackUrl.searchParams.set('txwalletSignin', '1');
+  fallbackUrl.searchParams.set('app_id', appId);
+  fallbackUrl.searchParams.set('request_id', requestId);
+  fallbackUrl.searchParams.set('callback_url', callbackUrl);
+  return fallbackUrl.toString();
+};
+
+const buildSignInStatusUrl = ({ requestOrigin, requestId }) => (
+  new URL(`/api/tx-wallet/signin/requests/${encodeURIComponent(requestId)}/status`, requestOrigin).toString()
+);
+
+const openWalletWindow = (fallbackUrl, {
+  windowRef = getBrowserWindow(),
+  target = DEFAULT_WINDOW_TARGET,
+  features = DEFAULT_WINDOW_FEATURES,
+  fallbackToCurrentTab = true,
+} = {}) => {
+  if (!fallbackUrl || !windowRef) return null;
+
+  const popup = windowRef.open?.(fallbackUrl, target, features) || null;
+  if (popup?.focus) popup.focus();
+  if (!popup && fallbackToCurrentTab && windowRef.location?.assign) {
+    windowRef.location.assign(fallbackUrl);
+  }
+  return popup;
+};
+
+const createSignInRequest = async ({
+  requestFetch,
+  endpoint,
+  credentials,
+  callbackUrl,
+  chainId,
+  statement,
+  body,
+  sdkMetadata,
+}) => {
+  const response = await requestFetch(endpoint, {
+    method: 'POST',
+    credentials,
+    headers: {
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+    },
+    body: JSON.stringify({
+      ...body,
+      callback_url: callbackUrl,
+      chain_id: chainId,
+      statement: statement || 'Sign in with TX Wallet.',
+      ...(sdkMetadata ? { sdk_metadata: sdkMetadata } : {}),
+    }),
+  });
+
+  const responseBody = await parseJsonResponse(response);
+  if (!response.ok) {
+    throw new TxWalletGrazConnectorError(responseBody.error || `Sign-in request failed with HTTP ${response.status}.`, {
+      code: normalizeCode(responseBody.code),
+      details: responseBody,
+    });
+  }
+
+  const requestId = toStringValue(responseBody.request_id || responseBody.requestId);
+  const fallbackUrl = toStringValue(responseBody.fallback_url || responseBody.fallbackUrl);
+  const statusUrl = toStringValue(responseBody.status_url || responseBody.statusUrl);
+
+  if (!requestId || !fallbackUrl || !statusUrl) {
+    throw new TxWalletGrazConnectorError('Sign-in request response missing request_id, fallback_url, or status_url.', {
+      code: 'REQUEST_FAILED',
+      details: responseBody,
+    });
+  }
+
+  return {
+    requestId,
+    fallbackUrl,
+    statusUrl,
+  };
+};
+
+const pollStatusUntilFinal = async ({
+  requestFetch,
+  statusUrl,
+  credentials,
+  intervalMs = DEFAULT_POLL_INTERVAL_MS,
+  timeoutMs = DEFAULT_POLL_TIMEOUT_MS,
+  signal,
+}) => {
+  const startedAt = Date.now();
+
+  while (Date.now() - startedAt < timeoutMs) {
+    if (signal?.aborted) {
+      throw new DOMException('TX Wallet Graz polling aborted.', 'AbortError');
+    }
+
+    const response = await requestFetch(statusUrl, {
+      method: 'GET',
+      credentials,
+      cache: 'no-store',
+      signal,
+      headers: {
+        Accept: 'application/json',
+      },
+    });
+    const statusPayload = await parseJsonResponse(response);
+
+    if (!response.ok) {
+      throw new TxWalletGrazConnectorError(statusPayload.error || `Status request failed with HTTP ${response.status}.`, {
+        code: normalizeCode(statusPayload.code),
+        details: statusPayload,
+      });
+    }
+
+    const status = toStringValue(statusPayload.status).toLowerCase();
+    if (AUTH_FINAL_STATUSES.includes(status)) {
+      return statusPayload;
+    }
+
+    await delay(intervalMs, signal);
+  }
+
+  throw new TxWalletGrazConnectorError('Sign-in status polling timed out.', {
+    code: 'REQUEST_FAILED',
+  });
+};
+
+const normalizeConnectorError = (error) => {
+  if (error instanceof TxWalletGrazConnectorError) {
+    return error;
+  }
+
+  const fallbackMessage = 'TX Wallet Graz connector request failed.';
+  const message = error instanceof Error && error.message ? error.message : fallbackMessage;
+  const codeFromError = isObject(error) ? error.code : undefined;
+  const normalizedCode = codeFromError
+    ? normalizeCode(codeFromError)
+    : isAbortError(error)
+      ? 'REQUEST_FAILED'
+      : looksLikeNetworkError(error)
+        ? 'NETWORK_ERROR'
+        : 'INTERNAL_ERROR';
+
+  return new TxWalletGrazConnectorError(message, {
+    code: normalizedCode,
+    details: isObject(error) ? error : undefined,
+    cause: error,
+  });
+};
+
+const validateConnectedAccount = (result) => {
+  const accountAddress = toStringValue(result?.accountAddress);
+  const chainId = toStringValue(result?.chainId);
+
+  if (!accountAddress) {
+    throw new TxWalletGrazConnectorError('Connected account address is required.', { code: 'NO_ACTIVE_ACCOUNT' });
+  }
+
+  if (!chainId) {
+    throw new TxWalletGrazConnectorError('Connected chain id is required.', { code: 'UNSUPPORTED_CHAIN' });
+  }
+
+  return {
+    accountAddress,
+    chainId,
+    walletName: 'TX Wallet',
+  };
+};
+
+const validateSignResult = (result) => {
+  const status = toStringValue(result?.status).toLowerCase();
+  if (!TERMINAL_SIGN_STATUSES.includes(status)) {
+    throw new TxWalletGrazConnectorError('Sign result status must be approved, rejected, or failed.', { code: 'REQUEST_FAILED' });
+  }
+
+  const requestId = toStringValue(result?.requestId);
+  if (!requestId) {
+    throw new TxWalletGrazConnectorError('Sign result request id is required.', { code: 'REQUEST_FAILED' });
+  }
+
+  return {
+    status,
+    requestId,
+    txWalletResultUrl: toStringValue(result?.txWalletResultUrl) || undefined,
+    signature: result?.signature,
+    error: result?.error,
+  };
+};
+
+const validateRequestResult = (result) => {
+  const status = toStringValue(result?.status).toLowerCase();
+  if (!TRANSACTION_FINAL_STATUSES.includes(status)) {
+    throw new TxWalletGrazConnectorError('Transaction result status must be final.', { code: 'REQUEST_FAILED' });
+  }
+
+  const requestId = toStringValue(result?.requestId || result?.request_id);
+  if (!requestId) {
+    throw new TxWalletGrazConnectorError('Transaction result request id is required.', { code: 'REQUEST_FAILED' });
+  }
+
+  return {
+    status,
+    requestId,
+    txWalletResultUrl: toStringValue(result?.txWalletResultUrl || result?.tx_wallet_result_url) || undefined,
+    receiptUrl: toStringValue(result?.receiptUrl || result?.receipt_url) || undefined,
+    txHash: toStringValue(result?.txHash || result?.tx_hash) || undefined,
+    receipt: isObject(result?.receipt) ? result.receipt : undefined,
+    error: result?.error,
+  };
+};
+
+export class TxWalletGrazConnectorError extends Error {
+  constructor(message, { code, details, cause } = {}) {
+    super(message);
+    this.name = 'TxWalletGrazConnectorError';
+    this.code = normalizeCode(code);
+    this.details = details;
+    this.cause = cause;
+  }
+}
+
+export class TxWalletGrazConnector {
+  constructor({ handlers = {}, initialChainId = 'coreum-mainnet-1' } = {}) {
+    this.handlers = handlers;
+    this.state = 'idle';
+    this.chainId = toStringValue(initialChainId) || 'coreum-mainnet-1';
+    this.accountAddress = '';
+    this.listeners = new Map();
+  }
+
+  on(eventName, listener) {
+    if (!this.listeners.has(eventName)) {
+      this.listeners.set(eventName, new Set());
+    }
+    this.listeners.get(eventName).add(listener);
+    return () => this.off(eventName, listener);
+  }
+
+  off(eventName, listener) {
+    this.listeners.get(eventName)?.delete(listener);
+  }
+
+  emit(eventName, detail) {
+    for (const listener of this.listeners.get(eventName) || []) {
+      listener(detail);
+    }
+  }
+
+  setState(nextState) {
+    this.state = nextState;
+    this.emit('state', nextState);
+  }
+
+  getState() {
+    return this.state;
+  }
+
+  getSupportedSignStatuses() {
+    return [...TERMINAL_SIGN_STATUSES];
+  }
+
+  getSupportedRequestStatuses() {
+    return [...TRANSACTION_FINAL_STATUSES];
+  }
+
+  async connect(input) {
+    this.setState('connecting');
+    try {
+      if (typeof this.handlers.connect !== 'function') {
+        throw new TxWalletGrazConnectorError('Connect handler is not configured.', { code: 'INTERNAL_ERROR' });
+      }
+
+      const connected = validateConnectedAccount(await this.handlers.connect(input));
+      this.accountAddress = connected.accountAddress;
+      this.chainId = connected.chainId;
+      this.setState('connected');
+      this.emit('connected', connected);
+      return connected;
+    } catch (error) {
+      const normalized = normalizeConnectorError(error);
+      this.setState('error');
+      this.emit('error', normalized);
+      throw normalized;
+    }
+  }
+
+  async getAccount() {
+    if (!this.accountAddress) {
+      throw new TxWalletGrazConnectorError('No active TX Wallet account is connected.', {
+        code: 'NO_ACTIVE_ACCOUNT',
+      });
+    }
+
+    return {
+      accountAddress: this.accountAddress,
+      chainId: this.chainId,
+    };
+  }
+
+  async signAdr36(input) {
+    if (!this.accountAddress) {
+      throw new TxWalletGrazConnectorError('Wallet must be connected before signing.', {
+        code: 'NO_ACTIVE_ACCOUNT',
+      });
+    }
+
+    this.setState('signing');
+    try {
+      if (typeof this.handlers.signAdr36 !== 'function') {
+        throw new TxWalletGrazConnectorError('signAdr36 handler is not configured.', {
+          code: 'INTERNAL_ERROR',
+        });
+      }
+
+      const result = validateSignResult(await this.handlers.signAdr36(input));
+      this.setState('connected');
+      this.emit('signed', result);
+      return result;
+    } catch (error) {
+      const normalized = normalizeConnectorError(error);
+      this.setState('error');
+      this.emit('error', normalized);
+      throw normalized;
+    }
+  }
+
+  async requestTransaction(input) {
+    this.setState('requesting');
+    try {
+      if (typeof this.handlers.requestTransaction !== 'function') {
+        throw new TxWalletGrazConnectorError('requestTransaction handler is not configured.', {
+          code: 'INTERNAL_ERROR',
+        });
+      }
+
+      const result = validateRequestResult(await this.handlers.requestTransaction(input));
+      this.setState(this.accountAddress ? 'connected' : 'idle');
+      this.emit('requested', result);
+      return result;
+    } catch (error) {
+      const normalized = normalizeConnectorError(error);
+      this.setState('error');
+      this.emit('error', normalized);
+      throw normalized;
+    }
+  }
+
+  async launchRequest(input) {
+    return this.requestTransaction(input);
+  }
+
+  async disconnect() {
+    try {
+      if (typeof this.handlers.disconnect === 'function') {
+        await this.handlers.disconnect();
+      }
+    } finally {
+      this.accountAddress = '';
+      this.setState('disconnected');
+      this.emit('disconnected', {
+        chainId: this.chainId,
+      });
+    }
+  }
+}
+
+export function createTxWalletGrazConnector(options = {}) {
+  return new TxWalletGrazConnector(options);
+}
+
+export function createTxWalletGrazAuthHandlers({
+  fetchImpl,
+  requestOrigin,
+  createEndpoint = TX_WALLET_GRAZ_DEFAULT_SIGNIN_CREATE_ENDPOINT,
+  walletBaseUrl = DEFAULT_WALLET_BASE_URL,
+  credentials = 'include',
+  pollIntervalMs = DEFAULT_POLL_INTERVAL_MS,
+  pollTimeoutMs = DEFAULT_POLL_TIMEOUT_MS,
+  openWallet = openWalletWindow,
+  sdkMetadata,
+  supportedChains,
+} = {}) {
+  const requestFetch = getFetch(fetchImpl);
+  const resolvedOrigin = resolveRequestOrigin(requestOrigin);
+  const resolvedWalletOrigin = resolveOrigin(walletBaseUrl, 'walletBaseUrl');
+  const resolvedSupportedChains = normalizeSupportedChains(supportedChains);
+
+  const runSignIn = async ({ appId, callbackUrl, chainId, statement, body, requestId, statusUrl, fallbackUrl }) => {
+    const normalizedAppId = toStringValue(appId);
+    const normalizedCallbackUrl = toStringValue(callbackUrl);
+    const normalizedChainId = toStringValue(chainId) || 'coreum-mainnet-1';
+
+    if (!normalizedAppId) {
+      throw new TxWalletGrazConnectorError('appId is required.', { code: 'REQUEST_FAILED' });
+    }
+    if (!normalizedCallbackUrl) {
+      throw new TxWalletGrazConnectorError('callbackUrl is required.', { code: 'REQUEST_FAILED' });
+    }
+    assertOriginMatch(normalizedCallbackUrl, resolvedOrigin, 'callbackUrl');
+    assertSupportedChain(normalizedChainId, resolvedSupportedChains);
+
+    let resolvedRequestId = toStringValue(requestId);
+    let resolvedStatusUrl = toStringValue(statusUrl);
+    let resolvedFallbackUrl = toStringValue(fallbackUrl);
+
+    if (!resolvedRequestId || !resolvedStatusUrl || !resolvedFallbackUrl) {
+      const request = await createSignInRequest({
+        requestFetch,
+        endpoint: createEndpoint,
+        credentials,
+        callbackUrl: normalizedCallbackUrl,
+        chainId: normalizedChainId,
+        statement,
+        body,
+        sdkMetadata: normalizeSdkMetadata(sdkMetadata, 'graz'),
+      });
+      resolvedRequestId = request.requestId;
+      resolvedStatusUrl = request.statusUrl;
+      resolvedFallbackUrl = request.fallbackUrl;
+    }
+
+    assertOriginMatch(resolvedStatusUrl, resolvedOrigin, 'statusUrl');
+    assertOriginMatch(resolvedFallbackUrl, resolvedWalletOrigin, 'fallbackUrl');
+
+    openWallet(resolvedFallbackUrl);
+
+    const finalStatus = await pollStatusUntilFinal({
+      requestFetch,
+      statusUrl: resolvedStatusUrl,
+      credentials,
+      intervalMs: pollIntervalMs,
+      timeoutMs: pollTimeoutMs,
+    });
+
+    assertRequestIdMatch(
+      resolvedRequestId,
+      finalStatus?.request_id || finalStatus?.requestId,
+      'Auth status',
+    );
+
+    const normalizedStatus = toStringValue(finalStatus.status).toLowerCase();
+    if (normalizedStatus === 'approved') {
+      const accountAddress = resolveAccountAddress(finalStatus);
+      if (!accountAddress) {
+        throw new TxWalletGrazConnectorError('Approved sign-in status did not include an account.', {
+          code: 'NO_ACTIVE_ACCOUNT',
+          details: finalStatus,
+        });
+      }
+
+      return {
+        status: 'approved',
+        requestId: resolvedRequestId,
+        accountAddress,
+        chainId: normalizedChainId,
+        txWalletResultUrl: resolvedStatusUrl,
+      };
+    }
+
+    throw new TxWalletGrazConnectorError(finalStatus.error || `Sign-in request ${normalizedStatus || 'failed'}.`, {
+      code: extractStatusCode(finalStatus),
+      details: finalStatus,
+    });
+  };
+
+  return {
+    connect: async ({ chainId, appId, callbackUrl, statement }) => {
+      const result = await runSignIn({
+        chainId,
+        appId,
+        callbackUrl,
+        statement,
+      });
+
+      return {
+        accountAddress: result.accountAddress,
+        chainId: result.chainId,
+      };
+    },
+
+    signAdr36: async ({ appId, requestId, callbackUrl, challenge = {} }) => {
+      const challengeRecord = isObject(challenge) ? challenge : {};
+      const statusUrl = toStringValue(challengeRecord.statusUrl || challengeRecord.status_url)
+        || (requestId ? buildSignInStatusUrl({ requestOrigin: resolvedOrigin, requestId }) : '');
+      const fallbackUrl = toStringValue(challengeRecord.fallbackUrl || challengeRecord.fallback_url)
+        || (requestId ? buildSignInFallbackUrl({
+          walletBaseUrl,
+          appId,
+          requestId,
+          callbackUrl,
+        }) : '');
+
+      const result = await runSignIn({
+        appId,
+        callbackUrl,
+        chainId: toStringValue(challengeRecord.chainId || challengeRecord.chain_id) || 'coreum-mainnet-1',
+        statement: toStringValue(challengeRecord.statement),
+        body: challengeRecord,
+        requestId,
+        statusUrl,
+        fallbackUrl,
+      });
+
+      return {
+        status: 'approved',
+        requestId: result.requestId,
+        txWalletResultUrl: result.txWalletResultUrl,
+      };
+    },
+
+    disconnect: async () => undefined,
+  };
+}
+
+export function createTxWalletGrazAuthConnector(options = {}) {
+  const { initialChainId = 'coreum-mainnet-1', ...handlerOptions } = options;
+  return createTxWalletGrazConnector({
+    initialChainId,
+    handlers: createTxWalletGrazAuthHandlers(handlerOptions),
+  });
+}
+
+export function createTxWalletGrazTransactionHandlers({
+  fetchImpl,
+  requestOrigin,
+  createEndpoint = DEFAULT_TRANSACTION_CREATE_ENDPOINT,
+  walletBaseUrl = DEFAULT_WALLET_BASE_URL,
+  credentials = 'include',
+  pollIntervalMs = DEFAULT_POLL_INTERVAL_MS,
+  pollTimeoutMs = DEFAULT_POLL_TIMEOUT_MS,
+  openWallet = openWalletWindow,
+  allowReviewOnly = false,
+  sdkMetadata,
+  supportedChains,
+} = {}) {
+  const requestFetch = getFetch(fetchImpl);
+  const resolvedOrigin = resolveRequestOrigin(requestOrigin);
+  const resolvedWalletOrigin = resolveOrigin(walletBaseUrl, 'walletBaseUrl');
+  const resolvedSupportedChains = normalizeSupportedChains(supportedChains);
+
+  const createTransactionRequest = async ({ appId, callbackUrl, chainId, body, requestId, statusUrl, fallbackUrl }) => {
+    const normalizedAppId = toStringValue(appId);
+    const normalizedCallbackUrl = toStringValue(callbackUrl);
+    const normalizedChainId = toStringValue(chainId) || 'coreum-mainnet-1';
+
+    if (!normalizedAppId) {
+      throw new TxWalletGrazConnectorError('appId is required.', { code: 'REQUEST_FAILED' });
+    }
+    if (!normalizedCallbackUrl) {
+      throw new TxWalletGrazConnectorError('callbackUrl is required.', { code: 'REQUEST_FAILED' });
+    }
+    assertOriginMatch(normalizedCallbackUrl, resolvedOrigin, 'callbackUrl');
+    assertSupportedChain(normalizedChainId, resolvedSupportedChains);
+
+    const requestCategory = toStringValue(body?.category).toLowerCase();
+    if (!allowReviewOnly && REVIEW_ONLY_TRANSACTION_CATEGORIES.includes(requestCategory)) {
+      throw new TxWalletGrazConnectorError(
+        `Transaction category ${requestCategory} is review-only and blocked by default in the Graz adapter. Set allowReviewOnly=true only for explicit review fixtures.`,
+        { code: 'CATEGORY_REVIEW_ONLY' },
+      );
+    }
+
+    let resolvedRequestId = toStringValue(requestId);
+    let resolvedStatusUrl = toStringValue(statusUrl);
+    let resolvedFallbackUrl = toStringValue(fallbackUrl);
+
+    if (!resolvedRequestId || !resolvedStatusUrl || !resolvedFallbackUrl) {
+      const response = await requestFetch(createEndpoint, {
+        method: 'POST',
+        credentials,
+        headers: {
+          'Content-Type': 'application/json',
+          Accept: 'application/json',
+        },
+        body: JSON.stringify({
+          ...(body || {}),
+          callback_url: normalizedCallbackUrl,
+          chain_id: normalizedChainId,
+          ...(normalizeSdkMetadata(sdkMetadata, 'graz') ? { sdk_metadata: normalizeSdkMetadata(sdkMetadata, 'graz') } : {}),
+        }),
+      });
+
+      const responseBody = await parseJsonResponse(response);
+      if (!response.ok) {
+        throw new TxWalletGrazConnectorError(responseBody.error || `Transaction request failed with HTTP ${response.status}.`, {
+          code: normalizeCode(responseBody.code),
+          details: responseBody,
+        });
+      }
+
+      const request = normalizeTransactionRequest(responseBody);
+      resolvedRequestId = request.requestId;
+      resolvedStatusUrl = request.statusUrl;
+      resolvedFallbackUrl = request.fallbackUrl;
+    }
+
+    assertOriginMatch(resolvedStatusUrl, resolvedOrigin, 'statusUrl');
+    assertOriginMatch(resolvedFallbackUrl, resolvedWalletOrigin, 'fallbackUrl');
+
+    openWallet(resolvedFallbackUrl);
+
+    const finalStatus = await pollTransactionStatus({
+      requestFetch,
+      statusUrl: resolvedStatusUrl,
+      credentials,
+      intervalMs: pollIntervalMs,
+      timeoutMs: pollTimeoutMs,
+    });
+
+    assertRequestIdMatch(resolvedRequestId, finalStatus.request_id, 'Transaction status');
+
+    return {
+      status: finalStatus.status,
+      requestId: resolvedRequestId,
+      txWalletResultUrl: resolvedStatusUrl,
+      receiptUrl: finalStatus.receipt_url || undefined,
+      txHash: finalStatus.tx_hash || undefined,
+      receipt: finalStatus.receipt || undefined,
+      error: finalStatus.error || undefined,
+    };
+  };
+
+  return {
+    requestTransaction: async (input) => {
+      const result = await createTransactionRequest(input);
+      return validateRequestResult(result);
+    },
+  };
+}
+
+export function createTxWalletGrazTransactionConnector(options = {}) {
+  const { initialChainId = 'coreum-mainnet-1', ...handlerOptions } = options;
+  return createTxWalletGrazConnector({
+    initialChainId,
+    handlers: createTxWalletGrazTransactionHandlers(handlerOptions),
+  });
+}