ERC6551 Token Bound Accounts (TBA)

This project implements the ERC6551 standard for token bound accounts, allowing NFTs to own and control their own smart contract accounts.

中文版文档

Features

• ERC6551Registry: Contract for creating and tracking token bound accounts
• ERC6551Account: Implementation of a token bound account that can be controlled by the NFT owner
• IPNFT: Sample NFT contract for intellectual property tokens

Package Versions

The project provides a framework-agnostic npm package for integration:

• gotake-contracts: Pure TypeScript types and ABIs - works with any framework

Installing the Package

# Framework-agnostic package (recommended)
npm install gotake-contracts

Using the Package

The package provides pure TypeScript types and ABIs without any runtime dependencies:

// Import ABIs
import { ERC6551REGISTRY_ABI, IPNFT_ABI, abis } from 'gotake-contracts';

// Import TypeScript types
import { NetworkConfig, ContractABI } from 'gotake-contracts';

// Import contract addresses and helper functions
import { CONTRACT_ADDRESSES, getContractAddress } from 'gotake-contracts';

// Example usage
const registryAddress = getContractAddress('base_sepolia', 'registry');
const networkConfig = CONTRACT_ADDRESSES.base_sepolia;

Building the Package

# Build the framework-agnostic package
yarn build

Key Features

• Zero Dependencies: No runtime dependencies, works with any ethers version
• Framework Agnostic: Compatible with browser, Node.js, React, Vue, etc.
• TypeScript Support: Full type safety with generated interfaces
• Static Assets: Contract addresses compiled as TypeScript constants

Setup

1. Clone this repository
2. Install dependencies:

   yarn install

3. Copy .env.example to .env and fill in your values:

   cp .env.example .env

4. Edit the .env file to add your private key and RPC URLs

Deployment

Deploying to Base Sepolia Testnet

Run the following command to deploy all contracts to Base Sepolia Testnet:

npx hardhat run scripts/deploy.ts --network base_sepolia

This will deploy:

• ERC6551Registry
• ERC6551Account implementation
• IPNFT contract
• Creates a sample Token Bound Account for demonstration

Verifying Contracts

After deployment, you can verify the contracts on BaseScan using our verification script:

# Verify all contracts on current network
npx hardhat run scripts/verify-contracts.ts --network base_sepolia

# Verify a specific contract on a specific network
npx hardhat run scripts/verify-contracts.ts --network base_sepolia --contract registry
npx hardhat run scripts/verify-contracts.ts --network base_sepolia --contract accountImplementation
npx hardhat run scripts/verify-contracts.ts --network base_sepolia --contract ipnft

Or manually:

npx hardhat verify --network base_sepolia <CONTRACT_ADDRESS> [CONSTRUCTOR_ARGUMENTS]

Example for IPNFT:

npx hardhat verify --network base_sepolia <IPNFT_ADDRESS> <OWNER_ADDRESS>

Batch Deployment (Recommended)

For production deployments, use the batch deployment tool to deploy multiple contracts efficiently:

# Deploy all contracts to Base mainnet
npm run batch-deploy -- deploy --networks base

# Deploy specific contracts
npm run batch-deploy -- deploy --networks base --contracts SSG,VideoPayment

# Deploy to multiple networks
npm run batch-deploy -- deploy --networks base,base_sepolia

# Preview deployment plan (dry run)
npm run batch-deploy -- deploy --networks base --dry-run

The batch deployment tool automatically:

• Deploys contracts efficiently
• Verifies contracts on block explorers
• Updates contract addresses in contracts-addresses.json
• Provides detailed deployment reports

For detailed usage instructions, see Batch Deployment Guide.

Testing

Local Testing

Run the tests locally:

npx hardhat test

Testing with Deployed Contracts

Use the test-tba.ts script to interact with your deployed contracts:

# Test on hardhat network (will deploy fresh contracts)
npx hardhat run scripts/test-tba.ts

# Test on Base Sepolia with deployed contracts
npx hardhat run scripts/test-tba.ts --network base_sepolia

This script will:

1. Connect to the contracts using the compiled address constants
2. Auto-mint an NFT if none exist on the contract
3. Check NFT ownership and metadata
4. Calculate and create a Token Bound Account if needed
5. Verify token association
6. Send ETH to the TBA if balance is low
7. Execute a transaction from the TBA (requires the signer to be the NFT owner)

Before running on Base Sepolia, make sure:

• Your wallet has Base Sepolia ETH
• Your private key in .env has the necessary permissions
• The script will automatically mint an NFT if none exist

Usage

Creating a Token Bound Account

1. Mint an NFT using the IPNFT contract
2. Call the createAccount function on the registry contract:

