@circle-fin/bridge-kit 1.6.0 → 1.6.1

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.
package/index.d.ts CHANGED
@@ -35,7 +35,6 @@ import { z } from '/home/runner/_work/stablecoin-kits-private/stablecoin-kits-pr
35
35
  */
36
36
  /**
37
37
  * Represents basic information about a currency or token.
38
- * @interface Currency
39
38
  * @category Types
40
39
  * @description Provides the essential properties of a cryptocurrency or token.
41
40
  * @example
@@ -67,7 +66,6 @@ interface Currency {
67
66
  }
68
67
  /**
69
68
  * Base information that all chain definitions must include.
70
- * @interface BaseChainDefinition
71
69
  * @category Types
72
70
  * @description Provides the common properties shared by all blockchain definitions.
73
71
  * @example
@@ -127,6 +125,11 @@ interface BaseChainDefinition {
127
125
  * @description Its presence indicates that USDC is supported.
128
126
  */
129
127
  usdcAddress: string | null;
128
+ /**
129
+ * The contract address for USDT.
130
+ * @description Its presence indicates that USDT is supported.
131
+ */
132
+ usdtAddress: string | null;
130
133
  /**
131
134
  * Optional CCTP configuration.
132
135
  * @description If provided, the chain supports CCTP.
@@ -168,7 +171,6 @@ interface BaseChainDefinition {
168
171
  }
169
172
  /**
170
173
  * Represents chain definitions for Ethereum Virtual Machine (EVM) compatible blockchains.
171
- * @interface EVMChainDefinition
172
174
  * @extends BaseChainDefinition
173
175
  * @category Types
174
176
  * @description Adds properties specific to EVM chains.
@@ -200,7 +202,6 @@ interface EVMChainDefinition extends BaseChainDefinition {
200
202
  }
201
203
  /**
202
204
  * Represents chain definitions for non-EVM blockchains.
203
- * @interface NonEVMChainDefinition
204
205
  * @extends BaseChainDefinition
205
206
  * @category Types
206
207
  * @description Contains properties for blockchains that do not use the EVM.
@@ -253,6 +254,7 @@ type ChainType = EVMChainDefinition['type'] | NonEVMChainDefinition['type'];
253
254
  * rpcEndpoints: ['https://eth.example.com'],
254
255
  * eurcAddress: null,
255
256
  * usdcAddress: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
257
+ * usdtAddress: '0xdac17f958d2ee523a2206206994597c13d831ec7',
256
258
  * cctp: {
257
259
  * domain: 0,
258
260
  * contracts: {
@@ -316,17 +318,74 @@ type ChainDefinitionWithCCTPv2 = ChainDefinition & {
316
318
  * - A string literal of the blockchain value (e.g., "Ethereum")
317
319
  */
318
320
  type ChainIdentifier$1 = ChainDefinition | Blockchain | `${Blockchain}`;
321
+ /**
322
+ * Split CCTP contract configuration.
323
+ *
324
+ * Used by chains that deploy separate TokenMessenger and MessageTransmitter contracts.
325
+ * This is the traditional CCTP architecture used by most EVM chains.
326
+ *
327
+ * @example
328
+ * ```typescript
329
+ * const splitConfig: CCTPSplitConfig = {
330
+ * type: 'split',
331
+ * tokenMessenger: '0x1234567890abcdef1234567890abcdef12345678',
332
+ * messageTransmitter: '0xabcdef1234567890abcdef1234567890abcdef12',
333
+ * confirmations: 12
334
+ * }
335
+ * ```
336
+ */
319
337
  interface CCTPSplitConfig {
320
338
  type: 'split';
321
339
  tokenMessenger: string;
322
340
  messageTransmitter: string;
323
341
  confirmations: number;
324
342
  }
343
+ /**
344
+ * Merged CCTP contract configuration.
345
+ *
346
+ * Used by chains that deploy a single unified CCTP contract.
347
+ * This simplified architecture is used by newer chain integrations.
348
+ *
349
+ * @example
350
+ * ```typescript
351
+ * const mergedConfig: CCTPMergedConfig = {
352
+ * type: 'merged',
353
+ * contract: '0x9876543210fedcba9876543210fedcba98765432',
354
+ * confirmations: 1
355
+ * }
356
+ * ```
357
+ */
325
358
  interface CCTPMergedConfig {
326
359
  type: 'merged';
327
360
  contract: string;
328
361
  confirmations: number;
329
362
  }
363
+ /**
364
+ * Version configuration for CCTP contracts.
365
+ *
366
+ * Defines whether the chain uses split or merged CCTP contract architecture.
367
+ * Split configuration uses separate TokenMessenger and MessageTransmitter contracts,
368
+ * while merged configuration uses a single unified contract.
369
+ *
370
+ * @example Split configuration (most EVM chains)
371
+ * ```typescript
372
+ * const splitConfig: VersionConfig = {
373
+ * type: 'split',
374
+ * tokenMessenger: '0x1234567890abcdef1234567890abcdef12345678',
375
+ * messageTransmitter: '0xabcdef1234567890abcdef1234567890abcdef12',
376
+ * confirmations: 12
377
+ * }
378
+ * ```
379
+ *
380
+ * @example Merged configuration (newer chains)
381
+ * ```typescript
382
+ * const mergedConfig: VersionConfig = {
383
+ * type: 'merged',
384
+ * contract: '0x9876543210fedcba9876543210fedcba98765432',
385
+ * confirmations: 1
386
+ * }
387
+ * ```
388
+ */
330
389
  type VersionConfig = CCTPSplitConfig | CCTPMergedConfig;
