Getting started

Installation

ETS SDK Core uses the popular viem library as its Ethereum interface. Viem is specified as a peer dependency, meaning you'll need to have it installed in your project to use the SDK.

If you're starting a new project:

npm

npm install @ethereum-tag-service/sdk-core viem

If your project already includes viem:

npm

npm install @ethereum-tag-service/sdk-core

Usage

Client initialization

All sdk-core clients require a chainId parameter and optionally an account parameter. The account parameter can be provided in one of two forms depending on your use case:

A hex address (type Hex) obtained from a third-party wallet like MetaMask via your wallet connector. See viem JSON-RPC Account for more information:

import { createTokenClient } from '@ethereum-tag-service/sdk-core'
 
// Read-only client without account
const tokenClient = createTokenClient({
  chainId: 421614 // Arbitrum Sepolia 
})
 
// Client with MetaMask account
const tokenClientWithWallet = createTokenClient({
  chainId: 421614,
  account: '0x...' // Hex address from MetaMask 
})

A viem local account:

import { createTokenClient } from '@ethereum-tag-service/sdk-core'
import { privateKeyToAccount } from 'viem/accounts'
 
// Create viem account
const account = privateKeyToAccount('0x...')
 
// Client with private key account
const tokenClient = createTokenClient({
  chainId: 421614,
  account // viem account object 
})

Relayer Client

The Relayer Client additionally requires a relayerAddress parameter:

import { createRelayerClient } from '@ethereum-tag-service/sdk-core'
 
const relayerClient = createRelayerClient({
  chainId: 421614,
  relayerAddress: '0x...', // Any relayer address 
  account: '0x...' // Optional account parameter
})

Learn more about Relayers.

Core client

The Core Client (createCoreClient) provides direct access to all methods from the initialized clients. You don't need to destructure the individual clients. You can call methods directly on the CoreClient instance.

import { createCoreClient } from '@ethereum-tag-service/sdk-core'
 
const coreClient = createCoreClient({
  chainId: 421614,
  relayerAddress: '0x...',
  account: '0x...',
  clients: {
    tokenClient: true,
    relayerClient: true,
    auctionHouseClient: true
  }
})
 
// Direct method access
await coreClient?.tagExists('#rainbow')
await coreClient?.applyTags(['#rainbow'], 'https://example.com', 'Demo')
await coreClient?.getAuction(1n)

Available clients

The SDK provides the following client initialization methods:

createTokenClient
createAccessControlsClient
createAuctionHouseClient
createRelayerFactoryClient
createTargetClient
createEnrichTargetClient
createEtsClient
createRelayerClient
createCoreClient

Examples

Once you have a client initialized, you can use it to interact directly with the ETS protocol smart contracts.

Simple read contract example

Implement the tagExistsByString method in the TokenClient to check if a CTAG exists.

import { createTokenClient } from "@ethereum-tag-service/sdk-core";
 
// Arbitrum Sepolia
const chainId = 421614;
 
// Create a token client to read from Arbitrum Sepolia.
const client = createTokenClient({ chainId });
 
// See if tag #rainbow exists on ETS.
const tag = "#rainbow";
const tagExists = await client?.tagExistsByString(tag);
 
console.log(tagExists); // true or false
 
> true

Simple create tagging record

Implement the createTaggingRecord method in the RelayerClient to create a tagging record on ETS.

 
import { createRelayerClient } from "@ethereum-tag-service/sdk-core";
 
// Initialize RelayerClient on Arbitrum Sepolia
const client = createRelayerClient({
  chainId: 421614,
  relayerAddress: "0xa01c9cb373c5e29934b92e5afa6a78e3d590340b",
  account: '0x...' // Hex address from MetaMask or other signing wallet.
});
 
// Create a Tagging Record
client?.createTaggingRecord(
  ["#rainbow", "#unicorn", "#og", "#uniswap"],
  "https://uniswap.org",
  "Demo"
)
.then((result) => console.log("Tagging record created:", result))
.catch((error) => console.error("Error creating tagging record:", error));
 
>
 Tagging record created: {
   transactionHash: '0x0b36f4d57ff8f2ab6f82e6f1ffc7c9c02ecdc1c5ed8da68c09a79f31b9917e00',
   status: 'success',
   taggingRecordId: '80903853133999221435814377604232091751415136525898835875800777163543136099110'
 }