sdk-suilink v1.1.1

SuiLink SDK Documentation

Overview

The SuiLink SDK is a TypeScript library that simplifies cross-chain wallet linking. It interacts directly with deployed move smart contracts on the Sui blockchain, enabling seamless linking of other blockchain wallet addresses to Sui.

The SuiLink SDK empowers developers to integrate the same functionality offered by SuiLink into their own applications. Developers can manage wallet associations, retrieve linked data, and access timestamps in a secure and efficient manner.

Currently, the SDK supports Ethereum and Solana but is designed to be extensible, allowing for the addition of other blockchain networks in the future.

Architecture Overview

The SuiLink SDK follows a straightforward architecture:

• Move Smart Contracts:

  • Implement core functionalities for address linking, deletion, and data retrieval.
  • Manage decentralized storage for cross-chain wallet associations.

• TypeScript SDK:

  • Provides an interface to interact with the smart contracts.
  • Encapsulates RPC calls to the Sui blockchain.

• No Backend Dependency:

  • All interactions are directly with the blockchain, ensuring trustless and decentralized functionality.

Features

• Cross-Chain Wallet Linking:

  • Link Ethereum or Solana addresses to a Sui address.
  • Validate ownership using cryptographic signatures.

• Data Retrieval:

  • Fetch linked wallet addresses for a given SuiLink.
  • Retrieve timestamps of link creation.

• Link Management:

  • Delete existing links to remove associations.

• Secure Transactions:

  • Validates addresses and cryptographic signatures.
  • Implements robust error handling for blockchain operations.

Limitations

• Wallet Connections: The SDK does not manage wallet connections or signing mechanisms. Applications must handle wallet interactions and pass the necessary data to the SDK.
• Network Scope: Currently supports Ethereum and Solana. Expanding to other blockchains requires custom implementations.

Technical Details

Address Validation

• Ethereum addresses are validated using the ethers.js library.
• Solana addresses are validated using @solana/web3.js.

Signature Processing

• Ethereum signatures are expected to be in hexadecimal format (0x prefixed).
• Solana signatures are expected to be a byte array.
• Helper functions are included in the SDK to assist in formatting and validating signatures for both Ethereum and Solana, ensuring the correct format is used when interacting with the blockchain.

Installation

Install the SDK via NPM:

npm install sdk-suilink

Initialization

Create an instance of the SuiLink SDK by initializing it with the required parameters.

Example Initialization

import { SuiClient } from '@mysten/sui/client';
import { EthereumLink, SolanaLink } from 'sdk-suilink';

const suiClient = new SuiClient({url: '<SUI_RPC_URL>'});


// Initialize EthereumLink
const ethereumLink = new EthereumLink(client, 'testnet'); // default is mainnet

// Initialize SolanaLink
const solanaLink = new SolanaLink(client, 'testnet'); // default is mainnet

EthereumLink Class

Methods

1. Link Ethereum Address

Links an Ethereum address to a Sui address. This method signs and executes the transaction on the Sui blockchain, creating the SuiLink directly.

async linkAddress(
  ethereumAddress: string,
  signature: string,
  signer: Keypair
): Promise<SuiObjectChangeCreated>;

Parameters:

• ethereumAddress: Ethereum wallet address.
• signature: Cryptographic signature proving ownership of the Ethereum address.
• signer: Keypair for signing the transaction on the Sui network.

Example:

await ethereumLink.linkAddress('0xEthereumAddress', '0xSignature', suiSigner);

2. Create Link Transaction

Prepares a transaction block for linking an Ethereum address. Unlike the linkAddress method, this function does not execute the transaction. Instead, it returns the transaction block, which can be passed to the calling application for execution.

This is useful for scenarios where the application needs to combine multiple transactions into a single execution.

createLinkTx(
  ethereumAddress: string,
  signature: string
): Transaction;

Parameters:

• ethereumAddress: Ethereum wallet address.
• signature: Cryptographic signature proving ownership of the Ethereum address.

Example:

const transaction = ethereumLink.createLinkTx('0xEthereumAddress', '0xSignature');
// The transaction block can then be signed and executed by the application
await client.signAndExecuteTransaction({ transaction, signer });

Notes:

• Option 1 (linkAddress): Automatically signs and executes the transaction, simplifying the process of creating a SuiLink.
• Option 2 (createLinkTx): Provides the flexibility to execute the transaction in the calling application, potentially alongside other transactions.

SolanaLink Class

Methods

1. Link Solana Address