331
390
  type CCTPContracts = Partial<{
332
391
  v1: VersionConfig;
@@ -336,7 +395,6 @@ type CCTPContracts = Partial<{
336
395
  }>;
337
396
  /**
338
397
  * Configuration for the Cross-Chain Transfer Protocol (CCTP).
339
- * @interface CCTPConfig
340
398
  * @category Types
341
399
  * @description Contains the domain and required contract addresses for CCTP support.
342
400
  * @example
@@ -390,7 +448,7 @@ interface CCTPConfig {
390
448
  * const invalidType: KitContractType = 'invalid' // TypeScript error
391
449
  * ```
392
450
  */
393
- type KitContractType = 'bridge';
451
+ type KitContractType = 'bridge' | 'adapter';
394
452
  /**
395
453
  * Kit-specific contract addresses for enhanced chain functionality.
396
454
  *
@@ -621,6 +679,7 @@ declare const Algorand: {
621
679
  readonly rpcEndpoints: readonly ["https://mainnet-api.algonode.cloud"];
622
680
  readonly eurcAddress: null;
623
681
  readonly usdcAddress: "31566704";
682
+ readonly usdtAddress: null;
624
683
  readonly cctp: null;
625
684
  };
626
685
 
@@ -644,6 +703,7 @@ declare const AlgorandTestnet: {
644
703
  readonly rpcEndpoints: readonly ["https://testnet-api.algonode.cloud"];
645
704
  readonly eurcAddress: null;
646
705
  readonly usdcAddress: "10458941";
706
+ readonly usdtAddress: null;
647
707
  readonly cctp: null;
648
708
  };
649
709
 
@@ -667,6 +727,7 @@ declare const Aptos: {
667
727
  readonly rpcEndpoints: readonly ["https://fullnode.mainnet.aptoslabs.com/v1"];
668
728
  readonly eurcAddress: null;
669
729
  readonly usdcAddress: "0xbae207659db88bea0cbead6da0ed00aac12edcdda169e591cd41c94180b46f3b";
730
+ readonly usdtAddress: "0x357b0b74bc833e95a115ad22604854d6b0fca151cecd94111770e5d6ffc9dc2b";
670
731
  readonly cctp: {
671
732
  readonly domain: 9;
672
733
  readonly contracts: {
@@ -704,6 +765,7 @@ declare const AptosTestnet: {
704
765
  readonly rpcEndpoints: readonly ["https://fullnode.testnet.aptoslabs.com/v1"];
705
766
  readonly eurcAddress: null;
706
767
  readonly usdcAddress: "0x69091fbab5f7d635ee7ac5098cf0c1efbe31d68fec0f2cd565e8d168daf52832";
768
+ readonly usdtAddress: null;
707
769
  readonly cctp: {
708
770
  readonly domain: 9;
709
771
  readonly contracts: {
@@ -746,6 +808,7 @@ declare const ArcTestnet: {
746
808
  readonly rpcEndpoints: readonly ["https://rpc.testnet.arc.network/"];
747
809
  readonly eurcAddress: "0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a";
748
810
  readonly usdcAddress: "0x3600000000000000000000000000000000000000";
811
+ readonly usdtAddress: null;
749
812
  readonly cctp: {
750
813
  readonly domain: 26;
751
814
  readonly contracts: {
@@ -788,6 +851,7 @@ declare const Arbitrum: {
788
851
  readonly rpcEndpoints: readonly ["https://arb1.arbitrum.io/rpc"];
789
852
  readonly eurcAddress: null;
790
853
  readonly usdcAddress: "0xaf88d065e77c8cc2239327c5edb3a432268e5831";
854
+ readonly usdtAddress: null;
791
855
  readonly cctp: {
792
856
  readonly domain: 3;
793
857
  readonly contracts: {
@@ -812,6 +876,7 @@ declare const Arbitrum: {
812
876
  };
813
877
  readonly kitContracts: {
814
878
  readonly bridge: "0xB3FA262d0fB521cc93bE83d87b322b8A23DAf3F0";
879
+ readonly adapter: "0x7FB8c7260b63934d8da38aF902f87ae6e284a845";
815
880
  };
816
881
  };
817
882
 
@@ -836,6 +901,7 @@ declare const ArbitrumSepolia: {
836
901
  readonly rpcEndpoints: readonly ["https://sepolia-rollup.arbitrum.io/rpc"];
837
902
  readonly eurcAddress: null;
838
903
  readonly usdcAddress: "0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d";
904
+ readonly usdtAddress: null;
839
905
  readonly cctp: {
840
906
  readonly domain: 3;
841
907
  readonly contracts: {
@@ -884,6 +950,7 @@ declare const Avalanche: {
884
950
  readonly rpcEndpoints: readonly ["https://api.avax.network/ext/bc/C/rpc"];
885
951
  readonly eurcAddress: "0xc891eb4cbdeff6e073e859e987815ed1505c2acd";
886
952
  readonly usdcAddress: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E";
953
+ readonly usdtAddress: "0x9702230a8ea53601f5cd2dc00fdbc13d4df4a8c7";
887
954
  readonly cctp: {
888
955
  readonly domain: 1;
889
956
  readonly contracts: {
@@ -908,6 +975,7 @@ declare const Avalanche: {
908
975
  };
909
976
  readonly kitContracts: {
910
977
  readonly bridge: "0xB3FA262d0fB521cc93bE83d87b322b8A23DAf3F0";
978
+ readonly adapter: "0x7FB8c7260b63934d8da38aF902f87ae6e284a845";
911
979
  };
912
980
  };
913
981
 
@@ -931,6 +999,7 @@ declare const AvalancheFuji: {
931
999
  readonly explorerUrl: "https://subnets-test.avax.network/c-chain/tx/{hash}";
932
1000
  readonly eurcAddress: "0x5e44db7996c682e92a960b65ac713a54ad815c6b";
933
1001
  readonly usdcAddress: "0x5425890298aed601595a70ab815c96711a31bc65";
1002
+ readonly usdtAddress: null;
934
1003
  readonly cctp: {
935
1004
  readonly domain: 1;
936
1005
  readonly contracts: {
@@ -980,6 +1049,7 @@ declare const Base: {
980
1049
  readonly rpcEndpoints: readonly ["https://mainnet.base.org", "https://base.publicnode.com"];
981
1050
  readonly eurcAddress: "0x60a3e35cc302bfa44cb288bc5a4f316fdb1adb42";
982
1051
  readonly usdcAddress: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
1052
+ readonly usdtAddress: null;
983
1053
  readonly cctp: {
984
1054
  readonly domain: 6;
985
1055
  readonly contracts: {
@@ -1004,6 +1074,7 @@ declare const Base: {
1004
1074
  };
1005
1075
  readonly kitContracts: {
1006
1076
  readonly bridge: "0xB3FA262d0fB521cc93bE83d87b322b8A23DAf3F0";
1077
+ readonly adapter: "0x7FB8c7260b63934d8da38aF902f87ae6e284a845";
1007
1078
  };
1008
1079
  };
1009
1080
 
@@ -1028,6 +1099,7 @@ declare const BaseSepolia: {
1028
1099
  readonly rpcEndpoints: readonly ["https://sepolia.base.org"];
1029
1100
  readonly eurcAddress: "0x808456652fdb597867f38412077A9182bf77359F";
1030
1101
  readonly usdcAddress: "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
1102
+ readonly usdtAddress: null;
1031
1103
  readonly cctp: {
1032
1104
  readonly domain: 6;
1033
1105
  readonly contracts: {
@@ -1076,6 +1148,7 @@ declare const Celo: {
1076
1148
  readonly rpcEndpoints: readonly ["https://forno.celo.org"];
1077
1149
  readonly eurcAddress: null;
1078
1150
  readonly usdcAddress: "0xcebA9300f2b948710d2653dD7B07f33A8B32118C";
1151
+ readonly usdtAddress: "0x48065fbBE25f71C9282ddf5e1cD6D6A887483D5e";
1079
1152
  readonly cctp: null;
1080
1153
  };
1081
1154
 
@@ -1100,6 +1173,7 @@ declare const CeloAlfajoresTestnet: {
1100
1173
  readonly rpcEndpoints: readonly ["https://alfajores-forno.celo-testnet.org"];
1101
1174
  readonly eurcAddress: null;
1102
1175
  readonly usdcAddress: "0x2F25deB3848C207fc8E0c34035B3Ba7fC157602B";
1176
+ readonly usdtAddress: null;
1103
1177
  readonly cctp: null;
1104
1178
  };
1105
1179
 
@@ -1124,6 +1198,7 @@ declare const Codex: {
1124
1198
  readonly rpcEndpoints: readonly ["https://rpc.codex.xyz"];
1125
1199
  readonly eurcAddress: null;
1126
1200
  readonly usdcAddress: "0xd996633a415985DBd7D6D12f4A4343E31f5037cf";
1201
+ readonly usdtAddress: null;
1127
1202
  readonly cctp: {
1128
1203
  readonly domain: 12;
1129
1204
  readonly contracts: {
@@ -1166,6 +1241,7 @@ declare const CodexTestnet: {
1166
1241
  readonly rpcEndpoints: readonly ["https://rpc.codex-stg.xyz"];
1167
1242
  readonly eurcAddress: null;
1168
1243
  readonly usdcAddress: "0x6d7f141b6819C2c9CC2f818e6ad549E7Ca090F8f";
1244
+ readonly usdtAddress: null;
1169
1245
  readonly cctp: {
1170
1246
  readonly domain: 12;
1171
1247
  readonly contracts: {
@@ -1208,6 +1284,7 @@ declare const Ethereum: {
1208
1284
  readonly rpcEndpoints: readonly ["https://eth.merkle.io", "https://ethereum.publicnode.com"];
1209
1285
  readonly eurcAddress: "0x1aBaEA1f7C830bD89Acc67eC4af516284b1bC33c";
1210
1286
  readonly usdcAddress: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48";
1287
+ readonly usdtAddress: "0xdac17f958d2ee523a2206206994597c13d831ec7";
1211
1288
  readonly cctp: {
1212
1289
  readonly domain: 0;
1213
1290
  readonly contracts: {
@@ -1232,6 +1309,7 @@ declare const Ethereum: {
1232
1309
  };
1233
1310
  readonly kitContracts: {
1234
1311
  readonly bridge: "0xB3FA262d0fB521cc93bE83d87b322b8A23DAf3F0";
1312
+ readonly adapter: "0x7FB8c7260b63934d8da38aF902f87ae6e284a845";
1235
1313
  };
1236
1314
  };
1237
1315
 
@@ -1256,6 +1334,7 @@ declare const EthereumSepolia: {
1256
1334
  readonly rpcEndpoints: readonly ["https://sepolia.drpc.org"];
1257
1335
  readonly eurcAddress: "0x08210F9170F89Ab7658F0B5E3fF39b0E03C594D4";
1258
1336
  readonly usdcAddress: "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238";
1337
+ readonly usdtAddress: null;
1259
1338
  readonly cctp: {
1260
1339
  readonly domain: 0;
1261
1340
  readonly contracts: {
@@ -1303,6 +1382,7 @@ declare const Hedera: {
1303
1382
  readonly rpcEndpoints: readonly ["https://mainnet.hashio.io/api"];
1304
1383
  readonly eurcAddress: null;
1305
1384
  readonly usdcAddress: "0.0.456858";
1385
+ readonly usdtAddress: null;
1306
1386
  readonly cctp: null;
1307
1387
  };
1308
1388
 
@@ -1326,6 +1406,7 @@ declare const HederaTestnet: {
1326
1406
  readonly rpcEndpoints: readonly ["https://testnet.hashio.io/api"];
1327
1407
  readonly eurcAddress: null;
1328
1408
  readonly usdcAddress: "0.0.429274";
1409
+ readonly usdtAddress: null;
1329
1410
  readonly cctp: null;
1330
1411
  };
1331
1412
 
@@ -1352,6 +1433,7 @@ declare const HyperEVM: {
1352
1433
  readonly rpcEndpoints: readonly ["https://rpc.hyperliquid.xyz/evm"];
1353
1434
  readonly eurcAddress: null;
1354
1435
  readonly usdcAddress: "0xb88339CB7199b77E23DB6E890353E22632Ba630f";
1436
+ readonly usdtAddress: null;
1355
1437
  readonly cctp: {
1356
1438
  readonly domain: 19;
1357
1439
  readonly contracts: {
@@ -1370,6 +1452,7 @@ declare const HyperEVM: {
1370
1452
  };
1371
1453
  readonly kitContracts: {
1372
1454
  readonly bridge: "0xB3FA262d0fB521cc93bE83d87b322b8A23DAf3F0";
1455
+ readonly adapter: "0x7FB8c7260b63934d8da38aF902f87ae6e284a845";
1373
1456
  };
1374
1457
  };
1375
1458
 
@@ -1395,6 +1478,7 @@ declare const HyperEVMTestnet: {
1395
1478
  readonly rpcEndpoints: readonly ["https://rpc.hyperliquid-testnet.xyz/evm"];
1396
1479
  readonly eurcAddress: null;
1397
1480
  readonly usdcAddress: "0x2B3370eE501B4a559b57D449569354196457D8Ab";
1481
+ readonly usdtAddress: null;
1398
1482
  readonly cctp: {
1399
1483
  readonly domain: 19;
1400
1484
  readonly contracts: {
@@ -1439,6 +1523,7 @@ declare const Ink: {
1439
1523
  readonly rpcEndpoints: readonly ["https://rpc-gel.inkonchain.com", "https://rpc-qnd.inkonchain.com"];
1440
1524
  readonly eurcAddress: null;
1441
1525
  readonly usdcAddress: "0x2D270e6886d130D724215A266106e6832161EAEd";
1526
+ readonly usdtAddress: null;
1442
1527
  readonly cctp: {
1443
1528
  readonly domain: 21;
1444
1529
  readonly contracts: {
@@ -1457,6 +1542,7 @@ declare const Ink: {
1457
1542
  };
1458
1543
  readonly kitContracts: {
1459
1544
  readonly bridge: "0xB3FA262d0fB521cc93bE83d87b322b8A23DAf3F0";
1545
+ readonly adapter: "0x7FB8c7260b63934d8da38aF902f87ae6e284a845";
1460
1546
  };
1461
1547
  };
1462
1548
 
@@ -1482,6 +1568,7 @@ declare const InkTestnet: {
1482
1568
  readonly rpcEndpoints: readonly ["https://rpc-gel-sepolia.inkonchain.com", "https://rpc-qnd-sepolia.inkonchain.com"];
1483
1569
  readonly eurcAddress: null;
1484
1570
  readonly usdcAddress: "0xFabab97dCE620294D2B0b0e46C68964e326300Ac";
1571
+ readonly usdtAddress: null;
1485
1572
  readonly cctp: {
1486
1573
  readonly domain: 21;
1487
1574
  readonly contracts: {
@@ -1524,6 +1611,7 @@ declare const Linea: {
1524
1611
  readonly rpcEndpoints: readonly ["https://rpc.linea.build"];
1525
1612
  readonly eurcAddress: null;
1526
1613
  readonly usdcAddress: "0x176211869ca2b568f2a7d4ee941e073a821ee1ff";
1614
+ readonly usdtAddress: null;
1527
1615
  readonly cctp: {
1528
1616
  readonly domain: 11;
1529
1617
  readonly contracts: {
@@ -1542,6 +1630,7 @@ declare const Linea: {
1542
1630
  };
1543
1631
  readonly kitContracts: {
1544
1632
  readonly bridge: "0xB3FA262d0fB521cc93bE83d87b322b8A23DAf3F0";
1633
+ readonly adapter: "0x7FB8c7260b63934d8da38aF902f87ae6e284a845";
1545
1634
  };
1546
1635
  };
1547
1636
 
@@ -1566,6 +1655,7 @@ declare const LineaSepolia: {
1566
1655
  readonly rpcEndpoints: readonly ["https://rpc.sepolia.linea.build"];
1567
1656
  readonly eurcAddress: null;
1568
1657
  readonly usdcAddress: "0xfece4462d57bd51a6a552365a011b95f0e16d9b7";
1658
+ readonly usdtAddress: null;
1569
1659
  readonly cctp: {
1570
1660
  readonly domain: 11;
1571
1661
  readonly contracts: {
@@ -1610,6 +1700,7 @@ declare const Monad: {
1610
1700
  readonly rpcEndpoints: readonly ["https://rpc.monad.xyz"];
1611
1701
  readonly eurcAddress: null;
1612
1702
  readonly usdcAddress: "0x754704Bc059F8C67012fEd69BC8A327a5aafb603";
1703
+ readonly usdtAddress: null;
1613
1704
  readonly cctp: {
1614
1705
  readonly domain: 15;
1615
1706
  readonly contracts: {
@@ -1628,6 +1719,7 @@ declare const Monad: {
1628
1719
  };
1629
1720
  readonly kitContracts: {
1630
1721
  readonly bridge: "0xB3FA262d0fB521cc93bE83d87b322b8A23DAf3F0";
1722
+ readonly adapter: "0x7FB8c7260b63934d8da38aF902f87ae6e284a845";
1631
1723
  };
1632
1724
  };
1633
1725
 
@@ -1654,6 +1746,7 @@ declare const MonadTestnet: {
1654
1746
  readonly rpcEndpoints: readonly ["https://testnet-rpc.monad.xyz"];
1655
1747
  readonly eurcAddress: null;
1656
1748
  readonly usdcAddress: "0x534b2f3A21130d7a60830c2Df862319e593943A3";
1749
+ readonly usdtAddress: null;
1657
1750
  readonly cctp: {
1658
1751
  readonly domain: 15;
1659
1752
  readonly contracts: {
@@ -1695,6 +1788,7 @@ declare const NEAR: {
1695
1788
  readonly rpcEndpoints: readonly ["https://eth-rpc.mainnet.near.org"];
1696
1789
  readonly eurcAddress: null;
1697
1790
  readonly usdcAddress: "17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1";
1791
+ readonly usdtAddress: "usdt.tether-token.near";
1698
1792
  readonly cctp: null;
1699
1793
  };
1700
1794
 
@@ -1718,6 +1812,7 @@ declare const NEARTestnet: {
1718
1812
  readonly rpcEndpoints: readonly ["https://eth-rpc.testnet.near.org"];
1719
1813
  readonly eurcAddress: null;
1720
1814
  readonly usdcAddress: "3e2210e1184b45b64c8a434c0a7e7b23cc04ea7eb7a6c3c32520d03d4afcb8af";
1815
+ readonly usdtAddress: null;
1721
1816
  readonly cctp: null;
1722
1817
  };
1723
1818
 
@@ -1741,6 +1836,7 @@ declare const Noble: {
1741
1836
  readonly rpcEndpoints: readonly ["https://noble-rpc.polkachu.com"];
1742
1837
  readonly eurcAddress: null;
1743
1838
  readonly usdcAddress: "uusdc";
1839
+ readonly usdtAddress: null;
1744
1840
  readonly cctp: {
1745
1841
  readonly domain: 4;
1746
1842
  readonly contracts: {
@@ -1777,6 +1873,7 @@ declare const NobleTestnet: {
1777
1873
  readonly rpcEndpoints: readonly ["https://noble-testnet-rpc.polkachu.com"];
1778
1874
  readonly eurcAddress: null;
1779
1875
  readonly usdcAddress: "uusdc";
1876
+ readonly usdtAddress: null;
1780
1877
  readonly cctp: {
1781
1878
  readonly domain: 4;
1782
1879
  readonly contracts: {
@@ -1814,6 +1911,7 @@ declare const Optimism: {
1814
1911
  readonly rpcEndpoints: readonly ["https://mainnet.optimism.io"];
1815
1912
  readonly eurcAddress: null;
1816
1913
  readonly usdcAddress: "0x0b2c639c533813f4aa9d7837caf62653d097ff85";
1914
+ readonly usdtAddress: null;
1817
1915
  readonly cctp: {
1818
1916
  readonly domain: 2;
1819
1917
  readonly contracts: {
@@ -1838,6 +1936,7 @@ declare const Optimism: {
1838
1936
  };
1839
1937
  readonly kitContracts: {
1840
1938
  readonly bridge: "0xB3FA262d0fB521cc93bE83d87b322b8A23DAf3F0";
1939
+ readonly adapter: "0x7FB8c7260b63934d8da38aF902f87ae6e284a845";
1841
1940
  };
1842
1941
  };
1843
1942
 
@@ -1862,6 +1961,7 @@ declare const OptimismSepolia: {
1862
1961
  readonly rpcEndpoints: readonly ["https://sepolia.optimism.io"];
1863
1962
  readonly eurcAddress: null;
1864
1963
  readonly usdcAddress: "0x5fd84259d66Cd46123540766Be93DFE6D43130D7";
1964
+ readonly usdtAddress: null;
1865
1965
  readonly cctp: {
1866
1966
  readonly domain: 2;
1867
1967
  readonly contracts: {
@@ -1912,6 +2012,7 @@ declare const Plume: {
1912
2012
  readonly rpcEndpoints: readonly ["https://rpc.plume.org"];
1913
2013
  readonly eurcAddress: null;
1914
2014
  readonly usdcAddress: "0x222365EF19F7947e5484218551B56bb3965Aa7aF";
2015
+ readonly usdtAddress: null;
1915
2016
  readonly cctp: {
1916
2017
  readonly domain: 22;
1917
2018
  readonly contracts: {
@@ -1930,6 +2031,7 @@ declare const Plume: {
1930
2031
  };
1931
2032
  readonly kitContracts: {
1932
2033
  readonly bridge: "0xB3FA262d0fB521cc93bE83d87b322b8A23DAf3F0";
2034
+ readonly adapter: "0x7FB8c7260b63934d8da38aF902f87ae6e284a845";
1933
2035
  };
1934
2036
  };
1935
2037
 
@@ -1955,6 +2057,7 @@ declare const PlumeTestnet: {
1955
2057
  readonly rpcEndpoints: readonly ["https://testnet-rpc.plume.org"];
1956
2058
  readonly eurcAddress: null;
1957
2059
  readonly usdcAddress: "0xcB5f30e335672893c7eb944B374c196392C19D18";
2060
+ readonly usdtAddress: null;
1958
2061
  readonly cctp: {
1959
2062
  readonly domain: 22;
1960
2063
  readonly contracts: {
@@ -1996,6 +2099,7 @@ declare const PolkadotAssetHub: {
1996
2099
  readonly rpcEndpoints: readonly ["https://asset-hub-polkadot-rpc.n.dwellir.com"];
1997
2100
  readonly eurcAddress: null;
1998
2101
  readonly usdcAddress: "1337";
2102
+ readonly usdtAddress: "1984";
1999
2103
  readonly cctp: null;
2000
2104
  };
2001
2105
 
@@ -2019,6 +2123,7 @@ declare const PolkadotWestmint: {
2019
2123
  readonly rpcEndpoints: readonly ["https://westmint-rpc.polkadot.io"];
2020
2124
  readonly eurcAddress: null;
2021
2125
  readonly usdcAddress: "Asset ID 31337";
2126
+ readonly usdtAddress: null;
2022
2127
  readonly cctp: null;
2023
2128
  };
2024
2129
 
@@ -2040,9 +2145,10 @@ declare const Polygon: {
2040
2145
  readonly chainId: 137;
2041
2146
  readonly isTestnet: false;
2042
2147
  readonly explorerUrl: "https://polygonscan.com/tx/{hash}";
2043
- readonly rpcEndpoints: readonly ["https://polygon-rpc.com", "https://polygon.publicnode.com"];
2148
+ readonly rpcEndpoints: readonly ["https://polygon.publicnode.com", "https://polygon.drpc.org"];
2044
2149
  readonly eurcAddress: null;
2045
2150
  readonly usdcAddress: "0x3c499c542cef5e3811e1192ce70d8cc03d5c3359";
2151
+ readonly usdtAddress: null;
2046
2152
  readonly cctp: {
2047
2153
  readonly domain: 7;
2048
2154
  readonly contracts: {
@@ -2067,6 +2173,7 @@ declare const Polygon: {
2067
2173
  };
2068
2174
  readonly kitContracts: {
2069
2175
  readonly bridge: "0xB3FA262d0fB521cc93bE83d87b322b8A23DAf3F0";
2176
+ readonly adapter: "0x7FB8c7260b63934d8da38aF902f87ae6e284a845";
2070
2177
  };
2071
2178
  };
2072
2179
 
@@ -2091,6 +2198,7 @@ declare const PolygonAmoy: {
2091
2198
  readonly rpcEndpoints: readonly ["https://rpc-amoy.polygon.technology"];
2092
2199
  readonly eurcAddress: null;
2093
2200
  readonly usdcAddress: "0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582";
2201
+ readonly usdtAddress: null;
2094
2202
  readonly cctp: {
2095
2203
  readonly domain: 7;
2096
2204
  readonly contracts: {
@@ -2141,6 +2249,7 @@ declare const Sei: {
2141
2249
  readonly rpcEndpoints: readonly ["https://evm-rpc.sei-apis.com"];
2142
2250
  readonly eurcAddress: null;
2143
2251
  readonly usdcAddress: "0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392";
2252
+ readonly usdtAddress: null;
2144
2253
  readonly cctp: {
2145
2254
  readonly domain: 16;
2146
2255
  readonly contracts: {
@@ -2159,6 +2268,7 @@ declare const Sei: {
2159
2268
  };
2160
2269
  readonly kitContracts: {
2161
2270
  readonly bridge: "0xB3FA262d0fB521cc93bE83d87b322b8A23DAf3F0";
2271
+ readonly adapter: "0x7FB8c7260b63934d8da38aF902f87ae6e284a845";
2162
2272
  };
2163
2273
  };
2164
2274
 
@@ -2184,6 +2294,7 @@ declare const SeiTestnet: {
2184
2294
  readonly rpcEndpoints: readonly ["https://evm-rpc-testnet.sei-apis.com"];
2185
2295
  readonly eurcAddress: null;
2186
2296
  readonly usdcAddress: "0x4fCF1784B31630811181f670Aea7A7bEF803eaED";
2297
+ readonly usdtAddress: null;
2187
2298
  readonly cctp: {
2188
2299
  readonly domain: 16;
2189
2300
  readonly contracts: {
@@ -2226,6 +2337,7 @@ declare const Sonic: {
2226
2337
  readonly rpcEndpoints: readonly ["https://rpc.soniclabs.com"];
2227
2338
  readonly eurcAddress: null;
2228
2339
  readonly usdcAddress: "0x29219dd400f2Bf60E5a23d13Be72B486D4038894";
2340
+ readonly usdtAddress: null;
2229
2341
  readonly cctp: {
2230
2342
  readonly domain: 13;
2231
2343
  readonly contracts: {
@@ -2244,6 +2356,7 @@ declare const Sonic: {
2244
2356
  };
2245
2357
  readonly kitContracts: {
2246
2358
  readonly bridge: "0xB3FA262d0fB521cc93bE83d87b322b8A23DAf3F0";
2359
+ readonly adapter: "0x7FB8c7260b63934d8da38aF902f87ae6e284a845";
2247
2360
  };
2248
2361
  };
2249
2362
 
@@ -2268,6 +2381,7 @@ declare const SonicTestnet: {
2268
2381
  readonly rpcEndpoints: readonly ["https://rpc.testnet.soniclabs.com"];
2269
2382
  readonly eurcAddress: null;
2270
2383
  readonly usdcAddress: "0x0BA304580ee7c9a980CF72e55f5Ed2E9fd30Bc51";
2384
+ readonly usdtAddress: null;
2271
2385
  readonly cctp: {
2272
2386
  readonly domain: 13;
2273
2387
  readonly contracts: {
@@ -2309,6 +2423,7 @@ declare const Solana: {
2309
2423
  readonly rpcEndpoints: readonly ["https://api.mainnet-beta.solana.com"];
2310
2424
  readonly eurcAddress: "HzwqbKZw8HxMN6bF2yFZNrht3c2iXXzpKcFu7uBEDKtr";
2311
2425
  readonly usdcAddress: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
2426
+ readonly usdtAddress: "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB";
2312
2427
  readonly cctp: {
2313
2428
  readonly domain: 5;
2314
2429
  readonly contracts: {
@@ -2355,6 +2470,7 @@ declare const SolanaDevnet: {
2355
2470
  readonly explorerUrl: "https://solscan.io/tx/{hash}?cluster=devnet";
2356
2471
  readonly eurcAddress: "HzwqbKZw8HxMN6bF2yFZNrht3c2iXXzpKcFu7uBEDKtr";
2357
2472
  readonly usdcAddress: "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU";
2473
+ readonly usdtAddress: null;
2358
2474
  readonly cctp: {
2359
2475
  readonly domain: 5;
2360
2476
  readonly contracts: {
@@ -2403,6 +2519,7 @@ declare const Stellar: {
2403
2519
  readonly rpcEndpoints: readonly ["https://horizon.stellar.org"];
2404
2520
  readonly eurcAddress: "EURC-GDHU6WRG4IEQXM5NZ4BMPKOXHW76MZM4Y2IEMFDVXBSDP6SJY4ITNPP2";
2405
2521
  readonly usdcAddress: "USDC-GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN";
2522
+ readonly usdtAddress: null;
2406
2523
  readonly cctp: null;
2407
2524
  };
2408
2525
 
@@ -2426,6 +2543,7 @@ declare const StellarTestnet: {
2426
2543
  readonly rpcEndpoints: readonly ["https://horizon-testnet.stellar.org"];
2427
2544
  readonly eurcAddress: "EURC-GB3Q6QDZYTHWT7E5PVS3W7FUT5GVAFC5KSZFFLPU25GO7VTC3NM2ZTVO";
2428
2545
  readonly usdcAddress: "USDC-GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5";
2546
+ readonly usdtAddress: null;
2429
2547
  readonly cctp: null;
2430
2548
  };
2431
2549
 
@@ -2449,6 +2567,7 @@ declare const Sui: {
2449
2567
  readonly rpcEndpoints: readonly ["https://fullnode.mainnet.sui.io"];
2450
2568
  readonly eurcAddress: null;
2451
2569
  readonly usdcAddress: "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC";
2570
+ readonly usdtAddress: null;
2452
2571
  readonly cctp: {
2453
2572
  readonly domain: 8;
2454
2573
  readonly contracts: {
@@ -2486,6 +2605,7 @@ declare const SuiTestnet: {
2486
2605
  readonly rpcEndpoints: readonly ["https://fullnode.testnet.sui.io"];
2487
2606
  readonly eurcAddress: null;
2488
2607
  readonly usdcAddress: "0xa1ec7fc00a6f40db9693ad1415d0c193ad3906494428cf252621037bd7117e29::usdc::USDC";
2608
+ readonly usdtAddress: null;
2489
2609
  readonly cctp: {
2490
2610
  readonly domain: 8;
2491
2611
  readonly contracts: {
@@ -2524,6 +2644,7 @@ declare const Unichain: {
2524
2644
  readonly rpcEndpoints: readonly ["https://mainnet.unichain.org"];
2525
2645
  readonly eurcAddress: null;
2526
2646
  readonly usdcAddress: "0x078D782b760474a361dDA0AF3839290b0EF57AD6";
2647
+ readonly usdtAddress: null;
2527
2648
  readonly cctp: {
2528
2649
  readonly domain: 10;
2529
2650
  readonly contracts: {
@@ -2548,6 +2669,7 @@ declare const Unichain: {
2548
2669
  };
2549
2670
  readonly kitContracts: {
2550
2671
  readonly bridge: "0xB3FA262d0fB521cc93bE83d87b322b8A23DAf3F0";
2672
+ readonly adapter: "0x7FB8c7260b63934d8da38aF902f87ae6e284a845";
2551
2673
  };
2552
2674
  };
2553
2675
 
@@ -2572,6 +2694,7 @@ declare const UnichainSepolia: {
2572
2694
  readonly rpcEndpoints: readonly ["https://sepolia.unichain.org"];
2573
2695
  readonly eurcAddress: null;
2574
2696
  readonly usdcAddress: "0x31d0220469e10c4E71834a79b1f276d740d3768F";
2697
+ readonly usdtAddress: null;
2575
2698
  readonly cctp: {
2576
2699
  readonly domain: 10;
2577
2700
  readonly contracts: {
@@ -2620,6 +2743,7 @@ declare const WorldChain: {
2620
2743
  readonly rpcEndpoints: readonly ["https://worldchain-mainnet.g.alchemy.com/public"];
2621
2744
  readonly eurcAddress: null;
2622
2745
  readonly usdcAddress: "0x79A02482A880bCE3F13e09Da970dC34db4CD24d1";
2746
+ readonly usdtAddress: null;
2623
2747
  readonly cctp: {
2624
2748
  readonly domain: 14;
2625
2749
  readonly contracts: {
@@ -2638,6 +2762,7 @@ declare const WorldChain: {
2638
2762
  };
2639
2763
  readonly kitContracts: {
2640
2764
  readonly bridge: "0xB3FA262d0fB521cc93bE83d87b322b8A23DAf3F0";
2765
+ readonly adapter: "0x7FB8c7260b63934d8da38aF902f87ae6e284a845";
2641
2766
  };
2642
2767
  };
2643
2768
 
@@ -2662,6 +2787,7 @@ declare const WorldChainSepolia: {
2662
2787
  readonly rpcEndpoints: readonly ["https://worldchain-sepolia.drpc.org", "https://worldchain-sepolia.g.alchemy.com/public"];
2663
2788
  readonly eurcAddress: null;
2664
2789
  readonly usdcAddress: "0x66145f38cBAC35Ca6F1Dfb4914dF98F1614aeA88";
2790
+ readonly usdtAddress: null;
2665
2791
  readonly cctp: {
2666
2792
  readonly domain: 14;
2667
2793
  readonly contracts: {
@@ -2706,6 +2832,7 @@ declare const XDC: {
2706
2832
  readonly rpcEndpoints: readonly ["https://erpc.xdcrpc.com", "https://erpc.xinfin.network"];
2707
2833
  readonly eurcAddress: null;
2708
2834
  readonly usdcAddress: "0xfA2958CB79b0491CC627c1557F441eF849Ca8eb1";
2835
+ readonly usdtAddress: null;
2709
2836
  readonly cctp: {
2710
2837
  readonly domain: 18;
2711
2838
  readonly contracts: {
@@ -2724,6 +2851,7 @@ declare const XDC: {
2724
2851
  };
2725
2852
  readonly kitContracts: {
2726
2853
  readonly bridge: "0xB3FA262d0fB521cc93bE83d87b322b8A23DAf3F0";
2854
+ readonly adapter: "0x7FB8c7260b63934d8da38aF902f87ae6e284a845";
2727
2855
  };
2728
2856
  };
2729
2857
 
@@ -2748,6 +2876,7 @@ declare const XDCApothem: {
2748
2876
  readonly rpcEndpoints: readonly ["https://erpc.apothem.network"];
2749
2877
  readonly eurcAddress: null;
2750
2878
  readonly usdcAddress: "0xb5AB69F7bBada22B28e79C8FFAECe55eF1c771D4";
2879
+ readonly usdtAddress: null;
2751
2880
  readonly cctp: {
2752
2881
  readonly domain: 18;
2753
2882
  readonly contracts: {
@@ -2790,6 +2919,7 @@ declare const ZKSyncEra: {
2790
2919
  readonly rpcEndpoints: readonly ["https://mainnet.era.zksync.io"];
2791
2920
  readonly eurcAddress: null;
2792
2921
  readonly usdcAddress: "0x1d17CBcF0D6D143135aE902365D2E5e2A16538D4";
2922
+ readonly usdtAddress: null;
2793
2923
  readonly cctp: null;
2794
2924
  };
2795
2925
 
@@ -2814,6 +2944,7 @@ declare const ZKSyncEraSepolia: {
2814
2944
  readonly rpcEndpoints: readonly ["https://sepolia.era.zksync.dev"];
2815
2945
  readonly eurcAddress: null;
2816
2946
  readonly usdcAddress: "0xAe045DE5638162fa134807Cb558E15A3F5A7F853";
2947
+ readonly usdtAddress: null;
2817
2948
  readonly cctp: null;
2818
2949
  };
2819
2950
 
@@ -3135,8 +3266,20 @@ type EvmPreparedChainRequestParams = {
3135
3266
  interface SolanaPreparedChainRequestParams {
3136
3267
  /**
3137
3268
  * The array of instructions to include in the transaction.
3269
+ *
3270
+ * @remarks
3271
+ * Used for instruction-based transaction building. Mutually exclusive with
3272
+ * `serializedTransaction`.
3273
+ */
3274
+ instructions?: TransactionInstruction[];
3275
+ /**
3276
+ * A pre-serialized transaction as a Uint8Array (e.g., from a service like Jupiter).
3277
+ *
3278
+ * @remarks
3279
+ * Used for executing pre-built transactions from external services.
3280
+ * The transaction may be partially signed. Mutually exclusive with `instructions`.
3138
3281
  */
3139
- instructions: TransactionInstruction[];
3282
+ serializedTransaction?: Uint8Array;
3140
3283
  /**
3141
3284
  * Additional signers besides the Adapter's wallet (e.g. program-derived authorities).
3142
3285
  */
@@ -3933,31 +4076,443 @@ interface CCTPActionMap {
3933
4076
  }
3934
4077
 
3935
4078
  /**
3936
- * Action map for native token operations (ETH, SOL, MATIC, etc.).
4079
+ * Permit signature standards for gasless token approvals.
3937
4080
  *
3938
- * Native tokens are the primary currency of each blockchain network,
3939
- * used for paying transaction fees and as a store of value.
3940
- * These actions operate on the native token without requiring
3941
- * a separate token contract address.
4081
+ * Defines the permit types that can be used to approve token spending
4082
+ * without requiring a separate approval transaction.
3942
4083
  *
3943
4084
  * @remarks
3944
- * Native token operations differ from ERC-20/SPL token operations
3945
- * in that they don't require contract interactions for basic transfers
3946
- * and balance checks.
4085
+ * - NONE: No permit, tokens must be pre-approved via separate transaction
4086
+ * - EIP2612: Standard ERC-20 permit (USDC, DAI v2, and most modern tokens)
4087
+ */
4088
+ declare enum PermitType {
4089
+ /** No permit required - tokens must be pre-approved */
4090
+ NONE = 0,
4091
+ /** EIP-2612 standard permit */
4092
+ EIP2612 = 1
4093
+ }
4094
+ /**
4095
+ * Token input with permit signature for gasless approval.
3947
4096
  *
3948
- * @see {@link ActionMap} for the complete action structure
4097
+ * The Adapter Contract uses this to pull tokens from the user's wallet
4098
+ * using permit signatures instead of requiring separate approval transactions.
4099
+ *
4100
+ * @example
4101
+ * ```typescript
4102
+ * const tokenInput: TokenInput = {
4103
+ * permitType: PermitType.EIP2612,
4104
+ * token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
4105
+ * from: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
4106
+ * amount: 1000000n, // 1 USDC
4107
+ * permitCalldata: '0x...' // Encoded permit(value, deadline, v, r, s)
4108
+ * }
4109
+ * ```
3949
4110
  */
3950
- interface NativeActionMap {
4111
+ interface TokenInput {
3951
4112
  /**
3952
- * Get the native token balance (SOL, ETH, etc.) for a wallet address.
4113
+ * Type of permit to execute.
3953
4114
  */
3954
- balanceOf: ActionParameters & {
3955
- /**
3956
- * The address to check the native balance for. If not provided, it will be
3957
- * automatically derived from the adapter context.
3958
- */
3959
- walletAddress?: string | undefined;
3960
- };
4115
+ permitType: PermitType;
4116
+ /**
4117
+ * Token contract address to pull from user.
4118
+ */
4119
+ token: `0x${string}`;
4120
+ /**
4121
+ * Amount of tokens to pull via permit.
4122
+ */
4123
+ amount: bigint;
4124
+ /**
4125
+ * ABI-encoded permit calldata.
4126
+ *
4127
+ * For EIP-2612: encode(value, deadline, v, r, s)
4128
+ * For Permit2: encode(permit, signature)
4129
+ *
4130
+ * @example '0x0000000000000000000000000000000000000000000000000000000000989680...'
4131
+ */
4132
+ permitCalldata: `0x${string}`;
4133
+ }
4134
+ /**
4135
+ * Single instruction to execute within the Adapter Contract.
4136
+ *
4137
+ * Each instruction represents a contract call (swap, fee collection, etc.)
4138
+ * with pre-execution approval and post-execution validation.
4139
+ *
4140
+ * @example
4141
+ * ```typescript
4142
+ * const swapInstruction: Instruction = {
4143
+ * target: '0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE', // LiFi Diamond
4144
+ * data: '0x...', // LiFi swap calldata
4145
+ * value: 0n,
4146
+ * tokenIn: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
4147
+ * amountToApprove: 1000000000n, // 1000 USDC to approve
4148
+ * tokenOut: '0xdAC17F958D2ee523a2206206994597C13D831ec7', // USDT
4149
+ * minTokenOut: 995000000n // 995 USDT minimum (0.5% slippage)
4150
+ * }
4151
+ * ```
4152
+ */
4153
+ interface Instruction {
4154
+ /**
4155
+ * Target contract address to call.
4156
+ *
4157
+ * Can be a DEX router, fee taker contract, or token contract.
4158
+ */
4159
+ target: `0x${string}`;
4160
+ /**
4161
+ * ABI-encoded calldata for the target contract.
4162
+ */
4163
+ data: `0x${string}`;
4164
+ /**
4165
+ * ETH value to send with the call (for native token operations).
4166
+ *
4167
+ * @defaultValue 0n
4168
+ */
4169
+ value: bigint;
4170
+ /**
4171
+ * Token to approve to target before executing instruction.
4172
+ *
4173
+ * Set to zero address (0x00...00) to disable pre-approval.
4174
+ */
4175
+ tokenIn: `0x${string}`;
4176
+ /**
4177
+ * Amount of tokenIn to approve to target before executing instruction.
4178
+ *
4179
+ * @remarks
4180
+ * Field name matches the adapter contract's `amountToApprove` parameter exactly.
4181
+ *
4182
+ * @defaultValue 0n if tokenIn is zero address
4183
+ */
4184
+ amountToApprove: bigint;
4185
+ /**
4186
+ * Token to validate minimum balance after instruction.
4187
+ *
4188
+ * Set to zero address (0x00...00) to disable post-validation.
4189
+ */
4190
+ tokenOut: `0x${string}`;
4191
+ /**
4192
+ * Minimum required balance of tokenOut after instruction.
4193
+ *
4194
+ * @defaultValue 0n if tokenOut is zero address
4195
+ */
4196
+ minTokenOut: bigint;
4197
+ }
4198
+ /**
4199
+ * Token recipient for residual sweep.
4200
+ *
4201
+ * After all instructions complete, the Adapter Contract sweeps
4202
+ * any remaining balances to the specified beneficiaries.
4203
+ */
4204
+ interface TokenRecipient {
4205
+ /**
4206
+ * Token contract address to sweep.
4207
+ */
4208
+ token: `0x${string}`;
4209
+ /**
4210
+ * Address to receive swept tokens.
4211
+ */
4212
+ beneficiary: `0x${string}`;
4213
+ }
4214
+ /**
4215
+ * Execution parameters for the Adapter Contract.
4216
+ *
4217
+ * This struct is signed via EIP-712 by the Circle proxy and verified
4218
+ * on-chain to ensure the execution is authorized.
4219
+ *
4220
+ * @remarks
4221
+ * The executeParams are provided by the stablecoin-service and must be
4222
+ * passed to the Adapter Contract exactly as received (no modification).
4223
+ *
4224
+ * @example
4225
+ * ```typescript
4226
+ * const executeParams: ExecuteParams = {
4227
+ * instructions: [
4228
+ * { target: dexRouter, data: swapCalldata, ... }
4229
+ * ],
4230
+ * tokens: [
4231
+ * { token: USDC, beneficiary: userAddress },
4232
+ * { token: USDT, beneficiary: userAddress }
4233
+ * ],
4234
+ * execId: 123456789n,
4235
+ * deadline: BigInt(Math.floor(Date.now() / 1000) + 1800),
4236
+ * metadata: '0x'
4237
+ * }
4238
+ * ```
4239
+ */
4240
+ interface ExecuteParams {
4241
+ /**
4242
+ * Array of instructions to execute sequentially.
4243
+ *
4244
+ * Each instruction can be a swap, fee collection, or other contract call.
4245
+ */
4246
+ instructions: Instruction[];
4247
+ /**
4248
+ * Token recipients for residual sweep.
4249
+ *
4250
+ * Typically a 2-tuple: [tokenIn recipient, tokenOut recipient]
4251
+ */
4252
+ tokens: TokenRecipient[];
4253
+ /**
4254
+ * Unique execution identifier for replay protection.
4255
+ *
4256
+ * Must be globally unique and is marked as used after execution.
4257
+ */
4258
+ execId: bigint;
4259
+ /**
4260
+ * Execution deadline timestamp (Unix seconds).
4261
+ *
4262
+ * Transaction reverts if block.timestamp is greater than deadline.
4263
+ */
4264
+ deadline: bigint;
4265
+ /**
4266
+ * Optional metadata for tracking and analytics.
4267
+ */
4268
+ metadata: `0x${string}`;
4269
+ }
4270
+ /**
4271
+ * Parameters for executing a swap transaction via the Adapter smart contract.
4272
+ *
4273
+ * This action executes swap transactions through the Adapter Contract, which
4274
+ * handles token approvals via permits (EIP-2612, Permit2, etc.) and executes
4275
+ * multi-step swap instructions atomically on-chain.
4276
+ *
4277
+ * @remarks
4278
+ * The swap flow uses the Adapter Contract pattern:
4279
+ * 1. Service provides `executeParams` and `signature` (proxy-signed EIP-712)
4280
+ * 2. SDK builds `tokenInputs` with permit signatures for gasless approvals
4281
+ * 3. SDK calls AdapterContract.execute(executeParams, tokenInputs, signature)
4282
+ * 4. Adapter Contract pulls tokens via permits, executes swaps, validates outputs
4283
+ *
4284
+ * This enables:
4285
+ * - Single atomic transaction (permit + swap in one tx)
4286
+ * - Gasless approvals via EIP-2612/Permit2
4287
+ * - Slippage protection enforced on-chain
4288
+ * - Multi-step instructions (swap + fees) atomically
4289
+ *
4290
+ * **Permit Support**: The SDK constructs `TokenInput` with `permitCalldata`
4291
+ * containing the encoded permit signature. The Adapter Contract executes
4292
+ * the permit on-chain before pulling tokens.
4293
+ *
4294
+ * @example
4295
+ * ```typescript
4296
+ * import type { ExecuteSwapParams } from '@core/adapter'
4297
+ * import { createSwap } from '@core/service-client'
4298
+ * import { PermitType } from '@core/adapter'
4299
+ *
4300
+ * // Get swap transaction from service
4301
+ * const swapResponse = await createSwap({
4302
+ * tokenInAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
4303
+ * tokenOutAddress: '0xdAC17F958D2ee523a2206206994597C13D831ec7',
4304
+ * tokenInChain: 'Ethereum',
4305
+ * fromAddress: '0x...',
4306
+ * toAddress: '0x...',
4307
+ * amount: '1000000',
4308
+ * apiKey: 'KIT_KEY:...',
4309
+ * })
4310
+ *
4311
+ * // Build token inputs with permit
4312
+ * const tokenInputs: TokenInput[] = [{
4313
+ * permitType: PermitType.EIP2612,
4314
+ * token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
4315
+ * from: userAddress,
4316
+ * amount: 1000000n,
4317
+ * permitCalldata: '0x...' // Encoded permit signature
4318
+ * }]
4319
+ *
4320
+ * // Prepare action parameters
4321
+ * const params: ExecuteSwapParams = {
4322
+ * executeParams: swapResponse.transaction.executeParams,
4323
+ * tokenInputs,
4324
+ * signature: swapResponse.transaction.signature,
4325
+ * inputAmount: BigInt(swapResponse.amount),
4326
+ * tokenInAddress: swapResponse.tokenInAddress as `0x${string}`
4327
+ * }
4328
+ * ```
4329
+ */
4330
+ interface ExecuteSwapEVMParams extends ActionParameters {
4331
+ /**
4332
+ * Execution parameters from the stablecoin-service.
4333
+ *
4334
+ * Contains instructions, token recipients, execution ID, deadline, and metadata.
4335
+ * This is an EIP-712 signed struct that the Adapter Contract validates.
4336
+ *
4337
+ * Provided by the service - do not modify.
4338
+ */
4339
+ executeParams: ExecuteParams;
4340
+ /**
4341
+ * Token inputs with permit signatures for gasless approvals.
4342
+ *
4343
+ * The SDK constructs this array with permit data for each token that needs
4344
+ * to be pulled from the user's wallet. The Adapter Contract executes these
4345
+ * permits on-chain before executing swap instructions.
4346
+ *
4347
+ * @remarks
4348
+ * For EIP-2612 permits, the SDK must:
4349
+ * 1. Build typed data with token, spender (Adapter), amount, nonce, deadline
4350
+ * 2. Get user signature via `adapter.signTypedData()`
4351
+ * 3. Encode as permitCalldata: encode(value, deadline, v, r, s)
4352
+ *
4353
+ * @example
4354
+ * ```typescript
4355
+ * [{
4356
+ * permitType: PermitType.EIP2612,
4357
+ * token: '0xUSDC',
4358
+ * from: userAddress,
4359
+ * amount: 1000000n,
4360
+ * permitCalldata: '0x...'
4361
+ * }]
4362
+ * ```
4363
+ */
4364
+ tokenInputs: TokenInput[];
4365
+ /**
4366
+ * EIP-712 signature from the Circle proxy service.
4367
+ *
4368
+ * The service signs the executeParams to authorize the execution.
4369
+ * The Adapter Contract verifies this signature on-chain.
4370
+ *
4371
+ * Provided by the service - do not modify.
4372
+ */
4373
+ signature: `0x${string}`;
4374
+ /**
4375
+ * Swap input amount in base units.
4376
+ *
4377
+ * @remarks
4378
+ * The amount of tokens being swapped, provided in the token's base units (e.g., wei for ETH,
4379
+ * smallest denomination for ERC20 tokens). This value should be extracted from the service
4380
+ * response, as it represents the authoritative swap amount for the operation.
4381
+ *
4382
+ * For native currency swaps (ETH → USDC), this amount is sent as the transaction `value`.
4383
+ * For ERC20 swaps (USDC → USDT), this amount determines the permit or approval quantity.
4384
+ *
4385
+ * @see CreateSwapResponse.amount - Service response field containing this value
4386
+ *
4387
+ * @example
4388
+ * ```typescript
4389
+ * import { createSwap } from '@core/service-client'
4390
+ *
4391
+ * // Get swap transaction from service
4392
+ * const response = await createSwap({
4393
+ * tokenInAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
4394
+ * amount: '1000000', // 1 USDC (6 decimals)
4395
+ * ...
4396
+ * })
4397
+ *
4398
+ * // Prepare swap execution using service response amount
4399
+ * await adapter.prepareAction('swap.execute', {
4400
+ * executeParams: response.transaction.executeParams,
4401
+ * tokenInputs,
4402
+ * signature: response.transaction.signature,
4403
+ * inputAmount: BigInt(response.amount),
4404
+ * tokenInAddress: response.tokenInAddress,
4405
+ * }, context)
4406
+ * ```
4407
+ */
4408
+ inputAmount: bigint;
4409
+ /**
4410
+ * Token address being swapped from.
4411
+ *
4412
+ * @remarks
4413
+ * Used to determine if the swap involves native currency (ETH, MATIC, etc.) or ERC20 tokens.
4414
+ * When tokenInAddress is NATIVE_TOKEN_ADDRESS (0xEeee...), the inputAmount is sent as tx.value.
4415
+ *
4416
+ * @see CreateSwapResponse.tokenInAddress - Service response field containing this value
4417
+ *
4418
+ * @example '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE' for ETH
4419
+ * @example '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' for USDC
4420
+ */
4421
+ tokenInAddress: `0x${string}`;
4422
+ }
4423
+ /**
4424
+ * Parameters for executing a swap transaction on Solana.
4425
+ *
4426
+ * This action executes swap transactions on Solana chains by deserializing
4427
+ * and executing a pre-built transaction provided by the stablecoin-service.
4428
+ *
4429
+ * @remarks
4430
+ * Unlike EVM chains that use the Adapter Contract pattern, Solana swaps
4431
+ * execute a fully serialized transaction provided by the service. The
4432
+ * transaction is base64-encoded and contains all necessary instructions
4433
+ * for the swap operation.
4434
+ *
4435
+ * The service handles:
4436
+ * - DEX aggregator routing (Jupiter, etc.)
4437
+ * - Fee collection
4438
+ * - Slippage protection
4439
+ * - Token account management
4440
+ *
4441
+ * @example
4442
+ * ```typescript
4443
+ * import type { ExecuteSwapSolanaParams } from '@core/adapter'
4444
+ * import { createSwap } from '@core/service-client'
4445
+ *
4446
+ * // Get swap transaction from service
4447
+ * const swapResponse = await createSwap({
4448
+ * tokenInAddress: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
4449
+ * tokenOutAddress: 'HzwqbKZw8HxMN6bF2yFZNrht3c2iXXzpKcFu7uBEDKtr',
4450
+ * tokenInChain: 'Solana',
4451
+ * fromAddress: 'YubQzu18FDqJRyNfG8JqHmsdbxhnoQqcKUHBdUkN6tP',
4452
+ * toAddress: 'YubQzu18FDqJRyNfG8JqHmsdbxhnoQqcKUHBdUkN6tP',
4453
+ * amount: '1000000',
4454
+ * apiKey: 'KIT_KEY:...',
4455
+ * })
4456
+ *
4457
+ * // Prepare action parameters
4458
+ * const params: ExecuteSwapSolanaParams = {
4459
+ * serializedTransaction: swapResponse.transaction.data
4460
+ * }
4461
+ * ```
4462
+ */
4463
+ interface ExecuteSwapSolanaParams extends ActionParameters {
4464
+ /**
4465
+ * Base64-encoded serialized Solana transaction.
4466
+ *
4467
+ * This transaction is fully constructed by the stablecoin-service and
4468
+ * contains all swap instructions, fee payments, and token account setup.
4469
+ * The transaction must be deserialized, signed, and submitted to the network.
4470
+ *
4471
+ * Provided by the service - do not modify.
4472
+ *
4473
+ * @example 'AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAAQAJFQg...'
4474
+ */
4475
+ serializedTransaction: string;
4476
+ }
4477
+ /**
4478
+ * Parameters accepted by the swap.execute action, supporting both EVM and Solana chains.
4479
+ *
4480
+ * @remarks
4481
+ * This union type covers all chain-specific swap execution parameter interfaces
4482
+ * currently supported by the App Kit. Extend this union to support
4483
+ * additional blockchains as needed. Each member provides all fields required
4484
+ * to prepare and execute a pre-built swap transaction on its respective chain.
4485
+ *
4486
+ * **Type Narrowing**: The correct parameter type is inferred from the chain type
4487
+ * in the `OperationContext` passed to `adapter.prepareAction()`. Action handlers
4488
+ * use property-based type guards (checking for `executeParams`/`tokenInputs` for EVM
4489
+ * or `serializedTransaction` for Solana) to narrow the union type at runtime.
4490
+ *
4491
+ * - {@link ExecuteSwapEVMParams} - For EVM chains (has `executeParams` and `tokenInputs`)
4492
+ * - {@link ExecuteSwapSolanaParams} - For Solana chains (has `serializedTransaction`)
4493
+ */
4494
+ type ExecuteSwapParams = ExecuteSwapEVMParams | ExecuteSwapSolanaParams;
4495
+ /**
4496
+ * Action map for swap operations on EVM chains.
4497
+ *
4498
+ * This namespace contains actions related to token swapping operations.
4499
+ * These actions handle the execution of pre-built swap transactions from
4500
+ * DEX aggregators and routing services.
4501
+ *
4502
+ * @remarks
4503
+ * The swap namespace is designed to be extensible for future swap-related
4504
+ * operations such as multi-hop swaps, batched swaps, or swap-and-bridge
4505
+ * compositions.
4506
+ */
4507
+ interface SwapActionMap {
4508
+ /**
4509
+ * Execute a pre-built swap transaction.
4510
+ *
4511
+ * This action prepares and executes swap transactions constructed by the
4512
+ * stablecoin-service API. It accepts transaction parameters (to, data, value)
4513
+ * and returns a prepared chain request suitable for gas estimation or execution.
4514
+ */
4515
+ readonly execute: ExecuteSwapParams;
3961
4516
  }
3962
4517
 
3963
4518
  interface TokenActionMap {
@@ -4172,6 +4727,81 @@ interface USDCActionMap {
4172
4727
  balanceOf: Omit<BaseUSDCActions['balanceOf'], 'tokenAddress'>;
4173
4728
  }
4174
4729
 
4730
+ /**
4731
+ * USDT-specific operations that automatically resolve the token address.
4732
+ *
4733
+ * These include standard ERC20 operations. The interface provides the same core
4734
+ * operations as {@link TokenActionMap} but without requiring a `tokenAddress`
4735
+ * parameter.
4736
+ *
4737
+ * @example
4738
+ * ```typescript
4739
+ * // USDT operations (address auto-resolved)
4740
+ * await adapter.action('usdt.transfer', {
4741
+ * to: '0x1234...',
4742
+ * amount: '1000000' // 1 USDT
4743
+ * })
4744
+ *
4745
+ * // vs. general token operations (address required)
4746
+ * await adapter.action('token.transfer', {
4747
+ * tokenAddress: '0xdAC17F958D2ee523a2206206994597C13D831ec7',
4748
+ * to: '0x1234...',
4749
+ * amount: '1000000'
4750
+ * })
4751
+ * ```
4752
+ */
4753
+ type BaseUSDTActions = {
4754
+ [K in keyof TokenActionMap]: Omit<TokenActionMap[K], 'tokenAddress'>;
4755
+ };
4756
+ /**
4757
+ * USDT action map with standard ERC20 operations.
4758
+ *
4759
+ * This provides standard token operations for USDT transfers.
4760
+ */
4761
+ interface USDTActionMap {
4762
+ /**
4763
+ * Transfer USDT tokens directly from the wallet to another address.
4764
+ *
4765
+ * Automatically uses the USDT contract address for the current chain.
4766
+ */
4767
+ transfer: BaseUSDTActions['transfer'];
4768
+ }
4769
+
4770
+ /**
4771
+ * Native token-related action maps for the bridge kit.
4772
+ *
4773
+ * This module provides action definitions for native token operations.
4774
+ */
4775
+ interface NativeActionMap {
4776
+ /**
4777
+ * Transfer native tokens directly from the wallet to another address.
4778
+ */
4779
+ transfer: ActionParameters & {
4780
+ /**
4781
+ * The chain to transfer the native tokens on.
4782
+ */
4783
+ chain?: ChainIdentifier$1;
4784
+ /**
4785
+ * The address to send the native tokens to.
4786
+ */
4787
+ to: string;
4788
+ /**
4789
+ * The amount of native tokens to transfer.
4790
+ */
4791
+ amount: bigint;
4792
+ };
4793
+ /**
4794
+ * Get the native token balance (SOL, ETH, etc.) for a wallet address.
4795
+ */
4796
+ balanceOf: ActionParameters & {
4797
+ /**
4798
+ * The address to check the native balance for. If not provided, it will be
4799
+ * automatically derived from the adapter context.
4800
+ */
4801
+ walletAddress?: string | undefined;
4802
+ };
4803
+ }
4804
+
4175
4805
  /**
4176
4806
  * Central registry of all available action namespaces and their operations.
4177
4807
  *
@@ -4191,12 +4821,16 @@ interface USDCActionMap {
4191
4821
  interface ActionMap {
4192
4822
  /** CCTP-specific operations with automatic address resolution. */
4193
4823
  readonly cctp: CCTPActionMap;
4194
- /** Native token operations (ETH, SOL, MATIC, etc.). */
4195
- readonly native: NativeActionMap;
4196
4824
  /** General token operations requiring explicit token addresses. */
4197
4825
  readonly token: TokenActionMap;
4198
4826
  /** USDC-specific operations with automatic address resolution. */
4199
4827
  readonly usdc: USDCActionMap;
4828
+ /** USDT-specific operations with automatic address resolution. */
4829
+ readonly usdt: USDTActionMap;
4830
+ /** Native token operations. */
4831
+ readonly native: NativeActionMap;
4832
+ /** Swap operations for DEX aggregator integrations. */
4833
+ readonly swap: SwapActionMap;
4200
4834
  }
4201
4835
  /**
4202
4836
  * Determine if a type represents an action parameter object (leaf node).
@@ -4335,7 +4969,7 @@ type ActionHandler$1<TActionKey extends ActionKeys> = (params: ActionPayload<TAc
4335
4969
  * This type defines a registry object where each key is a valid action key
4336
4970
  * (as defined by {@link ActionKeys}) and each value is an {@link ActionHandler}
4337
4971
  * capable of processing the payload for that action. This enables strongly-typed
4338
- * handler registration and lookup for all supported actions in the Stablecoin Kits.
4972
+ * handler registration and lookup for all supported actions in the App Kits.
4339
4973
  *
4340
4974
  * @remarks
4341
4975
  * Each handler is typed as {@link ActionHandler}, which means the handler
@@ -4597,11 +5231,11 @@ interface AdapterCapabilities {
4597
5231
  /**
4598
5232
  * Abstract class defining the standard interface for an adapter that interacts with a specific blockchain.
4599
5233
  *
4600
- * A `Adapter` is responsible for encapsulating chain-specific logic necessary to
5234
+ * An `Adapter` is responsible for encapsulating chain-specific logic necessary to
4601
5235
  * perform operations like sending transactions, querying balances, or interacting with smart contracts.
4602
5236
  * Implementations of this class will provide concrete logic for a particular blockchain protocol.
4603
5237
  *
4604
- * This abstraction allows the Stablecoin Kits to work with multiple blockchains in a uniform way.
5238
+ * This abstraction allows the App Kit to work with multiple blockchains in a uniform way.
4605
5239
  *
4606
5240
  * @typeParam TAdapterCapabilities - The adapter capabilities type for compile-time address validation.
4607
5241
  * When provided, enables strict typing of operation context based on the adapter's address control model.
@@ -4862,6 +5496,35 @@ declare abstract class Adapter<TAdapterCapabilities extends AdapterCapabilities
4862
5496
  * @returns A promise that resolves to the total transaction fee as a bigint.
4863
5497
  */
4864
5498
  abstract calculateTransactionFee(baseComputeUnits: bigint, bufferBasisPoints: bigint | undefined, chain: ChainDefinition): Promise<EstimatedGas>;
5499
+ /**
5500
+ * Get the decimal places for a token address on a given chain.
5501
+ *
5502
+ * This method fetches the number of decimal places from a token contract.
5503
+ * Different chain types implement this differently:
5504
+ * - EVM: Calls the `decimals()` function on ERC-20 contracts
5505
+ * - Solana: Reads the `decimals` field from the SPL token mint account
5506
+ *
5507
+ * @param tokenAddress - The token contract address (EVM) or mint address (Solana)
5508
+ * @param chain - The chain definition where the token is deployed
5509
+ * @returns Promise resolving to the number of decimal places for the token
5510
+ * @throws Error when the token contract doesn't exist or decimals cannot be fetched
5511
+ *
5512
+ * @example
5513
+ * ```typescript
5514
+ * import { EthersAdapter } from '@circle-fin/adapter-ethers-v6'
5515
+ * import { Ethereum } from '@core/chains'
5516
+ *
5517
+ * const adapter = new EthersAdapter({ signer })
5518
+ *
5519
+ * // Fetch decimals for DAI token
5520
+ * const decimals = await adapter.getTokenDecimals(
5521
+ * '0x6B175474E89094C44Da98b954EedeAC495271d0F',
5522
+ * Ethereum
5523
+ * )
5524
+ * console.log(decimals) // 18
5525
+ * ```
5526
+ */
5527
+ abstract getTokenDecimals(tokenAddress: string, chain: ChainDefinition): Promise<number>;
4865
5528
  }
4866
5529
 
4867
5530
  /**
@@ -5051,6 +5714,20 @@ declare module './types' {
5051
5714
  */
5052
5715
  interface TokenSymbolRegistry {
5053
5716
  USDC: true;
5717
+ USDT: true;
5718
+ EURC: true;
5719
+ DAI: true;
5720
+ USDE: true;
5721
+ PYUSD: true;
5722
+ WETH: true;
5723
+ WBTC: true;
5724
+ WSOL: true;
5725
+ WAVAX: true;
5726
+ WPOL: true;
5727
+ ETH: true;
5728
+ POL: true;
5729
+ PLUME: true;
5730
+ MON: true;
5054
5731
  }
5055
5732
  }
