zigap-utils

A utility library that helps communicate between dapp and zigap

📖 Documentation • 🚀 Installation • 💡 Usage

📦 Installation

npm install zigap-utils

yarn add zigap-utils

pnpm add zigap-utils

🚀 Usage

zigap-utils provides React components for seamless communication between dapp and zigap app.

📋 Table of Contents

• 🔐 LoginQR
• ✍️ SignatureQR
• 💸 SendTransactionQR

🔐 LoginQR

QR code component for user wallet login.

Basic Usage

import { LoginQR, LoginResultType } from 'zigap-utils';

const App = () => {
  const [result, setResult] = useState<LoginResultType | null>(null);

  return (
    <div>
      <LoginQR
        dapp='My Awesome Dapp'
        url='https://myapp.com'
        availableNetworks={['v2xphere', 'v3xphere']}
        sigMessage='Welcome to My Dapp!'
        validSeconds={600}
        onReceive={({ status, result }) => {
          if (status === 'SUCCESS') {
            console.log('Login successful!', result);
            setResult(result as LoginResultType);
          }
        }}
      />
    </div>
  );
};

Props

| Prop | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | dapp | string | ✅ | - | dapp name | | url | string | ✅ | - | dapp URL | | availableNetworks | ('binance' \| 'ethereum' \| 'v2xphere' \| 'v3xphere')[] | ✅ | - | supported networks | | sigMessage | string | ✅ | - | signature message | | validSeconds | number | ✅ | - | QR code valid time | | onReceive | (res) => void | ❌ | - | login result callback | | expire | LoginExpireType | ❌ | { type : 'NONE'} | expiration settings | | icon | string | ❌ | - | dapp icon URL | | processingMark | ProcessingMarkType | ❌ | { type: 'DEFAULT' } | processing display | | qrDomain | string | ❌ | https://zigap.io | QR domain |

Supported Networks

• 'binance' (bsc)
• 'ethereum' (eth)
• 'v2xphere' (xp)
• 'v3xphere' (xpt)

Status Values

• 'SUCCESS' - Login successful
• 'REQUEST' - Request in progress
• 'ACCOUNT' - Account selection in progress
• 'ERROR' - Error occurred

LoginResultType

interface LoginResultType {
  address: string;
  network: string;
  nickName: string;
  token: string;
  issuedDateTime: string;
  expire: LoginExpireType;
  isVerified: boolean;
  signature: string;
}

✍️ SignatureQR

QR code component for message signing.

Basic Usage

import { SignatureQR, SignatureResultType } from 'zigap-utils';

const App = () => {
  const [result, setResult] = useState<SignatureResultType | null>(null);

  return (
    <div>
      <SignatureQR
        dapp='My Awesome Dapp'
        url='https://myapp.com'
        availableNetworks={['v2xphere', 'v3xphere']}
        sigMessage='I agree to the terms and conditions'
        validSeconds={600}
        onReceive={({ status, result }) => {
          if (status === 'SUCCESS') {
            console.log('Signature successful!', result);
            setResult(result as SignatureResultType);
          }
        }}
      />
    </div>
  );
};

Props

| Prop | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | dapp | string | ✅ | - | dapp name | | url | string | ✅ | - | dapp URL | | availableNetworks | ('binance' \| 'ethereum' \| 'v2xphere' \| 'v3xphere')[] | ✅ | - | supported networks | | sigMessage | string | ✅ | - | message to sign | | validSeconds | number | ✅ | - | QR code valid time | | onReceive | (res) => void | ❌ | - | signature result callback | | expire | SignatureLoginExpireType | ❌ | { type : 'NONE'} | expiration settings | | icon | string | ❌ | - | dapp icon URL | | processingMark | SignatureProcessingMarkType | ❌ | { type: 'DEFAULT' } | processing display | | qrDomain | string | ❌ | https://zigap.io | QR domain |

Supported Networks

• 'binance' (bsc)
• 'ethereum' (eth)
• 'v2xphere' (xp)
• 'v3xphere' (xpt)

Status Values

• 'SUCCESS' - Signature successful
• 'REQUEST' - Request in progress
• 'ACCOUNT' - Account selection in progress
• 'ERROR' - Error occurred

SignatureResultType

interface SignatureResultType {
  address: string;
  network: string;
  nickName: string;
  token: string;
  issuedDateTime: string;
  expire: SignatureLoginExpireType;
  isVerified: boolean;
  signature: string;
}

