z-wallet-sdk

A TypeScript SDK for interacting with zWallet.

Installation

You can install the SDK using npm:

npm i z-wallet-sdk

Usage

Initialization

Import the zWalletClient singleton instance to get started.

import { zWalletClient } from "z-wallet-sdk";

The client manages connection state internally. You can access it via these properties:

• zWalletClient.isConnected: boolean
• zWalletClient.walletInfo: WalletInfo | null
• zWalletClient.error: string | null

Connecting to the Wallet

To begin interacting with the user's wallet, you need to connect to it. This will open a popup window for the user to approve the connection.

import { zWalletClient } from "z-wallet-sdk";

async function connectWallet(event: MouseEvent) {
  try {
    // Optional: Position the popup relative to the user's click
    const popupLeft = window.screenX + event.clientX;
    const popupTop = window.screenY + event.clientY;

    await zWalletClient.connect({
      left: popupLeft,
      top: popupTop,
    });

    if (zWalletClient.isConnected) {
      console.log("Successfully connected to zWallet!");
      console.log("Wallet Info:", zWalletClient.walletInfo);
    } else {
      console.error("Connection failed:", zWalletClient.error);
    }
  } catch (error) {
    console.error("An error occurred during connection:", error);
  }
}

Sending a Raw Transaction

Send a pre-encoded raw transaction payload to the network.

import { zWalletClient } from "z-wallet-sdk";
import type { SendRawTransactionPayload } from "z-wallet-sdk";

async function sendRawTx() {
  if (!zWalletClient.isConnected) {
    alert("Please connect your wallet first.");
    return;
  }

  try {
    const tx: SendRawTransactionPayload = {
      chainId: 9369, // testnet: 1417429182, mainnet: 9369
      to: "0x...contract_address",
      transactionData: "0x...raw_calldata,
    };

    const response = await zWalletClient.sendRawTransaction(tx);

    if (response.data) {
      console.log("Raw transaction sent successfully!");
      console.log("Transaction Hash:", response.data.transactionHash);
    } else {
      console.error("Failed to send raw transaction:", response.error);
    }
  } catch (error) {
    console.error("An error occurred while sending the raw transaction:", error);
  }
}

Signing a Message

Once connected, you can request message signatures from the user.

import { zWalletClient } from "z-wallet-sdk";

async function sign() {
  if (!zWalletClient.isConnected) {
    alert("Please connect your wallet first.");
    return;
  }

  try {
    const message = "Login request for xyz.zyx";
    const chainId = 9369; // testnet: 1417429182, mainnet: 9369

    const response = await zWalletClient.signMessage(message, chainId);

    if (response.data) {
      console.log("Message signed successfully!");
      console.log("Signature:", response.data.signature);
      // Signatures should be verified with thirdweb as wallets are AA contract wallets
      const verifyResponse = await verifyContractWalletSignature({
        chain: chain,
        client: thirdwebClient,
        address: zWalletClient.walletInfo.zeroWallet,
        message,
        signature: response.data.signature,
      });
    } else {
      console.error("Failed to sign message:", response.error);
    }
  } catch (error) {
    console.error("An error occurred while signing the message:", error);
  }
}

Calling a Contract

You can also send transactions to smart contracts.

import { zWalletClient } from "z-wallet-sdk";
import type { CallContractTransaction } from "z-wallet-sdk";

async function transferTokens() {
  if (!zWalletClient.isConnected) {
    alert("Please connect your wallet first.");
    return;
  }

  try {
    const transaction: CallContractTransaction = {
      chainId: 1, // Example Chain ID
      contractAddress: "0x...your_token_contract_address",
      method: "transfer(address to, uint256 value)", // Function signature
      params: [
        "0x...recipient_address", // Recipient address
        "1000000000000000000", // Amount (e.g., 1 token with 18 decimals)
      ],
    };

    const response = await zWalletClient.callContract(transaction);

    if (response.data) {
      console.log("Contract call successful!");
      console.log("Transaction Hash:", response.data.transactionHash);
    } else {
      console.error("Contract call failed:", response.error);
    }
  } catch (error) {
    console.error("An error occurred during the contract call:", error);
  }
}