Links a Solana address to a Sui address. This method signs and executes the transaction on the Sui blockchain, creating the SuiLink directly.

async linkAddress(
  solanaAddress: string,
  signature: number[],
  signer: Keypair
): Promise<SuiObjectChangeCreated>;

Parameters:

• solanaAddress: Solana wallet address.
• signature: Cryptographic signature proving ownership of the Solana address.
• signer: Keypair for signing the transaction on the Sui network.

Example:

await solanaLink.linkAddress('SolanaAddress', [/* signature bytes */], suiSigner);

2. Create Link Transaction

Prepares a transaction block for linking a Solana address. Unlike the linkAddress method, this function does not execute the transaction. Instead, it returns the transaction block, which can be passed to the calling application for execution.

This is useful for scenarios where the application needs to combine multiple transactions into a single execution.

createLinkTx(
  solanaAddress: string,
  signature: number[]
): Transaction;

Parameters:

• solanaAddress: Solana wallet address.
• signature: Cryptographic signature proving ownership of the Solana address.

Example:

const transaction = solanaLink.createLinkTx('SolanaAddress', [/* signature bytes */]);
// The transaction block can then be signed and executed by the application
await client.signAndExecuteTransaction({ transaction, signer });

Notes:

• Option 1 (linkAddress): Automatically signs and executes the transaction, simplifying the process of creating a SuiLink.
• Option 2 (createLinkTx): Provides the flexibility to execute the transaction in the calling application, potentially alongside other transactions.

Common Methods in SuiLink Class

The following methods are available in both EthereumLink and SolanaLink through inheritance from the SuiLink class:

1. Delete SuiLink

Deletes an existing SuiLink object. This can be achieved in two ways:

Option 1: Delete and Execute

This method directly deletes the SuiLink object by signing and executing the transaction.

async delete(
  suiLinkId: string,
  signer: Keypair
): Promise<void>;

Parameters:

• suiLinkId: Unique identifier of the SuiLink object.
• signer: Keypair for signing the deletion transaction.

Example:

await ethereumLink.delete('suiLinkId', suiSigner);

or

await solanaLink.delete('suiLinkId', suiSigner);

Note: From this point onward, examples will use ethereumLink for demonstration purposes. However, you can achieve the same functionality with solanaLink by substituting it accordingly.

Option 2: Create Delete Transaction

This method creates a transaction for deleting a SuiLink object and returns it to the application for execution. This is useful when combining multiple operations into a single transaction batch.

createDeleteTx(suiLinkId: string): Transaction;

Parameters:

• suiLinkId: Unique identifier of the SuiLink object.

Example:

const deleteTransaction = ethereumLink.createDeleteTx('suiLinkId');
// The transaction block can then be signed and executed by the application
await client.signAndExecuteTransaction({ transaction: deleteTransaction, signer });

2. Get Linked Network Address

Retrieves the address linked to a given SuiLink.

async getNetworkAddress(
  suiLinkId: string
): Promise<string>;

Parameters:

• suiLinkId: Unique identifier of the SuiLink object.

Example:

const linkedAddress = await ethereumLink.getNetworkAddress('suiLinkId');
console.log('Linked Address:', linkedAddress);

3. Get Timestamp

Fetches the timestamp of link creation.

async getTimestamp(
  suiLinkId: string
): Promise<number>;

Parameters:

• suiLinkId: Unique identifier of the SuiLink object.

Example:

const creationTimestamp = await ethereumLink.getTimestamp('suiLinkId');
console.log('Timestamp:', new Date(creationTimestamp * 1000).toLocaleString());

Network Configuration Functions

The SuiLink class provides utility functions for accessing important network configuration details. These functions are useful for developers who need to retrieve network-specific identifiers for their operations.

Methods

1. Get Package ID

Retrieves the package ID for the current network.

getPackageId(): string;

Returns:

• The move package ID string for the current network.

Example:

const packageId = ethereumLink.getPackageId();
console.log('Package ID:', packageId);

2. Get Registry ID

Retrieves the SuiLink registry ID for the current network.

getRegistryId(): string;

Returns:

• The registry object ID for the current network.

Example:

const registryId = ethereumLink.getRegistryId();
console.log('Registry ID:', registryId);

3. Get Clock Object ID

Retrieves the Sui clock object ID for the current network.

getClockObjectId(): string;

Returns:

• The clock object ID for the current network.

Example:

const clockObjectId = ethereumLink.getClockObjectId();
console.log('Clock Object ID:', clockObjectId);