Custom Data

This guide explains how to implement custom data functionality using the Cross SDK, including both signature and transaction features.

Signature with Custom Data

1. Sign Custom Data

// React Example
import { useAppKitAccount, ConnectionController } from '@to-nexus/sdk/react'

async function handleSignMessage() {
  const account = useAppKitAccount()
  if (!account?.isConnected) return

  const signedMessage = await ConnectionController.signMessage({ 
    message: `Hello, world! ${Date.now()}`,
    customData: {
      metadata: "This is metadata for signed message"
    }
  })
}

// Vanilla JS Example
import { ConnectionController } from '@to-nexus/sdk';

const signedMessage = await ConnectionController.signMessage({
  message: `Hello, world! ${Date.now()}`,
  customData: {
    metadata: 'This is metadata for signed message'
  }
});

2. Plain Text

// React Example
import { useAppKitAccount, ConnectionController } from '@to-nexus/sdk/react'

async function handleSignMessage() {
  const account = useAppKitAccount()
  if (!account?.isConnected) return

  const signedMessage = await ConnectionController.signMessage({ 
    message: `Hello, world! ${Date.now()}`,
    customData: {
      metadata: "This is a plain text message for signature"
    }
  })
}

// Vanilla JS Example
import { ConnectionController } from '@to-nexus/sdk';

const signedMessage = await ConnectionController.signMessage({
  message: `Hello, world! ${Date.now()}`,
  customData: {
    metadata: 'This is a plain text message for signature'
  }
});

3. JSON Data

// React Example
import { useAppKitAccount, ConnectionController } from '@to-nexus/sdk/react'

async function handleSignMessage() {
  const account = useAppKitAccount()
  if (!account?.isConnected) return

  const signedMessage = await ConnectionController.signMessage({ 
    message: `Hello, world! ${Date.now()}`,
    customData: {
      metadata: JSON.stringify({
        type: "signature",
        purpose: "authentication",
        timestamp: new Date().toISOString()
      })
    }
  })
}

// Vanilla JS Example
import { ConnectionController } from '@to-nexus/sdk';

const signedMessage = await ConnectionController.signMessage({
  message: `Hello, world! ${Date.now()}`,
  customData: {
    metadata: JSON.stringify({
      type: 'signature',
      purpose: 'authentication',
      timestamp: new Date().toISOString()
    })
  }
});

4. Binary Data

// React Example
import { useAppKitAccount, ConnectionController } from '@to-nexus/sdk/react'

async function handleSignMessage() {
  const account = useAppKitAccount()
  if (!account?.isConnected) return

  const binaryData = new TextEncoder().encode("Binary data for signature")
  
  const signedMessage = await ConnectionController.signMessage({ 
    message: `Hello, world! ${Date.now()}`,
    customData: {
      metadata: binaryData,
      format: "binary"
    }
  })
}

// Vanilla JS Example
import { ConnectionController } from '@to-nexus/sdk';

const binaryData = new TextEncoder().encode('Binary data for signature');
const signedMessage = await ConnectionController.signMessage({
  message: `Hello, world! ${Date.now()}`,
  customData: {
    metadata: binaryData,
    format: 'binary'
  }
});

Transaction with Custom Data

1. Plain Text

// React Example
import { useAppKitAccount, SendController } from '@to-nexus/sdk/react'

async function handleSendNative() {
  const account = useAppKitAccount()
  if (!account?.isConnected) return

  const resTx = await SendController.sendNativeToken({
    receiverAddress: RECEIVER_ADDRESS,
    sendTokenAmount: 1,
    decimals: '18',
    customData: {
      metadata: "You are about to send 1 CROSS to the receiver address. This is plain text formatted custom data."
    }
  })
}

// Vanilla JS Example
import { SendController, ConstantsUtil } from '@to-nexus/sdk';

