0.2.0

@0xfacet/sdk

The @0xfacet/sdk is a TypeScript SDK designed for interacting with the Facet network, a decentralized rollup on Ethereum. This SDK simplifies sending transactions, reading from contracts, and handling Facet's unique transaction model, with full compatibility with viem and wagmi.

Table of Contents

• Installation
• Getting Started
• API Reference
  • Viem Integration
  • WAGMI Integration
  • Utility Functions
• Examples
  • Using Viem Methods
  • Using WAGMI Hooks
  • Using Standard Methods
• Contributing
• License

Installation

Install the package via npm or yarn:

npm install @0xfacet/sdk

yarn add @0xfacet/sdk

Getting Started

Import and use the SDK functions as needed:

// For viem users
import {
  sendFacetTransaction,
  writeFacetContract,
  bridgeAndCall,
  facetMainnet,
} from "@0xfacet/sdk/viem";
import { createWalletClient, http } from "viem";

// For wagmi users
import {
  useSendFacetTransaction,
  useWriteFacetContract,
  useBridgeAndCall,
} from "@0xfacet/sdk/wagmi";

// For utility functions
import {
  getFctMintRate,
  decodeFacetEncodedTransaction,
  computeFacetTransactionHash,
  sendRawFacetTransaction,
} from "@0xfacet/sdk/utils";

API Reference

Viem Integration

sendFacetTransaction

Sends a transaction through the Facet protocol.

function sendFacetTransaction<chain, account, request, chainOverride>(
  client: Client<Transport, chain, account>,
  parameters: SendTransactionParameters<
    chain,
    account,
    chainOverride,
    request
  > & {
    mineBoost?: Hex; // Optional boost to increase FCT mining amount
  }
): Promise<SendTransactionReturnType>;

writeFacetContract

Executes a write operation on a contract through the Facet infrastructure.

function writeFacetContract<
  chain,
  account,
  abi,
  functionName,
  args,
  chainOverride,
>(
  client: Client<Transport, chain, account>,
  parameters: WriteContractParameters<
    abi,
    functionName,
    args,
    chain,
    account,
    chainOverride
  > & {
    mineBoost?: Hex; // Optional boost to increase FCT mining amount
  }
): Promise<WriteContractReturnType>;

bridgeAndCall

Bridges ETH from L1 to L2 and executes a contract call in a single transaction.

function bridgeAndCall<chain, account, abi, functionName, args, chainOverride>(
  client: Client<Transport, chain, account>,
  parameters: WriteContractParameters<
    abi,
    functionName,
    args,
    chain,
    account,
    chainOverride
  >,
  ethValue: bigint,
  bridgeAndCallConfig?: BridgeAndCallConfig
): Promise<WriteContractReturnType>;

WAGMI Integration

useSendFacetTransaction

React hook for sending Facet transactions.

function useSendFacetTransaction<config, context>(
  parameters?: UseSendFacetTransactionParameters<config, context>
): UseSendFacetTransactionReturnType<config, context>;

The transaction parameters can include the optional mineBoost property to increase the amount of FCT mined by the transaction.

useWriteFacetContract

React hook for executing write operations on contracts through Facet.

function useWriteFacetContract<abi, functionName, args, config, context>(
  parameters?: UseWriteFacetContractParameters<
    abi,
    functionName,
    args,
    config,
    context
  >
): UseWriteFacetContractReturnType<abi, functionName, args, config, context>;

The contract write parameters can include the optional mineBoost property to increase the amount of FCT mined by the transaction.

useBridgeAndCall

React hook for bridging ETH from L1 to L2 and executing a call on L2.

function useBridgeAndCall<config, context>(
  parameters?: UseBridgeAndCallParameters<config, context>
): UseBridgeAndCallReturnType<config, context>;

Utility Functions

getFctMintRate

Retrieves the current FCT mint rate from the L1 block contract.

function getFctMintRate(l1ChainId: 1 | 11155111): Promise<bigint>;

computeFacetTransactionHash

Computes a hash for a Facet transaction.

function computeFacetTransactionHash(
  l1TransactionHash: Hex,
  from: Address,
  to: Address,
  value: bigint,
  data: Hex,
  gasLimit: bigint,
  mint: bigint
): Hex;

Examples

Using Viem Methods

Send a Facet Transaction

import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { mainnet } from "viem/chains";
import { sendFacetTransaction } from "@0xfacet/sdk/viem";

const account = privateKeyToAccount("0xYourPrivateKey");
const client = createWalletClient({
  account,
  chain: mainnet,
  transport: http(),
});

// Send a basic transaction
const hash = await sendFacetTransaction(client, {
  to: "0xRecipientAddress",
  value: 1000000000000000000n, // 1 FCT
  data: "0x", // Empty data for simple FCT transfer
  mineBoost: "0x01", // Optional: increase FCT mining amount
});

console.log("Transaction hash:", hash);

Write to a Contract

import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { mainnet } from "viem/chains";
import { writeFacetContract } from "@0xfacet/sdk/viem";

const account = privateKeyToAccount("0xYourPrivateKey");
const client = createWalletClient({
  account,
  chain: mainnet,
  transport: http(),
});

