hak-axelar-plugin 1.0.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 (9) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +170 -0
  3. package/dist/index.cjs +614 -0
  4. package/dist/index.cjs.map +1 -0
  5. package/dist/index.d.cts +43 -0
  6. package/dist/index.d.ts +43 -0
  7. package/dist/index.js +605 -0
  8. package/dist/index.js.map +1 -0
  9. package/package.json +60 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Juanma Gomez
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,170 @@
1
+ # hak-axelar-plugin
2
+
3
+ **Axelar Network cross-chain plugin for Hedera Agent Kit (HAK)**
4
+
5
+ Lets AI agents bridge tokens and send general-message-passing (GMP) messages from Hedera to 60+ chains using the Axelar Network protocol. Built as a first-class HAK plugin — drop it in, register it, and your agent gains five new cross-chain tools with no additional setup required.
6
+
7
+ ---
8
+
9
+ ## Strategic positioning: Axelar vs LayerZero
10
+
11
+ This plugin complements [`hak-layerzero-plugin`](https://github.com/hedera-agent-kit/hak-layerzero-plugin) and addresses different use cases:
12
+
13
+ | Concern | hak-axelar-plugin | hak-layerzero-plugin |
14
+ |---|---|---|
15
+ | Security model | Proof-of-Stake validator set | Decentralized Verifier Network (DVN) |
16
+ | Token standard | Interchain Token Service (ITS) | Omnichain Fungible Token (OFT) |
17
+ | Confirmed Hedera routes | Ethereum, Base, Arbitrum, Avalanche, Optimism, Polygon, BSC, XRPL, Monad, Berachain, Flow EVM, Scroll | Ethereum, Base, Arbitrum, Avalanche, Optimism, Polygon, BSC |
18
+ | XRPL support | Yes (confirmed live GMP txs) | No |
19
+ | Bridge architecture | Axelar Amplifier | LayerZero V2 |
20
+
21
+ Choose Axelar when you need XRPL, Berachain, Flow EVM, or Monad destinations, or when your token is already registered with Axelar ITS.
22
+
23
+ ---
24
+
25
+ ## Installation
26
+
27
+ ```bash
28
+ npm install hak-axelar-plugin
29
+ ```
30
+
31
+ ### Peer dependencies
32
+
33
+ ```bash
34
+ npm install @hashgraph/hedera-agent-kit @hiero-ledger/sdk
35
+ ```
36
+
37
+ ---
38
+
39
+ ## Quick start
40
+
41
+ ```typescript
42
+ import { HederaAgentKit } from "@hashgraph/hedera-agent-kit";
43
+ import { axelarPlugin } from "hak-axelar-plugin";
44
+
45
+ // Register the plugin with HAK
46
+ const kit = new HederaAgentKit({
47
+ accountId: process.env.HEDERA_ACCOUNT_ID!,
48
+ privateKey: process.env.HEDERA_PRIVATE_KEY!,
49
+ network: "mainnet",
50
+ });
51
+
52
+ kit.registerPlugin(axelarPlugin);
53
+
54
+ // The agent now has access to all 5 Axelar tools.
55
+ // Example: ask the agent to list supported chains
56
+ const result = await kit.runTool("axelar_get_supported_chains", {});
57
+ console.log(result);
58
+
59
+ // Example: estimate the fee to send a GMP message to Ethereum
60
+ const fee = await kit.runTool("axelar_get_message_fee", {
61
+ destinationChain: "ethereum",
62
+ gasLimit: 200000,
63
+ });
64
+ console.log(fee);
65
+ // { baseFee: "5000000", executionFee: "...", executionFeeWithMultiplier: "...", gasMultiplier: 1.1, isExpressSupported: false }
66
+ ```
67
+
68
+ ---
69
+
70
+ ## Tools
71
+
72
+ | Tool name | Description | Type |
73
+ |---|---|---|
74
+ | `axelar_get_supported_chains` | Lists all chains reachable from Hedera via Axelar. Calls the AxelarScan API — no transaction required. | Query |
75
+ | `axelar_get_message_fee` | Estimates the HBAR fee (in tinybars) needed to pay for GMP message execution on a destination chain. | Query |
76
+ | `axelar_send_message` | Sends a GMP message from Hedera to a destination chain contract. Submits two Hedera transactions: gas payment + gateway call. | Transaction |
77
+ | `axelar_send_token` | Bridges an ITS-registered token from Hedera to any supported destination chain. Single Hedera transaction. | Transaction |
78
+ | `axelar_get_message_status` | Checks the delivery status of a cross-chain message by source transaction hash. | Query |
79
+
80
+ See [`docs/TOOLS.md`](docs/TOOLS.md) for full per-tool parameter reference and examples.
81
+
82
+ ---
83
+
84
+ ## Supported chains (confirmed mainnet routes from Hedera)
85
+
86
+ | Chain | Status | Notes |
87
+ |---|---|---|
88
+ | Ethereum | Confirmed | High liquidity, many ITS tokens |
89
+ | Base | Confirmed | Low fees |
90
+ | Arbitrum | Confirmed | |
91
+ | Avalanche | Confirmed | |
92
+ | Optimism | Confirmed | |
93
+ | Polygon | Confirmed | |
94
+ | BSC | Confirmed | Binance Smart Chain |
95
+ | XRPL EVM | Confirmed | Unique to Axelar vs LayerZero |
96
+ | Monad | Confirmed | |
97
+ | Berachain | Confirmed | |
98
+ | Flow EVM | Confirmed | |
99
+ | Scroll | Confirmed | |
100
+ | Solana | Partial | Technically supported by Axelar; 0 confirmed GMP txs from Hedera as of research |
101
+ | 50+ others | Via Axelar | Query `axelar_get_supported_chains` for the live list |
102
+
103
+ Use `axelar_get_supported_chains` at runtime for the authoritative list — the Axelar network continues to add new chains.
104
+
105
+ ---
106
+
107
+ ## Network defaults
108
+
109
+ ### Contract addresses
110
+
111
+ | Contract | Mainnet (chainId 295) | Testnet (chainId 296) |
112
+ |---|---|---|
113
+ | AxelarGateway | `0xe432150cce91c13a887f7D836923d5597adD8E31` | `0xe432150cce91c13a887f7D836923d5597adD8E31` |
114
+ | AxelarGasService | `0x2d5d7d31F671F86C782533cc367F14109a082712` | `0xbE406F0189A0B4cf3A05C286473D23791Dd44Cc6` |
115
+ | ITS (Interchain Token Service) | `0xB5FB4BE02232B1bBA4dC8f81dc24C26980dE9e3C` | `0xB5FB4BE02232B1bBA4dC8f81dc24C26980dE9e3C` |
116
+ | WHBAR | `0xb1F616b8134F602c3Bb465fB5b5e6565cCAd37Ed` | — |
117
+
118
+ ### API endpoints
119
+
120
+ | Network | GMP API |
121
+ |---|---|
122
+ | Mainnet | `https://api.gmp.axelarscan.io` |
123
+ | Testnet | `https://testnet.api.gmp.axelarscan.io` |
124
+
125
+ No API keys required.
126
+
127
+ ---
128
+
129
+ ## Important notes
130
+
131
+ ### Amplifier architecture
132
+
133
+ Hedera is connected to Axelar via the **Axelar Amplifier** architecture, not the classic gateway. This means:
134
+
135
+ - Classic `axlUSDC` deposit-address bridging **does not work** on Hedera.
136
+ - Only tokens registered with the **Interchain Token Service (ITS)** can be bridged via `axelar_send_token`.
137
+ - To bridge HBAR, use **WHBAR** (`0xb1F616b8134F602c3Bb465fB5b5e6565cCAd37Ed`) — native HBAR cannot be bridged directly.
138
+
139
+ ### ITS token requirement
140
+
141
+ `axelar_send_token` requires an `interchainTokenId` (a 32-byte hex identifier assigned by the ITS contract). This is **not** the same as the ERC-20 token address. Look up the token ID via the [Axelar ITS Portal](https://interchain.axelar.dev) or by calling the ITS contract's `interchainTokenId()` view function.
142
+
143
+ ### AxelarExecutable requirement
144
+
145
+ Destination contracts that receive GMP messages via `axelar_send_message` must implement the `AxelarExecutable` interface from `@axelar-network/axelar-gmp-sdk-solidity`. Plain EOAs and contracts that do not implement this interface will not receive messages correctly.
146
+
147
+ ### HBAR decimal duality
148
+
149
+ Hedera has two decimal representations for HBAR:
150
+
151
+ - **Tinybars (8 decimals)** — native Hedera SDK denomination, used throughout this plugin's API.
152
+ - **Weibars (18 decimals)** — used in EVM / `msg.value` contexts.
153
+
154
+ All HBAR amounts in this plugin (gas fees, `gasTinybars` parameter) are expressed in **tinybars**. 1 HBAR = 100,000,000 tinybars.
155
+
156
+ ### HTS token association
157
+
158
+ Before a Hedera account can receive bridged tokens, the account must be **associated** with the HTS token. This is a Hedera-specific requirement not present on EVM chains. Use `hak-hts` or the Hedera SDK to associate before initiating a bridge that returns tokens to Hedera.
159
+
160
+ ---
161
+
162
+ ## Links
163
+
164
+ - [Axelar Documentation](https://docs.axelar.dev)
165
+ - [AxelarScan Explorer](https://axelarscan.io)
166
+ - [Axelar Amplifier Overview](https://docs.axelar.dev/dev/amplifier/introduction)
167
+ - [Interchain Token Service](https://interchain.axelar.dev)
168
+ - [Hedera Agent Kit](https://github.com/hedera-agent-kit/hedera-agent-kit)
169
+ - [hak-layerzero-plugin](https://github.com/hedera-agent-kit/hak-layerzero-plugin)
170
+ - [Axelar GMP SDK (Solidity)](https://github.com/axelar-network/axelar-gmp-sdk-solidity)