5056
5733
 
@@ -5228,7 +5905,8 @@ interface TokenDefinition {
5228
5905
  */
5229
5906
  readonly symbol: string;
5230
5907
  /**
5231
- * The number of decimal places for the token.
5908
+ * The default number of decimal places for the token.
5909
+ * Used when no chain-specific override exists in {@link chainDecimals}.
5232
5910
  * @example 6 for USDC, 18 for most ERC20 tokens
5233
5911
  */
5234
5912
  readonly decimals: number;
@@ -5238,6 +5916,15 @@ interface TokenDefinition {
5238
5916
  * Not all chains need to be present - tokens may only exist on a subset of chains.
5239
5917
  */
5240
5918
  readonly locators: Partial<ChainLocatorMap>;
5919
+ /**
5920
+ * Optional per-chain decimal overrides.
5921
+ *
5922
+ * Some tokens have different decimal places on different chains
5923
+ * (e.g., USDe is 18 decimals on EVM but 9 decimals on Solana).
5924
+ * When present, the value for a specific chain takes precedence
5925
+ * over the default {@link decimals}.
5926
+ */
5927
+ readonly chainDecimals?: Partial<Record<ChainIdentifier, number>>;
5241
5928
  }
5242
5929
  /**
5243
5930
  * A raw token locator selector with explicit decimals.
@@ -5432,6 +6119,15 @@ interface TokenRegistry {
5432
6119
  * @throws When the token cannot be resolved (unknown symbol, missing decimals, etc.).
5433
6120
  */
5434
6121
  resolve(selector: TokenSelector, chainId: ChainIdentifier): ResolvedToken;
6122
+ /**
6123
+ * Resolve a token by chain-specific locator (address/program ID).
6124
+ *
6125
+ * @param address - The token locator to resolve.
6126
+ * @param chainId - The chain identifier to resolve for.
6127
+ * @returns The resolved token information.
6128
+ * @throws When no registry token matches the locator on the chain.
6129
+ */
6130
+ resolveByAddress(address: string, chainId: ChainIdentifier): ResolvedToken;
5435
6131
  /**
5436
6132
  * Get a token definition by symbol.
5437
6133
  *
@@ -5480,7 +6176,7 @@ type Recoverability = (typeof RECOVERABILITY_VALUES)[number];
5480
6176
  * Array of valid error type values for validation.
5481
6177
  * Derived from ERROR_TYPES const object.
5482
6178
  */
5483
- declare const ERROR_TYPE_VALUES: ("INPUT" | "BALANCE" | "ONCHAIN" | "RPC" | "NETWORK" | "UNKNOWN")[];
6179
+ declare const ERROR_TYPE_VALUES: ("INPUT" | "BALANCE" | "ONCHAIN" | "RPC" | "NETWORK" | "RATE_LIMIT" | "SERVICE" | "UNKNOWN")[];
5484
6180
  /**
5485
6181
  * Error type indicating the category of the error.
5486
6182
  */
@@ -5489,7 +6185,7 @@ type ErrorType = (typeof ERROR_TYPE_VALUES)[number];
5489
6185
  * Structured error details with consistent properties for programmatic handling.
5490
6186
  *
5491
6187
  * This interface provides a standardized format for all errors in the
5492
- * Stablecoin Kits system, enabling developers to handle different error
6188
+ * App Kits system, enabling developers to handle different error
5493
6189
  * types consistently and provide appropriate user feedback.
5494
6190
  *
5495
6191
  * @example
@@ -5539,11 +6235,11 @@ interface ErrorDetails {
5539
6235
  }
5540
6236
 
5541
6237
  /**
5542
- * Structured error class for Stablecoin Kit operations.
6238
+ * Structured error class for App Kit operations.
5543
6239
  *
5544
6240
  * This class extends the native Error class while implementing the ErrorDetails
5545
6241
  * interface, providing a consistent error format for programmatic handling
5546
- * across the Stablecoin Kits ecosystem. All properties are immutable to ensure
6242
+ * across the App Kits ecosystem. All properties are immutable to ensure
5547
6243
  * error objects cannot be modified after creation.
5548
6244
  *
5549
6245
  * @example
@@ -5553,6 +6249,7 @@ interface ErrorDetails {
5553
6249
  * const error = new KitError({
5554
6250
  * code: 1001,
5555
6251
  * name: 'INPUT_NETWORK_MISMATCH',
6252
+ * type: 'INPUT',
5556
6253
  * recoverability: 'FATAL',
5557
6254
  * message: 'Cannot bridge between mainnet and testnet'
5558
6255
  * })
@@ -5570,7 +6267,8 @@ interface ErrorDetails {
5570
6267
  * // Error with cause information
5571
6268
  * const error = new KitError({
5572
6269
  * code: 1002,
5573
- * name: 'INVALID_AMOUNT',
6270
+ * name: 'INPUT_INVALID_AMOUNT',
6271
+ * type: 'INPUT',
5574
6272
  * recoverability: 'FATAL',
5575
6273
  * message: 'Amount must be greater than zero',
5576
6274
  * cause: {
@@ -5612,6 +6310,8 @@ declare class KitError extends Error implements ErrorDetails {
5612
6310
  * - 3000-3999: NETWORK errors - Internet connectivity, DNS, connection issues
5613
6311
  * - 4000-4999: RPC errors - Blockchain provider issues, gas estimation, nonce errors
5614
6312
  * - 5000-5999: ONCHAIN errors - Transaction/simulation failures, gas exhaustion, reverts
6313
+ * - 7000-7999: RATE_LIMIT errors - API throttling, request frequency limits
6314
+ * - 8000-8999: SERVICE errors - Internal service errors, server failures
5615
6315
  * - 9000-9999: BALANCE errors - Insufficient funds, token balance, allowance
5616
6316
  */
5617
6317
  /**
@@ -5672,10 +6372,22 @@ declare const InputError: {
5672
6372
  readonly name: "INPUT_INVALID_CHAIN";
5673
6373
  readonly type: ErrorType;
5674
6374
  };
5675
- /** Invalid or unknown token (symbol not found, missing decimals, etc.) */
5676
- readonly INVALID_TOKEN: {
6375
+ /** Unsupported token for chain */
6376
+ readonly UNSUPPORTED_TOKEN: {
5677
6377
  readonly code: 1006;
5678
- readonly name: "INPUT_INVALID_TOKEN";
6378
+ readonly name: "INPUT_UNSUPPORTED_TOKEN";
6379
+ readonly type: ErrorType;
6380
+ };
6381
+ /** Insufficient swap amount for the token pair */
6382
+ readonly INSUFFICIENT_SWAP_AMOUNT: {
6383
+ readonly code: 1007;
6384
+ readonly name: "INPUT_INSUFFICIENT_SWAP_AMOUNT";
6385
+ readonly type: ErrorType;
6386
+ };
6387
+ /** Action not supported by this adapter / ecosystem */
6388
+ readonly UNSUPPORTED_ACTION: {
6389
+ readonly code: 1008;
6390
+ readonly name: "INPUT_UNSUPPORTED_ACTION";
5679
6391
  readonly type: ErrorType;
5680
6392
  };
5681
6393
  /** General validation failure for complex validation rules */
@@ -5684,6 +6396,12 @@ declare const InputError: {
5684
6396
  readonly name: "INPUT_VALIDATION_FAILED";
5685
6397
  readonly type: ErrorType;
5686
6398
  };
6399
+ /** User cancelled wallet interaction (signature, transaction, connection) */
6400
+ readonly USER_CANCELLED: {
6401
+ readonly code: 1099;
6402
+ readonly name: "INPUT_USER_CANCELLED";
6403
+ readonly type: ErrorType;
6404
+ };
5687
6405
  };
5688
6406
  /**
5689
6407
  * Standardized error definitions for BALANCE type errors.
@@ -5766,6 +6484,18 @@ declare const OnchainError: {
5766
6484
  readonly name: "ONCHAIN_GAS_LIMIT_EXCEEDED";
5767
6485
  readonly type: ErrorType;
5768
6486
  };
6487
+ /** Transaction size exceeds blockchain limit */
6488
+ readonly TRANSACTION_TOO_LARGE: {
6489
+ readonly code: 5005;
6490
+ readonly name: "ONCHAIN_TRANSACTION_TOO_LARGE";
6491
+ readonly type: ErrorType;
6492
+ };
6493
+ /** Unknown blockchain error that cannot be categorized */
6494
+ readonly UNKNOWN_BLOCKCHAIN_ERROR: {
6495
+ readonly code: 5099;
6496
+ readonly name: "ONCHAIN_UNKNOWN_BLOCKCHAIN_ERROR";
6497
+ readonly type: ErrorType;
6498
+ };
5769
6499
  };