// ERC-20 token transfer example
const hash = await writeFacetContract(client, {
  address: "0xTokenContractAddress",
  abi: [
    {
      name: "transfer",
      type: "function",
      inputs: [
        { name: "recipient", type: "address" },
        { name: "amount", type: "uint256" },
      ],
      outputs: [{ type: "bool" }],
    },
  ],
  functionName: "transfer",
  args: ["0xRecipientAddress", 1000000000000000000n], // 1 token with 18 decimals
  mineBoost: "0x02", // Optional: increase FCT mining amount
});

console.log("Contract transaction hash:", hash);

Bridge ETH and Call a Contract

import { createWalletClient, http, parseEther } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { mainnet } from "viem/chains";
import { bridgeAndCall } from "@0xfacet/sdk/viem";

const account = privateKeyToAccount("0xYourPrivateKey");
const client = createWalletClient({
  account,
  chain: mainnet,
  transport: http(),
});

// Bridge ETH and call a contract function
const hash = await bridgeAndCall(
  client,
  {
    address: "0xL2ContractAddress",
    abi: [
      {
        name: "purchaseWithBridgedETH",
        type: "function",
        inputs: [{ name: "tokenId", type: "uint256" }],
        outputs: [],
        stateMutability: "payable",
      },
    ],
    functionName: "purchaseWithBridgedETH",
    args: [123],
  },
  parseEther("0.1"), // ETH value to bridge
  {
    // Optional config
    maxFeePerGas: 20000000000n,
    maxPriorityFeePerGas: 2000000000n,
  }
);

console.log("Bridge and call transaction hash:", hash);

Using WAGMI Hooks

Send a Facet Transaction with WAGMI

import React from "react";
import { parseEther } from "viem";
import { useSendFacetTransaction } from "@0xfacet/sdk/wagmi";

function SendTransaction() {
  const { sendFacetTransactionAsync, data } = useSendFacetTransaction();

  const handleSend = async () => {
    try {
      // Using the async version
      const hash = await sendFacetTransactionAsync({
        to: "0xRecipientAddress",
        value: parseEther("0.01"),
        mineBoost: "0x01", // Optional: increase FCT mining amount
      });

      console.log("Transaction submitted:", hash);
    } catch (error) {
      console.error("Failed to send transaction:", error);
    }
  };

  return <button onClick={handleSend}>Send 0.01 FCT</button>;
}

Contract Write with WAGMI

import React from "react";
import { useWriteFacetContract } from "@0xfacet/sdk/wagmi";

const abi = [
  {
    name: "mint",
    type: "function",
    inputs: [
      { name: "to", type: "address" },
      { name: "tokenId", type: "uint256" },
    ],
    outputs: [],
    stateMutability: "nonpayable",
  },
];

function MintNFT() {
  const { writeFacetContractAsync } = useWriteFacetContract({
    abi,
    address: "0xNFTContractAddress",
    functionName: "mint",
  });

  const handleMint = async () => {
    try {
      await writeFacetContractAsync({
        args: ["0xYourAddress", 123n],
        mineBoost: "0x01", // Optional: increase FCT mining amount
      });
    } catch (error) {
      console.error("Mint failed:", error);
    }
  };

  return <button onClick={handleMint}>Mint NFT</button>;
}

Bridge ETH and Call Contract

import React from "react";
import { parseEther } from "viem";
import { useBridgeAndCall } from "@0xfacet/sdk/wagmi";

function BridgeAndMint() {
  const { bridgeAndCall } = useBridgeAndCall();

  const handleBridgeAndMint = () => {
    bridgeAndCall({
      address: "0xL2ContractAddress",
      abi: [
        {
          name: "mintWithBridgedETH",
          type: "function",
          inputs: [{ name: "tokenId", type: "uint256" }],
          outputs: [],
          stateMutability: "payable",
        },
      ],
      functionName: "mintWithBridgedETH",
      args: [123],
      ethValue: parseEther("0.1"), // Amount of ETH to bridge from L1 to L2
    });
  };

  return <button onClick={handleBridgeAndMint}>Bridge & Mint</button>;
}

Using Standard Methods

The SDK is fully compatible with standard viem and wagmi methods. Here are some examples:

Read Contract with viem

import { createPublicClient, http } from "viem";
import { facetMainnet } from "@0xfacet/sdk/viem";

const publicClient = createPublicClient({
  chain: facetMainnet,
  transport: http(),
});

// Standard viem readContract works normally
const balance = await publicClient.readContract({
  address: "0xTokenContract",
  abi: [
    {
      name: "balanceOf",
      type: "function",
      inputs: [{ name: "account", type: "address" }],
      outputs: [{ type: "uint256" }],
      stateMutability: "view",
    },
  ],
  functionName: "balanceOf",
  args: ["0xUserAddress"],
});

console.log("Balance:", balance);

Using wagmi's useReadContract

import React from "react";
import { useReadContract } from "wagmi";

function TokenBalance() {
  const { data: balance } = useReadContract({
    address: "0xTokenContract",
    abi: [
      {
        name: "balanceOf",
        type: "function",
        inputs: [{ name: "account", type: "address" }],
        outputs: [{ type: "uint256" }],
        stateMutability: "view",
      },
    ],
    functionName: "balanceOf",
    args: ["0xUserAddress"],
  });

  return <div>Balance: {balance?.toString() || "Loading..."}</div>;
}

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Commit your changes: git commit -m 'Add new feature'
4. Push to the branch: git push origin feature/my-feature
5. Submit a pull request

License

This project is licensed under the MIT License.