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 install @ethereum-tag-service/sdk-core viemIf your project already includes viem:
npm install @ethereum-tag-service/sdk-coreUsage
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: 84532 // Base Sepolia
})
// Client with MetaMask account
const tokenClientWithWallet = createTokenClient({
chainId: 84532,
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: 84532,
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: 84532,
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: 84532,
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";
// Base Sepolia
const chainId = 84532;
// Create a token client to read from Base 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
// @log: > trueSimple 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 Base Sepolia
const client = createRelayerClient({
chainId: 84532,
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));
// @log: >
// @log: Tagging record created: {
// @log: transactionHash: '0x0b36f4d57ff8f2ab6f82e6f1ffc7c9c02ecdc1c5ed8da68c09a79f31b9917e00',
// @log: status: 'success',
// @log: taggingRecordId: '80903853133999221435814377604232091751415136525898835875800777163543136099110'
// @log: }