const RECEIVER_ADDRESS = '0xB09f7E5309982523310Af3eA1422Fcc2e3a9c379';
const resTx = await SendController.sendNativeToken({
  data: '0x',
  receiverAddress: RECEIVER_ADDRESS,
  sendTokenAmount: 1,
  decimals: '18',
  customData: {
    metadata: 'You are about to send 1 CROSS to the receiver address. This is plain text formatted custom data.'
  },
  type: ConstantsUtil.TRANSACTION_TYPE.LEGACY
});

2. JSON Data

// React Example
import { useAppKitAccount, SendController } from '@to-nexus/sdk/react'

async function handleSendTransaction() {
  const account = useAppKitAccount()
  if (!account?.isConnected) return

  const resTx = await SendController.sendNativeToken({
    receiverAddress: RECEIVER_ADDRESS,
    sendTokenAmount: 1,
    decimals: '18',
    customData: {
      metadata: JSON.stringify({
        type: "payment",
        description: "Monthly subscription",
        reference: "SUB-2024-03",
        amount: 1,
        currency: "CROSS"
      })
    }
  })
}

// Vanilla JS Example
import { SendController, ConstantsUtil } from '@to-nexus/sdk';

const RECEIVER_ADDRESS = '0xB09f7E5309982523310Af3eA1422Fcc2e3a9c379';
const resTx = await SendController.sendNativeToken({
  data: '0x',
  receiverAddress: RECEIVER_ADDRESS,
  sendTokenAmount: 1,
  decimals: '18',
  customData: {
    metadata: JSON.stringify({
      type: 'payment',
      description: 'Monthly subscription',
      reference: 'SUB-2024-03',
      amount: 1,
      currency: 'CROSS'
    })
  },
  type: ConstantsUtil.TRANSACTION_TYPE.LEGACY
});

3. Binary Data

// React Example
import { useAppKitAccount, SendController } from '@to-nexus/sdk/react'

async function handleSendTransaction() {
  const account = useAppKitAccount()
  if (!account?.isConnected) return

  const binaryData = new TextEncoder().encode("Binary data example")
  
  const resTx = await SendController.sendNativeToken({
    receiverAddress: RECEIVER_ADDRESS,
    sendTokenAmount: 1,
    decimals: '18',
    customData: {
      metadata: binaryData,
      format: "binary"
    }
  })
}

// Vanilla JS Example
import { SendController, ConstantsUtil } from '@to-nexus/sdk';

const RECEIVER_ADDRESS = '0xB09f7E5309982523310Af3eA1422Fcc2e3a9c379';
const binaryData = new TextEncoder().encode('Binary data example');
const resTx = await SendController.sendNativeToken({
  data: '0x',
  receiverAddress: RECEIVER_ADDRESS,
  sendTokenAmount: 1,
  decimals: '18',
  customData: {
    metadata: binaryData,
    format: 'binary'
  },
  type: ConstantsUtil.TRANSACTION_TYPE.LEGACY
});

Read Custom Data

1. Read Transaction Data

// React Example
import { ConnectionController } from '@to-nexus/sdk/react'

async function readCustomData(txHash: string) {
  const tx = await ConnectionController.getTransaction(txHash)
  
  if (tx.customData?.format === "binary") {
    // Handle binary data
    const decoder = new TextDecoder()
    return decoder.decode(tx.customData.metadata)
  }
  
  if (tx.customData?.metadata) {
    try {
      // Try parsing as JSON
      return JSON.parse(tx.customData.metadata)
    } catch {
      // Return as plain text if not JSON
      return tx.customData.metadata
    }
  }
  
  return null
}

// Vanilla JS Example
import { ConnectionController } from '@to-nexus/sdk';

async function readCustomData(txHash) {
  const tx = await ConnectionController.getTransaction(txHash);

  if (tx.customData?.format === 'binary') {
    // Handle binary data
    const decoder = new TextDecoder();
    return decoder.decode(tx.customData.metadata);
  }

  if (tx.customData?.metadata) {
    try {
      // Try parsing as JSON
      return JSON.parse(tx.customData.metadata);
    } catch {
      // Return as plain text if not JSON
      return tx.customData.metadata;
    }
  }

  return null;
}