5770
6500
  /**
5771
6501
  * Standardized error definitions for RPC type errors.
@@ -5848,6 +6578,75 @@ declare const NetworkError: {
5848
6578
  readonly name: "NETWORK_RELAYER_PENDING";
5849
6579
  readonly type: ErrorType;
5850
6580
  };
6581
+ /** LI.FI swap status is pending — waiting for indexing or completion */
6582
+ readonly LIFI_STATUS_PENDING: {
6583
+ readonly code: 3005;
6584
+ readonly name: "NETWORK_LIFI_STATUS_PENDING";
6585
+ readonly type: ErrorType;
6586
+ };
6587
+ /** LI.FI swap status returned a terminal failure */
6588
+ readonly LIFI_STATUS_FAILED: {
6589
+ readonly code: 3006;
6590
+ readonly name: "NETWORK_LIFI_STATUS_FAILED";
6591
+ readonly type: ErrorType;
6592
+ };
6593
+ };
6594
+ /**
6595
+ * Standardized error definitions for RATE_LIMIT type errors.
6596
+ *
6597
+ * RATE_LIMIT errors indicate API throttling, request frequency limits errors.
6598
+ *
6599
+ * @example
6600
+ * ```typescript
6601
+ * import { RateLimitError } from '@core/errors'
6602
+ *
6603
+ * const error = new KitError({
6604
+ * ...RateLimitError.RATE_LIMIT_EXCEEDED,
6605
+ * recoverability: 'RETRYABLE',
6606
+ * message: 'Rate limit exceeded, please retry later',
6607
+ * cause: { trace: { error: '429 Too Many Requests' } }
6608
+ * })
6609
+ * ```
6610
+ */
6611
+ declare const RateLimitError: {
6612
+ /** Rate limit exceeded */
6613
+ readonly RATE_LIMIT_EXCEEDED: {
6614
+ readonly code: 7001;
6615
+ readonly name: "RATE_LIMIT_EXCEEDED";
6616
+ readonly type: ErrorType;
6617
+ };
6618
+ };
6619
+ /**
6620
+ * Standardized error definitions for SERVICE type errors.
6621
+ *
6622
+ * SERVICE errors indicate internal service failures, HTTP 5xx errors,
6623
+ * or backend processing issues that are retryable.
6624
+ *
6625
+ * @example
6626
+ * ```typescript
6627
+ * import { ServiceError } from '@core/errors'
6628
+ *
6629
+ * const error = new KitError({
6630
+ * ...ServiceError.INTERNAL_ERROR,
6631
+ * recoverability: 'RETRYABLE',
6632
+ * message: 'Service encountered an internal error (500)',
6633
+ * cause: { trace: { statusCode: 500 } }
6634
+ * })
6635
+ * ```
6636
+ */
6637
+ declare const ServiceError: {
6638
+ /** Internal server error (HTTP 5xx) */
6639
+ readonly INTERNAL_ERROR: {
6640
+ readonly code: 8001;
6641
+ readonly name: "SERVICE_INTERNAL_ERROR";
6642
+ readonly type: ErrorType;
6643
+ };
6644
+ /** Unknown or unclassified error that cannot be categorized */
6645
+ readonly UNKNOWN_ERROR: {
6646
+ readonly code: 8002;
6647
+ readonly name: "SERVICE_UNKNOWN_ERROR";
6648
+ readonly type: ErrorType;
6649
+ };
5851
6650
  };