// Example parameters
const implementation = "<ACCOUNT_IMPLEMENTATION_ADDRESS>";
const salt = ethers.utils.formatBytes32String("SALT");
const chainId = 84532; // Base Sepolia
const tokenContract = "<IPNFT_ADDRESS>";
const tokenId = 0; // The NFT ID

// Create the account
await registry.createAccount(
    implementation,
    salt,
    chainId,
    tokenContract,
    tokenId
);

Interacting with a Token Bound Account

1. Get the account address using the registry's account function
2. Connect to the account using the ERC6551Account ABI
3. Call functions on the account using the NFT owner's address

// Get the account address
const accountAddress = await registry.account(
    implementation,
    salt,
    chainId,
    tokenContract,
    tokenId
);

// Connect to the account
const account = await ethers.getContractAt("ERC6551Account", accountAddress);

// Execute a transaction from the account (must be called by the NFT owner)
await account.execute(
    targetAddress,  // The address to interact with
    value,          // Amount of ETH to send
    data,           // The calldata for the transaction
    operation       // 0 for call, 1 for delegatecall
);

Running SDK Example Scripts

The SDK provides several example scripts to demonstrate how to work with IPNFT and TBA functionality. These scripts are located in the gotake-sdk/scripts directory.

Prerequisites

1. Install dependencies in the SDK directory:

   cd gotake-sdk
   yarn install

2. Create an environment file:

   # In the gotake-sdk directory
   cp .env.example .env

3. Edit the .env file to add your Ethereum private key:

   PRIVATE_KEY=your_private_key_here

Example Scripts

1. Creating a TBA

The create-tba.ts script demonstrates:

• Creating an SDK instance
• Minting an IPNFT
• Creating a TBA linked to the IPNFT

Run with:

# In the gotake-sdk directory
npx ts-node --transpile-only scripts/create-tba.ts

After successful execution, copy the TBA address to the .env file's TBA_ADDRESS field for use in subsequent scripts.

2. Sending ETH to a TBA

The send-eth-to-tba.ts script demonstrates:

• Sending ETH to a TBA
• Executing transactions from the TBA (sending ETH back to the original account)

Run with:

# In the gotake-sdk directory
npx ts-node --transpile-only scripts/send-eth-to-tba.ts

3. Checking TBA Information

The check-tba.ts script demonstrates:

• Querying a TBA's balance
• Getting the Token information associated with a TBA
• Getting the TBA owner
• Getting detailed information about the associated IPNFT

Run with:

# In the gotake-sdk directory
npx ts-node --transpile-only scripts/check-tba.ts

Recommended Execution Order

1. First run create-tba.ts to create a TBA
2. Then run check-tba.ts to confirm the TBA was created successfully and check its information
3. Finally run send-eth-to-tba.ts to demonstrate interaction with the TBA

Troubleshooting

If scripts fail, check:

1. Your private key is correct
2. Your account has sufficient test ETH
3. Network connection is stable
4. TBA address is correct (for second and third scripts)

Package Architecture

This project generates a framework-agnostic npm package with zero runtime dependencies.

Package Features

• Pure Static Exports: Only TypeScript types, ABIs, and contract addresses
• Environment Universal: Works in browser, Node.js, React Native, etc.
• Framework Agnostic: Compatible with any ethers version (v5, v6) or Web3 library
• Frontend Safe: No Node.js dependencies, can be bundled for browsers
• TypeScript First: Full type safety with generated interfaces

Development Workflow

The development environment uses ethers v5 for consistency, while the published package remains framework-agnostic:

# Development commands
yarn compile                 # Compile contracts
yarn typechain              # Generate TypeChain types
yarn build                  # Build the framework-agnostic package

Package Structure

gotake-contracts/
├── abi/                    # Pure JSON ABI files
├── types/                  # Framework-agnostic TypeScript interfaces
├── constants/              # Contract addresses as TypeScript constants
└── index.js               # Main export with all types and ABIs

Integration Examples

// React + ethers v6
import { ERC6551REGISTRY_ABI, CONTRACT_ADDRESSES } from 'gotake-contracts';
import { ethers } from 'ethers';

const contract = new ethers.Contract(
  CONTRACT_ADDRESSES.base_sepolia.contracts.registry,
  ERC6551REGISTRY_ABI,
  provider
);

// Node.js + ethers v5
import { IPNFT_ABI, getContractAddress } from 'gotake-contracts';
const address = getContractAddress('base_sepolia', 'ipnft');

// Vue + Web3.js
import { abis } from 'gotake-contracts';
const web3Contract = new web3.eth.Contract(abis.ERC6551Registry, address);

License

This project is licensed under the MIT License.