@txwallet/graz-connector

Thin-slice TX Wallet compatibility connector for Graz-oriented Cosmos integrations.

Ownership note: this package is an adapter layer. The TX Wallet Auth protocol remains the source of truth for request IDs, payload verification, callback policy, and approval outcomes.

This package is the first implementation rail only:

• connect
• account and chain context
• ADR-36 sign-in result path
• typed transaction-request launch path for approved payment lanes

It does not claim full Keplr or Leap parity.

Partner rollout checklist: see TX_WALLET_GRAZ_PARTNER_QUICKSTART.md in the repo root for the end-to-end thin-slice handoff flow.

Install

npm install @txwallet/graz-connector

Minimal usage

import { createTxWalletGrazConnector } from '@txwallet/graz-connector';

const connector = createTxWalletGrazConnector({
  handlers: {
    connect: async ({ chainId, appId, callbackUrl }) => {
      // map into existing TX Wallet connect/request rails
      return {
        accountAddress: 'core1example...',
        chainId,
      };
    },
    signAdr36: async ({ appId, requestId, callbackUrl, challenge }) => {
      // map into existing TX Wallet sign-in approval flow
      return {
        status: 'approved',
        requestId,
        signature: {
          pubKey: 'A1B2...',
          signature: 'MEQC...',
          signed: challenge,
        },
      };
    },
    disconnect: async () => {
      // clear session state only
    },
  },
});

await connector.connect({
  chainId: 'coreum-mainnet-1',
  appId: 'txapp_01JZ8S3J9M3N7Q2K5R9V6X4H1A',
  callbackUrl: 'https://partner.example.com/tx-wallet/callback',
});

const account = await connector.getAccount();

Live TX Wallet Auth-backed usage

Use the built-in handlers when you want this connector to call your existing TX Wallet Auth endpoints directly.

import {
  createTxWalletGrazAuthConnector,
} from '@txwallet/graz-connector';

const connector = createTxWalletGrazAuthConnector({
  requestOrigin: window.location.origin,
  walletBaseUrl: 'https://txwallet.tesbert.com',
  supportedChains: ['coreum-mainnet-1', 'coreum-testnet-1'],
});

await connector.connect({
  chainId: 'coreum-mainnet-1',
  appId: 'txapp_01JZ8S3J9M3N7Q2K5R9V6X4H1A',
  callbackUrl: 'https://partner.example.com/tx-wallet/callback',
  statement: 'Connect with TX Wallet',
});

const signResult = await connector.signAdr36({
  appId: 'txapp_01JZ8S3J9M3N7Q2K5R9V6X4H1A',
  callbackUrl: 'https://partner.example.com/tx-wallet/callback',
  challenge: {
    statement: 'Sign in with TX Wallet.',
  },
});

console.log(signResult.status, signResult.requestId);

Notes:

• connect() creates and polls a standard sign-in request and returns normalized account context.
• signAdr36() uses the same approval rail and returns approved/rejected/failed terminal status.
• If your backend already created a sign-in request, pass requestId to signAdr36().
• Unknown chainId values now fail fast with UNSUPPORTED_CHAIN before network calls. Override allowed chains with supportedChains when needed.
• Callback and status URL origins are enforced against requestOrigin; mismatches fail fast with CALLBACK_ORIGIN_MISMATCH before network calls.
• Fallback handoff URLs are enforced against the configured walletBaseUrl origin; mismatches fail fast with CALLBACK_ORIGIN_MISMATCH before opening a wallet window.
• Status payload request_id values are integrity-checked against the expected request id; mismatches fail with REQUEST_FAILED to prevent cross-request result confusion.

React / Graz hook usage

Graz is hooks-first, so @txwallet/graz-connector/react ships a useTxWalletGrazConnector hook with graz-style ergonomics. Pass auth-handler options (a connector is built once on mount) or an existing connector instance. react is an optional peer dependency.

import { useTxWalletGrazConnector } from '@txwallet/graz-connector/react';

function ConnectTxWallet() {
  const { connect, signAdr36, disconnect, account, error, isConnecting, isConnected } =
    useTxWalletGrazConnector({
      requestOrigin: window.location.origin,
      walletBaseUrl: 'https://txwallet.tesbert.com',
    });

  if (isConnected) {
    return (
      <div>
        <p>Connected: {account?.accountAddress}</p>
        <button onClick={() => signAdr36({
          appId: 'txapp_01JZ8S3J9M3N7Q2K5R9V6X4H1A',
          callbackUrl: 'https://partner.example.com/tx-wallet/callback',
          challenge: { statement: 'Sign in with TX Wallet.' },
        })}>Sign in</button>
        <button onClick={() => disconnect()}>Disconnect</button>
      </div>
    );
  }

  return (
    <button
      disabled={isConnecting}
      onClick={() => connect({
        chainId: 'coreum-mainnet-1',
        appId: 'txapp_01JZ8S3J9M3N7Q2K5R9V6X4H1A',
        callbackUrl: 'https://partner.example.com/tx-wallet/callback',
      })}
    >
      {isConnecting ? 'Connecting…' : 'Connect TX Wallet'}{error ? ` — ${error.code}` : ''}
    </button>
  );
}

Hook actions are fire-and-forget safe (failures surface through error/status, no unhandled rejections); use the returned connector directly when you need the raw awaitable/throwing calls.

Transaction Requests

Use the transaction-request handlers when Graz-oriented integrations need to launch a typed TX Wallet Request instead of an ADR-36 sign-in.

import { createTxWalletGrazTransactionConnector } from '@txwallet/graz-connector';

const connector = createTxWalletGrazTransactionConnector({
  requestOrigin: window.location.origin,
  walletBaseUrl: 'https://txwallet.tesbert.com',
});

const result = await connector.requestTransaction({
  appId: 'txapp_01JZ8S3J9M3N7Q2K5R9V6X4H1A',
  callbackUrl: 'https://partner.example.com/tx-wallet/callback',
  chainId: 'coreum-mainnet-1',
  body: {
    category: 'token_payment',
    payer: 'core1payer...',
    recipient: 'core1recipient...',
    amount: '1',
  },
});

console.log(result.status, result.txHash);

For partners that already assemble the request envelope themselves, requestTransaction() also accepts prebuilt requestId, statusUrl, and fallbackUrl values.

Transaction support in this adapter is intentionally focused on the approved payment lanes. Keep checkout/payment mainnet lanes behind the existing app and rollout switches, and do not use the connector as a blind-signing surface.

• requestTransaction() launches and polls a typed TX Wallet Request and returns the final request status.
• The connector emits a request result through the same connector state machine, but the request rail is still separate from ADR-36 sign-in.
• Review-only categories are blocked by default in the transaction handlers to prevent accidental production onboarding mistakes; use allowReviewOnly: true only for explicit review-fixture workflows.

Error behavior

Expected stable error code buckets include:

• WALLET_LOCKED
• NO_ACTIVE_ACCOUNT
• UNSUPPORTED_CHAIN
• REQUEST_EXPIRED
• CALLBACK_ORIGIN_MISMATCH
• USER_REJECTED
• REQUEST_FAILED
• NETWORK_ERROR
• INTERNAL_ERROR

Boundary

Use this adapter as a compatibility bridge into existing TX Wallet Auth rails. Treat TX Wallet protocol docs and server/client rails as authoritative behavior. Do not bypass approval UI, policy checks, or request validation.