liquid-sdk 1.2.0 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/AGENT_README.md +770 -0
  2. package/CHANGELOG.md +60 -0
  3. package/dist/index.d.mts +95 -1
  4. package/dist/index.d.ts +95 -1
  5. package/dist/index.js +149 -11
  6. package/dist/index.js.map +1 -1
  7. package/dist/index.mjs +144 -10
  8. package/dist/index.mjs.map +1 -1
  9. package/llms.txt +154 -0
  10. package/package.json +22 -4
package/llms.txt ADDED
@@ -0,0 +1,154 @@
1
+ # liquid-sdk
2
+
3
+ > TypeScript SDK to deploy ERC-20 tokens with Uniswap V4 liquidity on Base — zero API keys, one dependency (viem)
4
+
5
+ ## Install
6
+
7
+ ```
8
+ npm install liquid-sdk viem
9
+ ```
10
+
11
+ ## Quick Start
12
+
13
+ ```typescript
14
+ import { createPublicClient, createWalletClient, http } from "viem";
15
+ import { base } from "viem/chains";
16
+ import { privateKeyToAccount } from "viem/accounts";
17
+ import { LiquidSDK } from "liquid-sdk";
18
+
19
+ const publicClient = createPublicClient({ chain: base, transport: http() });
20
+ const account = privateKeyToAccount("0x...");
21
+ const walletClient = createWalletClient({ account, chain: base, transport: http() });
22
+ const sdk = new LiquidSDK({ publicClient, walletClient });
23
+
24
+ const result = await sdk.deployToken({ name: "My Token", symbol: "MTK" });
25
+ console.log(result.tokenAddress);
26
+ ```
27
+
28
+ ## What It Does
29
+
30
+ Liquid Protocol deploys ERC-20 tokens on Base (chain 8453) with:
31
+ - Uniswap V4 liquidity pools (created automatically)
32
+ - Locked LP with configurable reward splits
33
+ - MEV protection (sniper auction or block delay)
34
+ - Optional extensions: dev buy, vault lockup/vesting, merkle airdrops
35
+
36
+ Every token gets 100 billion supply (18 decimals), a Uniswap V4 pool, and locked liquidity.
37
+
38
+ ## API Methods
39
+
40
+ ### Token Deployment
41
+ - `sdk.deployToken(params)` — Deploy ERC-20 + Uniswap V4 pool. Params: name (required), symbol (required), image, metadata, context, devBuy, hook, tickSpacing, poolData, rewardRecipients, rewardBps, extensions
42
+ - `sdk.buildDevBuyExtension(devBuy)` — Build extension config for buying tokens at launch
43
+
44
+ ### Fee Management
45
+ - `sdk.getAvailableFees(feeOwner, tokenAddress)` — Total unlocked fees (bigint)
46
+ - `sdk.getFeesToClaim(feeOwner, tokenAddress)` — Claimable fees right now (bigint)
47
+ - `sdk.claimFees(feeOwner, tokenAddress)` — Claim fees (returns txHash)
48
+
49
+ ### LP Reward Management
50
+ - `sdk.getTokenRewards(tokenAddress)` — Reward config (recipients, bps, admins, poolKey)
51
+ - `sdk.collectRewards(tokenAddress)` — Collect + unlock LP (returns txHash)
52
+ - `sdk.collectRewardsWithoutUnlock(tokenAddress)` — Collect fees only (returns txHash)
53
+ - `sdk.updateRewardRecipient(tokenAddress, index, newRecipient)` — Change recipient (returns txHash)
54
+
55
+ ### Vault (Token Lockup & Vesting)
56
+ - `sdk.getVaultAllocation(tokenAddress)` — Vault state (total, claimed, lockup/vesting times, admin)
57
+ - `sdk.getVaultClaimable(tokenAddress)` — Tokens available to claim now (bigint)
58
+ - `sdk.claimVault(tokenAddress)` — Claim vested tokens (returns txHash)
59
+
60
+ ### Airdrop
61
+ - `sdk.getAirdropInfo(tokenAddress)` — Airdrop state (merkle root, supply, claimed, times)
62
+ - `sdk.getAirdropClaimable(tokenAddress, recipient, amount)` — Claimable for recipient (bigint)
63
+ - `sdk.claimAirdrop(tokenAddress, recipient, amount, proof)` — Claim airdrop (returns txHash)
64
+
65
+ ### Token Info & Discovery
66
+ - `sdk.getTokenInfo(tokenAddress)` — Name, symbol, decimals, totalSupply, deployment addresses
67
+ - `sdk.getDeploymentInfo(tokenAddress)` — Token, hook, locker, extensions addresses
68
+ - `sdk.getTokens(options?)` — Query all deployed tokens with optional deployer filter and block range pagination. Returns full event data + blockNumber
69
+ - `sdk.getTokenEvent(tokenAddress)` — Look up single token's on-chain event data by address (indexed, single RPC call). Returns metadata, context, poolId, hook, extensions
70
+ - `sdk.getDeployedTokens(deployer, fromBlock?, toBlock?)` — Convenience wrapper for getTokens({ deployer })
71
+
72
+ ### Token Metadata Updates
73
+ - `sdk.updateImage(tokenAddress, newImageUrl)` — Update token image (admin only)
74
+ - `sdk.updateMetadata(tokenAddress, newMetadata)` — Update token metadata (admin only)
75
+
76
+ ### Pool Reads
77
+ - `sdk.getPoolConfig(poolId)` — Dynamic fee configuration
78
+ - `sdk.getPoolFeeState(poolId)` — Current fee state
79
+ - `sdk.getPoolCreationTimestamp(poolId)` — Pool creation time
80
+ - `sdk.isLiquidToken0(poolId)` — Token sort order in pool
81
+
82
+ ### Sniper Auction (MEV)
83
+ - `sdk.getAuctionState(poolId)` — Current auction state (block, round, gasPeg, fee)
84
+ - `sdk.getAuctionFeeConfig(poolId)` — Fee parameters (starting, ending, decay)
85
+ - `sdk.getAuctionDecayStartTime(poolId)` — When fee decay started
86
+ - `sdk.getAuctionMaxRounds()` — Max auction rounds
87
+ - `sdk.getAuctionGasPriceForBid(gasPeg, bidAmount)` — Calculate gas price for bid
88
+
89
+ ### MEV Protection
90
+ - `sdk.getMevBlockDelay()` — Configured block delay
91
+ - `sdk.getPoolUnlockTime(poolId)` — When MEV lock expires (unix timestamp)
92
+
93
+ ### Factory & Allowlist
94
+ - `sdk.isFactoryDeprecated()` — Is factory still active
95
+ - `sdk.isLockerEnabled(locker, hook)` — Is locker approved for hook
96
+ - `sdk.isExtensionEnabled(extension)` — Is extension on allowlist
97
+
98
+ ### Context & Metadata Helpers
99
+ - `buildContext({ interface?, platform?, messageId?, id? })` — Build JSON context string
100
+ - `buildMetadata({ description?, socialMediaUrls?, auditUrls? })` — Build JSON metadata string
101
+ - `parseContext(contextString)` — Parse context JSON to typed object
102
+ - `parseMetadata(metadataString)` — Parse metadata JSON to typed object
103
+
104
+ ## Utility Functions
105
+
106
+ - `encodeStaticFeePoolData(liquidFeeBps, pairedFeeBps)` — Encode static fee config
107
+ - `encodeDynamicFeePoolData(config)` — Encode dynamic fee config
108
+ - `encodeSniperAuctionData(config)` — Encode MEV auction config
109
+ - `createPositions(startingCapETH, tranches)` — Build position arrays from ETH market caps
110
+ - `createPositionsUSD(startingCapUSD, ethPrice, tranches)` — Build from USD market caps
111
+ - `createDefaultPositions(startingCapUSD, ethPrice)` — Default 3-tranche (40%@$500K, 50%@$10M, 10%@$1B)
112
+ - `describePositions(positions, ethPrice?)` — Human-readable position descriptions
113
+ - `getTickFromMarketCapETH(capETH)` / `getTickFromMarketCapUSD(capUSD, ethPrice)` — Market cap → tick
114
+ - `marketCapFromTickETH(tick)` / `marketCapFromTickUSD(tick, ethPrice)` — Tick → market cap
115
+
116
+ ## Default Values
117
+
118
+ | Field | Default |
119
+ |-------|---------|
120
+ | hook | Static fee V2 (1% buy fee) |
121
+ | tickSpacing | 200 |
122
+ | tickIfToken0IsLiquid | -230400 (~10 ETH market cap) |
123
+ | positions | 3-tranche: 40% to $500K, 50% to $10M, 10% to $1B |
124
+ | mevModule | Sniper Auction V2 (80%→40% over 32s) |
125
+ | rewardRecipients | [deployer] at 100% |
126
+ | context | {"interface":"SDK"} |
127
+
128
+ ## Contract Addresses (Base Mainnet)
129
+
130
+ - Factory: 0x0000003482fe299E72d4908368044A8A173BE576
131
+ - LP Locker: 0x00000548732DfA56Be1257cE44D0CFc3B46dDb2A
132
+ - LP Locker Fee Conversion: 0x00000547518784420CEeF761fb18D884bb908102 (default)
133
+ - Fee Locker: 0x000008B9242b7e4432f6c4b1EeAD93562f9Cc94d
134
+ - Vault: 0x000001c5263F4d64CdC343cDA9C8bF961CF8376c
135
+ - Hook (Dynamic Fee V2): 0x2A2F73CDDa098d639bd8Bbcd7dF2bf24E06728cC
136
+ - Hook (Static Fee V2): 0xb2401c5369AaCF62F8d615623C7F68F84da428Cc
137
+ - Sniper Auction V2: 0x000007b64003ee07a69576F98859a0a36b854260
138
+ - MEV Block Delay: 0x0000035D83588954F3c581c3A66251b3F06AD5e4
139
+ - Airdrop V2: 0x00000C222442512b08446D33dd9754a7F260BE79
140
+ - Dev Buy Extension: 0x00000d7DE1f0A3FA7957F5d8A2b97B0E24e5783D
141
+ - WETH (Base): 0x4200000000000000000000000000000000000006
142
+ - Pool Manager (Uniswap V4): 0x498581fF718922c3f8e6A244956aF099B2652b2b
143
+
144
+ ## Docs
145
+
146
+ - README.md: Usage guide with code examples
147
+ - AGENT_README.md: Complete API reference for AI agents and developers (700+ lines)
148
+ - CHANGELOG.md: Version history
149
+ - examples/: 8 runnable TypeScript examples
150
+
151
+ ## Links
152
+
153
+ - NPM: https://www.npmjs.com/package/liquid-sdk
154
+ - GitHub: https://github.com/craigbots/liquid-sdk
package/package.json CHANGED
@@ -1,7 +1,12 @@
1
1
  {
2
2
  "name": "liquid-sdk",
3
- "version": "1.2.0",
4
- "description": "TypeScript SDK for the Liquid Protocol token launcher on Base",
3
+ "version": "1.3.0",
4
+ "description": "TypeScript SDK to deploy ERC-20 tokens with Uniswap V4 liquidity on Base — zero API keys, one dependency (viem)",
5
+ "author": "Liquid Protocol",
6
+ "homepage": "https://github.com/craigbots/liquid-sdk#readme",
7
+ "bugs": {
8
+ "url": "https://github.com/craigbots/liquid-sdk/issues"
9
+ },
5
10
  "main": "dist/index.js",
6
11
  "module": "dist/index.mjs",
7
12
  "types": "dist/index.d.ts",
@@ -13,7 +18,11 @@
13
18
  }
14
19
  },
15
20
  "files": [
16
- "dist"
21
+ "dist",
22
+ "README.md",
23
+ "AGENT_README.md",
24
+ "CHANGELOG.md",
25
+ "llms.txt"
17
26
  ],
18
27
  "scripts": {
19
28
  "build": "tsup",
@@ -48,6 +57,15 @@
48
57
  "uniswap",
49
58
  "v4",
50
59
  "token",
51
- "launcher"
60
+ "launcher",
61
+ "erc20",
62
+ "deploy",
63
+ "token-launcher",
64
+ "defi",
65
+ "onchain",
66
+ "web3",
67
+ "smart-contract",
68
+ "liquidity",
69
+ "mev-protection"
52
70
  ]
53
71
  }