5852
6651
 
5853
6652
  /**
@@ -5956,7 +6755,7 @@ declare function isFatalError(error: unknown): boolean;
5956
6755
  * // KitError with non-retryable code and FATAL recoverability
5957
6756
  * const error3 = new KitError({
5958
6757
  * code: 1001,
5959
- * name: 'INVALID_INPUT',
6758
+ * name: 'INPUT_NETWORK_MISMATCH',
5960
6759
  * type: 'INPUT',
5961
6760
  * recoverability: 'FATAL',
5962
6761
  * message: 'Invalid input',
@@ -6094,6 +6893,56 @@ declare function isRpcError(error: unknown): error is KitError;
6094
6893
  * ```
6095
6894
  */
6096
6895
  declare function isNetworkError(error: unknown): error is KitError;
6896
+ /**
6897
+ * Type guard to check if error is KitError with RATE_LIMIT type.
6898
+ *
6899
+ * RATE_LIMIT errors indicate API throttling or request frequency limits.
6900
+ * These errors are typically RETRYABLE after a delay.
6901
+ *
6902
+ * @param error - Unknown error to check
6903
+ * @returns True if error is KitError with RATE_LIMIT type
6904
+ *
6905
+ * @example
6906
+ * ```typescript
6907
+ * import { isRateLimitError } from '@core/errors'
6908
+ *
6909
+ * try {
6910
+ * await kit.bridge(params)
6911
+ * } catch (error) {
6912
+ * if (isRateLimitError(error)) {
6913
+ * console.log('Rate limited, retrying in 60s')
6914
+ * await sleep(60000)
6915
+ * retry()
6916
+ * }
6917
+ * }
6918
+ * ```
6919
+ */
6920
+ declare function isRateLimitError(error: unknown): error is KitError;
6921
+ /**
6922
+ * Type guard to check if error is KitError with SERVICE type.
6923
+ *
6924
+ * SERVICE errors indicate internal service failures or HTTP 5xx errors.
6925
+ * These errors are typically RETRYABLE as they indicate temporary
6926
+ * backend issues.
6927
+ *
6928
+ * @param error - Unknown error to check
6929
+ * @returns True if error is KitError with SERVICE type
6930
+ *
6931
+ * @example
6932
+ * ```typescript
6933
+ * import { isServiceError } from '@core/errors'
6934
+ *
6935
+ * try {
6936
+ * await kit.bridge(params)
6937
+ * } catch (error) {
6938
+ * if (isServiceError(error)) {
6939
+ * console.log('Service error:', error.message)
6940
+ * retryWithBackoff()
6941
+ * }
6942
+ * }
6943
+ * ```
6944
+ */
6945
+ declare function isServiceError(error: unknown): error is KitError;
6097
6946
  /**
6098
6947
  * Safely extracts error message from any error type.
6099
6948
  *
@@ -6545,7 +7394,7 @@ interface Timer {
6545
7394
  * ```typescript
6546
7395
  * // Create a scoped metrics instance
6547
7396
  * const appMetrics = metrics.child({
6548
- * service: 'stablecoin-kit',
7397
+ * service: 'app-kit',
6549
7398
  * version: '1.0.0',
6550
7399
  * })
6551
7400
  *
@@ -9250,5 +10099,5 @@ declare const bridgeParamsWithChainIdentifierSchema: z.ZodObject<{
9250
10099
  } | undefined;
9251
10100
  }>;
9252
10101
 
9253
- export { BalanceError, Blockchain, BridgeChain, BridgeKit, InputError, KitError, NetworkError, OnchainError, RpcError, TransferSpeed, bridgeParamsWithChainIdentifierSchema, createRuntime, createTokenRegistry, createTraceId, extendInvocationContext, getErrorCode, getErrorMessage, isBalanceError, isFatalError, isInputError, isKitError, isNetworkError, isOnchainError, isRetryableError, isRpcError, resolveChainIdentifier, resolveInvocationContext, setExternalPrefix };
10102
+ export { Arbitrum, ArbitrumSepolia, ArcTestnet, Avalanche, AvalancheFuji, BalanceError, Base, BaseSepolia, Blockchain, BridgeChain, BridgeKit, Codex, CodexTestnet, Ethereum, EthereumSepolia, HyperEVM, HyperEVMTestnet, Ink, InkTestnet, InputError, KitError, Linea, LineaSepolia, Monad, MonadTestnet, NetworkError, OnchainError, Optimism, OptimismSepolia, Plume, PlumeTestnet, Polygon, PolygonAmoy, RateLimitError, RpcError, Sei, SeiTestnet, ServiceError, Solana, SolanaDevnet, Sonic, SonicTestnet, TransferSpeed, Unichain, UnichainSepolia, WorldChain, WorldChainSepolia, XDC, XDCApothem, bridgeParamsWithChainIdentifierSchema, createRuntime, createTokenRegistry, createTraceId, extendInvocationContext, getErrorCode, getErrorMessage, isBalanceError, isFatalError, isInputError, isKitError, isNetworkError, isOnchainError, isRateLimitError, isRetryableError, isRpcError, isServiceError, resolveChainIdentifier, resolveInvocationContext, setExternalPrefix };
9254
10103
  export type { ActionHandler, AdapterContext, BaseChainDefinition, BridgeChainIdentifier, BridgeConfig, BridgeKitConfig, BridgeParams, BridgeResult, CCTPConfig, CCTPContracts, CCTPMergedConfig, CCTPSplitConfig, CCTPV2SupportedChainType, Caller, ChainDefinition, ChainIdentifier$1 as ChainIdentifier, Currency, CustomFeePolicy, EVMChainDefinition, ErrorDetails, EstimateResult, EstimatedGas, GetSupportedChainsOptions, InvocationContext, InvocationDefaults, InvocationMeta, KitContractType, KitContracts, NonEVMChainDefinition, Recoverability, RetryContext, VersionConfig };