clanker-sdk 1.8.0 → 3.1.1

package/README.md

@@ -1,277 +1,122 @@
-# Clanker SDK
+# Clanker SDK v3.1.0
 
-A lightweight TypeScript SDK for interacting with the Clanker API. Deploy tokens, manage splits, and track rewards with ease.
+A lightweight TypeScript SDK for deploying tokens using Clanker v3.1.0. This SDK provides a simple interface for deploying tokens with configurable market caps, vaulting, and reward distributions.
 
 ## Installation
 
 ```bash
-npm install clanker-sdk
+npm install clanker-sdk viem
 ```
 
-## Getting Started
-
-### 1. Request API Access
-Currently, API access is granted on a case-by-case basis to interested platforms. To request access, please contact:
-- Telegram: `btayengco`
-- Warpcast: `btayengco`
-
-We'll evaluate each request individually as we carefully scale our platform access.
-
-### 2. Environment Setup
-Create a `.env` file in your project root:
-
-```bash
-# Clanker API Key (required for token operations)
-CLANKER_API_KEY=your_api_key_here
-
-# Dune Analytics API Key (optional)
-DUNE_API_KEY=your_dune_api_key_here
-
-# The Graph API Key (optional)
-GRAPH_API_KEY=your_graph_api_key_here
-
-# CoinGecko Pro API Key (optional)
-COINGECKO_API_KEY=your_coingecko_api_key_here
-```
-
-Copy the `.env.example` file to get started:
-
-```bash
-cp .env.example .env
-```
-
-Make sure to add your API keys to the `.env` file and never commit it to version control.
-
-### 3. Getting Your API Keys
-
-#### Clanker API Key
-Contact `btayengco` on Telegram or Warpcast to request access.
-
-#### Dune Analytics API Key (Optional)
-To access market data features:
-1. Visit [dune.xyz](https://dune.xyz) and sign up for an account
-2. Go to your [API Keys page](https://dune.com/settings/api)
-3. Create a new API key
-4. Add the key to your `.env` file as `DUNE_API_KEY`
-
-Note: Dune API access requires a paid subscription. Check their [pricing page](https://dune.com/pricing) for more details.
-
-#### The Graph API Key (Optional)
-To access Uniswap data:
-1. Visit [thegraph.com](https://thegraph.com) and create an account
-2. Go to your billing settings
-3. Create an API key
-4. Add the key to your `.env` file as `GRAPH_API_KEY`
-
-#### CoinGecko Pro API Key (Optional)
-To access CoinGecko's comprehensive market data:
-1. Visit [CoinGecko](https://www.coingecko.com) and create an account
-2. Go to your [Developer Dashboard](https://www.coingecko.com/en/api/pricing)
-3. Choose a subscription plan and create an API key
-4. Add the key to your `.env` file as `COINGECKO_API_KEY`
-
-For detailed instructions on setting up your CoinGecko API key, visit their [official documentation](https://docs.coingecko.com/reference/setting-up-your-api-key).
-
-### 4. Basic Usage
+## Usage
 
 ```typescript
-import * as dotenv from 'dotenv';
-import { ClankerSDK, MarketDataClient } from 'clanker-sdk';
-
-// Load environment variables
-dotenv.config();
-
-// Initialize market data client (CoinGecko API key required for token prices)
-const marketData = new MarketDataClient(
-  process.env.DUNE_API_KEY,      // Optional: For Dune Analytics data
-  process.env.GRAPH_API_KEY,     // Optional: For Uniswap data
-  process.env.COINGECKO_API_KEY  // Required for token price lookups
-);
-
-// Example 1: Get price for your token on Base/Ethereum
-const tokenAddress = '0x1234567890123456789012345678901234567890'; // Your token address
-
-// Direct CoinGecko API usage
-const url = 'https://pro-api.coingecko.com/api/v3/simple/token_price/id';
-const options = {
-  method: 'GET',
-  headers: {
-    'accept': 'application/json',
-    'x-cg-pro-api-key': process.env.COINGECKO_API_KEY
-  }
-};
-
-// You can use the API directly
-fetch(url, options)
-  .then(res => res.json())
-  .then(json => console.log('Token price:', json))
-  .catch(err => console.error('Error:', err));
-
-// Or use our SDK wrapper for easier handling
-const tokenPrices = await marketData.getGeckoTokenPrice({
-  'ethereum': [tokenAddress]  // For tokens on Base/Ethereum
+import { createWalletClient, http } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { base } from 'viem/chains';
+import { Clanker } from 'clanker-sdk';
+
+// Initialize wallet
+const account = privateKeyToAccount('0x...');
+const wallet = createWalletClient({
+  account,
+  chain: base,
+  transport: http()
 });
-console.log('Token prices:', tokenPrices);
-
-// Example 2: Other SDK features (optional)
-const clanker = new ClankerSDK(process.env.CLANKER_API_KEY);
 
-// Deploy a token
-const token = await clanker.deployToken({
-  name: "Community Token",
-  symbol: "CMTY",
-  image: "https://example.com/token.png",
-  requestorAddress: "0x1234567890123456789012345678901234567890"
+// Initialize Clanker SDK
+const clanker = new Clanker({
+  wallet,
+  factoryAddress: '0x2A787b2362021cC3eEa3C24C4748a6cD5B687382', // Clanker factory address on Base
+  chainId: base.id
 });
 
-// Get additional market data
-const additionalData = await Promise.all([
-  marketData.getClankerDictionary(),
-  marketData.getDexPairStats('ethereum', token.contractAddress),
-  marketData.getUniswapData([token.contractAddress])
-]);
-```
-
-## Features
-
-- 🚀 Token Deployment
-- 💰 Split Management
-- 📊 Rewards Tracking
-- 🔒 Type-safe API
-- 📝 Full TypeScript Support
-- 📈 Market Data Analytics
-
-## Market Data Features
-
-The SDK provides access to comprehensive market data through multiple sources:
-
-### Clanker Top Performers View
-Access our curated list of top-performing Clanker tokens using our materialized view:
-
-```sql
--- Query our materialized view for top Clankers on Base & Farcaster
--- Filtered for high-quality tokens meeting these criteria:
--- - Market Cap > $100,000
--- - 24hr Volume > $10,000
--- - 3-day Volume > $50,000
-SELECT *
-FROM dune.clanker_protection_team.result_clnkr_100_k_mkt_share_2_0
-```
-
-This view provides real-time insights into the best-performing tokens deployed through Clanker on Base & Farcaster.
-
-### CoinGecko Market Data
-Get token prices by contract address on Base/Ethereum:
-
-```typescript
-// Example 1: Get price for your token (RECOMMENDED)
-const tokenAddress = '0x1234567890123456789012345678901234567890'; // Your token address
-
-// The SDK uses this CoinGecko endpoint under the hood:
-// GET https://pro-api.coingecko.com/api/v3/simple/token_price/id
-// You can also use it directly:
-const url = 'https://pro-api.coingecko.com/api/v3/simple/token_price/id';
-const options = {
-  method: 'GET',
-  headers: {
-    'accept': 'application/json',
-    'x-cg-pro-api-key': process.env.COINGECKO_API_KEY
+// Deploy a token
+const tokenAddress = await clanker.deploy({
+  tokenConfig: {
+    name: 'My Token',
+    symbol: 'MTK',
+    salt: '0x...', // bytes32 for address customization
+    image: 'ipfs://...',
+    metadata: 'ipfs://...',
+    context: 'Deployed via SDK',
+    originatingChainId: BigInt(base.id)
+  },
+  poolConfig: {
+    pairedToken: '0x4200000000000000000000000000000000000006', // WETH on Base
+    initialMarketCapInPairedToken: BigInt(10) * BigInt(10)**BigInt(18) // 10 WETH initial mcap
+  },
+  // Optional: Lock tokens in vault
+  vaultConfig: {
+    vaultPercentage: 30, // 30% of supply
+    vaultDuration: BigInt(30 * 24 * 60 * 60) // 30 days in seconds
+  },
+  // Optional: Perform initial buy with ETH
+  initialBuyConfig: {
+    pairedTokenPoolFee: 3000, // 0.3% fee tier for ETH -> pairedToken swap
+    pairedTokenSwapAmountOutMinimum: BigInt('1000000000000000000') // 1 ETH
+  },
+  rewardsConfig: {
+    creatorReward: BigInt(80), // 80% of remaining rewards (after 20% team cut)
+    creatorAdmin: '0x...', // Address to manage creator's locked tokens
+    creatorRewardRecipient: '0x...', // Address to receive creator's trading fees
+    interfaceAdmin: '0x...', // Address to manage interface's trading fees
+    interfaceRewardRecipient: '0x...' // Address to receive interface's trading fees
   }
-};
-
-// Direct API usage
-fetch(url, options)
-  .then(res => res.json())
-  .then(json => console.log(json))
-  .catch(err => console.error(err));
-
-// Or use our SDK wrapper (handles authentication and error handling)
-const tokenPrices = await marketData.getGeckoTokenPrice({
-  'ethereum': [tokenAddress]  // For tokens on Base/Ethereum
 });
-```
 
-This endpoint is specifically designed for getting token prices on Base/Ethereum. For other data sources or chains, see below.
-
-### Clanker Dictionary
-Get detailed information about all Clanker tokens:
-```typescript
-const dictionary = await marketData.getClankerDictionary();
-// Returns: Array of tokens with market cap, volume, and liquidity data
+console.log('Token deployed at:', tokenAddress);
 ```
 
-### DEX Pair Statistics
-Get detailed DEX pair statistics for any token:
-```typescript
-const dexStats = await marketData.getDexPairStats(
-  'ethereum',  // Chain name (ethereum, arbitrum, etc.)
-  '0x1234...'  // Optional: Token address to filter by
-);
-// Returns: Detailed DEX pair statistics including:
-// - Trading volumes (24h, 7d, 30d)
-// - Liquidity
-// - Volume/Liquidity ratios
-```
+## Features
 
-### Uniswap Data
-Get detailed Uniswap pool data for tokens (requires Graph API key):
-```typescript
-const uniswapData = await marketData.getUniswapData(
-  ['0x1234...', '0x5678...'],  // Array of token addresses
-  15_000_000  // Optional: Block number for historical data
-);
-// Returns: Array of tokens with:
-// - WETH price
-// - Transaction count
-// - Volume in USD
-// - Decimals
-```
+- Deploy tokens with customizable parameters
+- Calculate initial token price based on desired market cap in paired token
+- Support for token vaulting with configurable duration and percentage
+- Configure reward distribution between creator and interface
+- Support for initial token buys with ETH
+- Super-chain compatibility for cross-chain deployments
 
-Supported chains for DEX stats:
-- ethereum
-- arbitrum
-- base
-- bnb
-- celo
-- fantom
-- gnosis
-- optimism
-- polygon
-- scroll
-- zk_sync
-- solana
+## Configuration
 
-## Examples
+### TokenConfig
+- `name`: Token name
+- `symbol`: Token symbol
+- `salt`: Address salt value for token address customization
+- `image`: Token image URI
+- `metadata`: Token metadata URI
+- `context`: Additional deployment context
+- `originatingChainId`: Chain ID where token supply is deployed
 
-Check out the `examples/` directory for more usage examples:
+### PoolConfig
+- `pairedToken`: Token to pair with (e.g., WETH)
+- `initialMarketCapInPairedToken`: Desired initial market cap in paired token units
 
-- Token Deployment (`examples/token-deployment.ts`)
-- Rewards and Fees (`examples/rewards-and-fees.ts`)
-- Market Data (`examples/market-data.ts`)
+### VaultConfig (Optional)
+- `vaultPercentage`: Percentage of supply to lock (max 30)
+- `vaultDuration`: Lock duration in seconds (min 30 days)
 
-Run examples using:
+### InitialBuyConfig (Optional)
+- `pairedTokenPoolFee`: Fee tier for ETH -> pairedToken swap
+- `pairedTokenSwapAmountOutMinimum`: Minimum amount of paired tokens to receive
 
-```bash
-npm run example:deploy    # Run token deployment example
-npm run example:rewards   # Run rewards tracking example
-npm run example:market   # Run market data example
-npm run example          # Run all examples
-```
+### RewardsConfig
+- `creatorReward`: Creator's percentage of remaining rewards after team cut (max 80)
+- `creatorAdmin`: Address to manage creator's locked tokens
+- `creatorRewardRecipient`: Address to receive creator's trading fees
+- `interfaceAdmin`: Address to manage interface's trading fees
+- `interfaceRewardRecipient`: Address to receive interface's trading fees
 
-## Development
+## Super-chain Compatibility
 
-```bash
-npm install        # Install dependencies
-npm run build     # Build the SDK
-npm test          # Run tests
-npm run lint      # Run linter
-npm run format    # Format code
-```
+The SDK supports deploying tokens that are compatible with the super-chain architecture. When deploying a token:
 
-## Contributing
+1. Set `originatingChainId` to the chain ID where the token's supply should be minted
+2. Deploy the token on other super-chain networks using the same parameters
+3. Use the super-chain's bridge to migrate tokens between networks
 
-Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) for details.
+Note: Tokens can only be minted with supply on the originating chain. Make sure the target chains are part of the same super-chain cluster.
 
 ## License
 
-ISC © Clanker Team
+MIT

package/dist/index.d.mts

@@ -1,143 +1,56 @@
-interface Token {
-    chainId: number;
-    address: string;
-    symbol: string;
-    decimals: number;
-    name: string;
-}
-interface DeployTokenOptions {
+import { Address, WalletClient, Account } from 'viem';
+
+interface TokenConfig {
     name: string;
     symbol: string;
+    salt: `0x${string}`;
     image: string;
-    requestorAddress: string;
-    requestKey?: string;
-}
-interface DeployTokenWithSplitsOptions extends DeployTokenOptions {
-    splitAddress: string;
-}
-interface UncollectedFeesResponse {
-    lockerAddress: string;
-    lpNftId: number;
-    token0UncollectedRewards: string;
-    token1UncollectedRewards: string;
-    token0: Token;
-    token1: Token;
-}
-interface DeployedToken {
-    id: number;
-    created_at: string;
-    tx_hash: string;
-    requestor_fid: number;
-    contract_address: string;
-    name: string;
-    symbol: string;
-    img_url: string | null;
-    pool_address: string;
-    cast_hash: string;
-    type: string;
-    pair: string;
-}
-interface DeployedTokensResponse {
-    data: DeployedToken[];
-    hasMore: boolean;
-    total: number;
-}
-interface EstimatedRewardsResponse {
-    userRewards: number;
-}
-declare class ClankerError extends Error {
-    readonly code?: string | undefined;
-    readonly status?: number | undefined;
-    readonly details?: any | undefined;
-    constructor(message: string, code?: string | undefined, status?: number | undefined, details?: any | undefined);
-}
-
-declare class ClankerSDK {
-    private readonly api;
-    private readonly baseURL;
-    constructor(apiKey: string);
-    getEstimatedUncollectedFees(contractAddress: string): Promise<UncollectedFeesResponse>;
-    deployToken(options: DeployTokenOptions): Promise<DeployedToken>;
-    deployTokenWithSplits(options: DeployTokenWithSplitsOptions): Promise<DeployedToken>;
-    fetchDeployedByAddress(address: string, page?: number): Promise<DeployedTokensResponse>;
-    getEstimatedRewardsByPoolAddress(poolAddress: string): Promise<EstimatedRewardsResponse>;
-    getClankerByAddress(address: string): Promise<DeployedToken>;
-    private generateRequestKey;
-    private isValidAddress;
-    private validateDeployOptions;
+    metadata: string;
+    context: string;
+    originatingChainId: bigint;
+}
+interface VaultConfig {
+    vaultPercentage: number;
+    vaultDuration: bigint;
+}
+interface PoolConfig {
+    pairedToken: Address;
+    initialMarketCapInPairedToken: bigint;
+}
+interface InitialBuyConfig {
+    pairedTokenPoolFee: number;
+    pairedTokenSwapAmountOutMinimum: bigint;
+}
+interface RewardsConfig {
+    creatorReward: bigint;
+    creatorAdmin: Address;
+    creatorRewardRecipient: Address;
+    interfaceAdmin: Address;
+    interfaceRewardRecipient: Address;
+}
+interface DeploymentConfig {
+    tokenConfig: TokenConfig;
+    vaultConfig?: VaultConfig;
+    poolConfig: PoolConfig;
+    initialBuyConfig?: InitialBuyConfig;
+    rewardsConfig: RewardsConfig;
+}
+interface ClankerConfig {
+    wallet: WalletClient & {
+        account: Account;
+    };
+    factoryAddress: Address;
+    chainId: number;
 }
 
-interface ClankerMarketData {
-    name: string;
-    symbol: string;
-    marketCap?: number;
-    volume24h?: number;
-    volume7d?: number;
-    liquidity?: number;
-}
-interface DexPairStats {
-    token_a_address: string;
-    token_a_symbol: string;
-    token_b_address: string;
-    token_b_symbol: string;
-    volume_24h: number;
-    volume_7d: number;
-    volume_30d: number;
-    liquidity: number;
-    volume_to_liquidity_ratio: number;
-}
-interface GraphToken {
-    contractAddress: string;
-    decimals: number;
-    transactionCount: number;
-    volumeUSD: number;
-    priceWETH: number;
-}
-interface CoinGeckoTokenData {
-    price: number;
-    marketCap: number;
-    volume24h: number;
-    priceChange24h: number;
-    lastUpdated: Date;
-}
-declare class MarketDataClient {
-    private readonly dune?;
-    private readonly duneApiKey?;
-    private readonly graphApiKey?;
-    private readonly geckoApiKey?;
-    private readonly DICTIONARY_QUERY_ID;
-    private readonly GRAPH_API_ENDPOINT;
-    private readonly UNISWAP_SUBGRAPH_ID;
-    private readonly COINGECKO_API_ENDPOINT;
-    constructor(duneApiKey?: string, graphApiKey?: string, geckoApiKey?: string);
-    /**
-     * Get market data from CoinGecko (requires CoinGecko API key)
-     * @param tokenIds Array of CoinGecko token IDs
-     */
-    getGeckoTokenData(tokenIds: string[]): Promise<Record<string, CoinGeckoTokenData>>;
-    /**
-     * Get market data from the materialized view (requires Dune API key)
-     */
-    getClankerDictionary(): Promise<ClankerMarketData[]>;
-    /**
-     * Get DEX pair stats for a specific chain (requires Dune API key)
-     * @param chain - The blockchain to query (e.g., 'ethereum', 'arbitrum', etc.)
-     * @param tokenAddress - Optional token address to filter by
-     */
-    getDexPairStats(chain: string, tokenAddress?: string): Promise<DexPairStats[]>;
-    /**
-     * Fetch Uniswap data for multiple tokens using The Graph (requires Graph API key)
-     * @param contractAddresses Array of token contract addresses
-     * @param blockNumber Optional block number for historical data
-     */
-    getUniswapData(contractAddresses: string[], blockNumber?: number): Promise<GraphToken[]>;
-    /**
-     * Filter DEX pairs by token address
-     */
-    private filterPairsByToken;
-    private buildUniswapQuery;
-    private transformUniswapData;
-    private calculatePrice;
+declare class Clanker {
+    private readonly wallet;
+    private readonly factoryAddress;
+    private readonly chainId;
+    private readonly publicClient;
+    constructor(config: ClankerConfig);
+    private calculateTick;
+    deploy(config: DeploymentConfig): Promise<Address>;
 }
 
-export { ClankerError, type ClankerMarketData, ClankerSDK, type CoinGeckoTokenData, type DeployTokenOptions, type DeployTokenWithSplitsOptions, type DeployedToken, type DeployedTokensResponse, type DexPairStats, type EstimatedRewardsResponse, type GraphToken, MarketDataClient, type Token, type UncollectedFeesResponse, ClankerSDK as default };
+export { Clanker, type ClankerConfig, type DeploymentConfig, type InitialBuyConfig, type PoolConfig, type RewardsConfig, type TokenConfig, type VaultConfig };