💸 SendTransactionQR

QR code component for transaction sending.

Basic Usage

import { SendTransactionQR, SendTransactionResultType } from 'zigap-utils';

const App = () => {
  const [result, setResult] = useState<SendTransactionResultType | null>(null);

  return (
    <div>
      <SendTransactionQR
        dapp='My Awesome Dapp'
        url='https://myapp.com'
        availableNetworks='v2xphere'
        validSeconds={600}
        transaction={{
          type: 0,
          to: '0x1234567890123456789012345678901234567890',
          value: '1000000000000000000', // 1 XP
          gasLimit: '21000',
          gasPrice: '1000000000',
        }}
        onReceive={({ status, result }) => {
          if (status === 'SUCCESS') {
            console.log('Transaction Complete!', result);
            setResult(result as SendTransactionResultType);
          }
        }}
      />
    </div>
  );
};

Props

| Prop | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | dapp | string | ✅ | - | dapp name | | url | string | ✅ | - | dapp URL | | availableNetworks | 'binance' \| 'ethereum' \| 'v2xphere' \| 'v3xphere' | ✅ | - | supported network (single value) | | validSeconds | number | ✅ | - | QR code valid time | | transaction | TransactionType | ✅ | - | transaction configuration | | onReceive | (res) => void | ❌ | - | transaction result callback | | icon | string | ❌ | - | dapp icon URL | | processingMark | ProcessingMarkType | ❌ | { type: 'DEFAULT' } | processing display | | qrDomain | string | ❌ | https://zigap.io | QR domain |

Supported Networks

• 'binance' (bsc)
• 'ethereum' (eth)
• 'v2xphere' (xp)
• 'v3xphere' (xpt)

TransactionType

// Type 0: Legacy (pre-EIP-2718)
interface TransactionType0 {
  type: 0 | '0x0';
  to: string;
  data?: string;
  value: string;
  gasLimit: string;
  gasPrice: string;
  chainId?: number;
}

// Type 1: EIP-2930 (access list)
interface TransactionType1 {
  type: 1 | '0x1';
  to: string;
  data?: string;
  value: string;
  gasLimit: string;
  gasPrice: string;
  accessList?: AccessList;
  chainId?: number;
}

// Type 2: EIP-1559 (dynamic fees)
interface TransactionType2 {
  type: 2 | '0x2';
  to: string;
  data?: string;
  value: string;
  gasLimit: string;
  maxFeePerGas: string;
  maxPriorityFeePerGas: string;
  chainId?: number;
}

type TransactionType = TransactionType0 | TransactionType1 | TransactionType2;

SendTransactionResultType

interface SendTransactionResultType {
  txHash: string;
  status: 0 | 1; // 0 : fail , 1 : success
  error: string;
}

Status Values

• 'SUCCESS' - Transaction successful
• 'REQUEST' - Request in progress
• 'ERROR' - Error occurred

🎨 Common Style Props

Common style options available for all QR components.

| Prop | Type | Default | Description | | ------------ | --------------- | ------- | ---------------------------- | | size | number | 128 | QR code canvas size | | bgColor | string | #fff | background color | | fgColor | string | #000 | foreground color | | style | CSSProperties | - | custom CSS style | | isShowLogo | boolean | false | show Zigap logo in QR center | | logoSize | number | 30 | logo size |

Example

<LoginQR
  // ... other props
  size={200}
  bgColor='#ffffff'
  fgColor='#000000'
  isShowLogo={true}
  logoSize={40}
  style={{ borderRadius: '8px' }}
/>

⚙️ Processing Mark Options

Configure how to display during processing.

Options

• 'DEFAULT' - Shows default "processing..." message
• 'CUSTOM' - Allows custom React component
• 'NONE' - No visual indicator

Custom Component Example

<SendTransactionQR
  // ... other props
  processingMark={{
    type: 'CUSTOM',
    component: (
      <div
        style={{
          display: 'flex',
          alignItems: 'center',
          gap: '8px',
        }}
      >
        <div className='spinner'></div>
        <span>Processing payment...</span>
      </div>
    ),
  }}
/>

📝 Expire Configuration

Configure expiration time and type.

// No expiration
expire={{ type: 'NONE' }}

// Fixed expiration time
expire={{ type: 'FIX', seconds: 3600 }}

// Extendable expiration time
expire={{ type: 'EXTEND', seconds: 3600 }}

📄 License

ISC License

Made with by Seoul Labs

📖 Documentation