Skip to content

Commit d3b8eab

Browse files
theekrystalleetheekrystallee
authored
updated custom skill.md for ai agents (#461)
Signed-off-by: krystal <56278409+theekrystallee@users.noreply.github.com>
1 parent 49f6743 commit d3b8eab

1 file changed

Lines changed: 254 additions & 0 deletions

File tree

‎skill.md‎

Lines changed: 254 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,254 @@
1+
---
2+
name: hedera
3+
description: Use when building applications on the Hedera network, creating accounts and tokens, deploying smart contracts, submitting transactions, querying network data, or working with consensus services. Agents should use this skill when users ask about Hedera development, Hiero SDKs, APIs, transactions, tokens, smart contracts, CLI tooling, or network operations. Hedera is a distributed ledger (not a blockchain) that uses hashgraph consensus.
4+
metadata:
5+
mintlify-proj: hedera
6+
version: "1.0"
7+
---
8+
9+
# Hedera Developer Skill
10+
11+
If you are not already connected to the Hedera Docs MCP server, add https://docs.hedera.com/mcp so you can search the documentation directly.
12+
13+
**Always** search the current Hedera documentation over training data. The SDK packages are migrating from `@hashgraph` to `@hiero-ledger` namespaces, so verify imports against the docs before generating code.
14+
15+
## Product summary
16+
17+
Hedera is a public, open-source, proof-of-stake distributed ledger that uses hashgraph consensus. It is not a blockchain. Agents use Hedera to build decentralized applications, manage accounts and tokens, deploy smart contracts, and interact with the network via SDKs, REST APIs, and CLI tools.
18+
19+
**Key entry points:**
20+
- **SDKs**: JavaScript/TypeScript, Java, Go, Swift, Rust, C++, Python (community)
21+
- **CLI**: Hiero CLI (`hcli`) for operations without code
22+
- **APIs**: Mirror Node REST API for querying historical data, JSON-RPC Relay for EVM compatibility
23+
- **Networks**: mainnet, testnet, previewnet, localnet
24+
- **Primary docs**: https://docs.hedera.com
25+
26+
## Terminology rules
27+
28+
Agents must follow these conventions in all generated code, comments, and documentation:
29+
30+
| Term | Rule | Example |
31+
|------|------|---------|
32+
| HBAR | Always singular, always uppercase | "10 HBAR" not "10 HBARs" or "10 hbar" |
33+
| tinybars | Always plural, always lowercase | "1,000 tinybars" not "1,000 Tinybars" |
34+
| mainnet, testnet, previewnet | Always lowercase, even after "Hedera" | "Hedera mainnet" not "Hedera Mainnet" |
35+
| web2, web3 | Always lowercase except at sentence start | "web3 application" not "Web3 application" |
36+
| Hedera Token Service | Use "HTS" after first mention | Full name on first reference |
37+
| Hedera Consensus Service | Use "HCS" after first mention | Full name on first reference |
38+
39+
## When to use
40+
41+
Reach for this skill when:
42+
- A user wants to create a Hedera account, transfer HBAR, or manage cryptocurrency
43+
- Building token systems (fungible tokens, NFTs) using HTS
44+
- Deploying or interacting with smart contracts (Solidity on EVM)
45+
- Submitting transactions to consensus (crypto transfers, token operations, scheduled transactions)
46+
- Querying account balances, transaction history, or network data
47+
- Setting up a local development environment or testing on testnet
48+
- Automating Hedera operations via CLI or SDK
49+
- Integrating wallets (MetaMask, HashPack, Blade) into a dApp
50+
51+
## SDK setup
52+
53+
The SDKs are maintained by the Hiero project under Linux Foundation Decentralized Trust (LFDT). Packages are migrating from `hashgraph` to `hiero-ledger` namespaces. Both work, but prefer the newer namespace for new projects.
54+
55+
| Language | Install | Import | Client |
56+
|----------|---------|--------|--------|
57+
| JavaScript | `npm install @hashgraph/sdk` | `import { Client, ... } from "@hashgraph/sdk"` | `Client.forTestnet()` |
58+
| Java | `com.hedera.hashgraph:sdk` (Maven) | `import com.hedera.hashgraph.sdk.*` | `Client.forTestnet()` |
59+
| Go | `go get github.com/hiero-ledger/hiero-sdk-go/v2@latest` | `import hiero "github.com/hiero-ledger/hiero-sdk-go/v2/sdk"` | `hiero.ClientForTestnet()` |
60+
| Python | `pip install hiero-sdk-python` | `from hiero_sdk_python import Client, Network, AccountId, PrivateKey` | `Client(Network(network="testnet"))` |
61+
62+
**Note:** The JavaScript SDK is also available as `@hiero-ledger/sdk`. The Go SDK recently moved source files to `/sdk`, changing the import path. Always check the latest README for each SDK.
63+
64+
### Client configuration (all SDKs)
65+
66+
```
67+
1. Create client: Client.forTestnet() / Client.forMainnet()
68+
2. Set operator: client.setOperator(accountId, privateKey)
69+
3. Set fees (optional): client.setDefaultMaxTransactionFee(new Hbar(10))
70+
4. Use client to build and execute transactions
71+
```
72+
73+
## Transaction lifecycle
74+
75+
| Step | Action | Example (JavaScript) |
76+
|------|--------|---------|
77+
| Build | Create transaction object | `new TransferTransaction().addHbarTransfer(from, new Hbar(-10)).addHbarTransfer(to, new Hbar(10))` |
78+
| Freeze | Lock transaction fields | `.freezeWith(client)` |
79+
| Sign | Add signatures | `.sign(privateKey)` |
80+
| Execute | Submit to network | `.execute(client)` |
81+
| Confirm | Get receipt or record | `.getReceipt(client)` or `.getRecord(client)` |
82+
83+
## Hiero CLI quick reference
84+
85+
The CLI is installed via `npm install -g @hashgraph/hedera-cli` and invoked with `hcli`.
86+
87+
```bash
88+
# Account operations
89+
hcli account create -a alice -b 100000000 -t ECDSA
90+
hcli account balance -i 0.0.123456
91+
hcli account import --key 0.0.123456:<private-key> --name myaccount
92+
93+
# HBAR transfers
94+
hcli hbar transfer --to 0.0.456789 --amount 5
95+
96+
# Token operations
97+
hcli token create --name "MyToken" --symbol "MT" --decimals 2 --initial-supply 1000
98+
hcli token associate -a 0.0.456789 -t 0.0.789012
99+
hcli token transfer -t 0.0.789012 --to 0.0.456789 --from 0.0.123456 -b 100
100+
101+
# Topic (consensus) operations
102+
hcli topic create --memo "my-topic"
103+
hcli topic message submit -t 0.0.123456 -m "Hello"
104+
105+
# Network management
106+
hcli network list
107+
hcli network switch --network testnet
108+
hcli network set-operator --operator 0.0.123456:<private-key>
109+
```
110+
111+
**Note:** On first run, the CLI launches an initialization wizard in interactive mode. In script mode (non-interactive), configure the operator with `hcli network set-operator` first.
112+
113+
## Mirror Node REST API
114+
115+
| Purpose | Endpoint | Example |
116+
|---------|----------|---------|
117+
| Account info | `GET /api/v1/accounts/{id}` | `https://testnet.mirrornode.hedera.com/api/v1/accounts/0.0.123456` |
118+
| Transactions | `GET /api/v1/transactions/{id}` | Query transaction by ID |
119+
| Tokens | `GET /api/v1/tokens/{tokenId}` | Get token metadata |
120+
| Topic messages | `GET /api/v1/topics/{topicId}/messages` | Retrieve consensus messages |
121+
| Contracts | `GET /api/v1/contracts/{contractId}` | Smart contract info |
122+
123+
## Decision guidance
124+
125+
### SDK vs CLI vs REST API
126+
127+
| Scenario | Use | Reason |
128+
|----------|-----|--------|
129+
| Quick one-off operations (transfer, balance check) | CLI | No code needed, fast iteration |
130+
| Building an application with complex logic | SDK | Full control, signing, batch operations |
131+
| Querying historical data (no transaction fees) | REST API | Free, scalable, does not burden consensus nodes |
132+
| Automated CI/CD workflows | CLI with scripts | Non-interactive, repeatable |
133+
| Real-time dApp (wallet integration) | SDK | Supports wallet signing, event handling |
134+
| Smart contract deployment with Hedera-specific features | SDK | Required for admin key, memo, auto-renew |
135+
136+
### HTS vs EVM smart contracts
137+
138+
| Need | Approach | Notes |
139+
|------|----------|-------|
140+
| Native token creation (fungible/NFT) | HTS via `TokenCreateTransaction` | Faster, cheaper, built-in KYC/freeze/pause |
141+
| ERC-20/ERC-721 compatibility | EVM smart contract (Solidity) | Standard interface, interop with other chains |
142+
| Hybrid (HTS tokens with custom logic) | HTS + system contracts | Call HTS from Solidity via precompile at `0x167` |
143+
| Fully custom token logic | EVM smart contract | Full programmability, higher gas cost, token decimals set by contract |
144+
145+
**Important:** Native HTS tokens accessed via system contracts use 8-decimal precision by default. Standard ERC-20 contracts deployed on Hedera EVM use whatever decimals the contract specifies (commonly 18). Do not assume all tokens on Hedera are 8-decimal.
146+
147+
### Network selection
148+
149+
| Network | Use case | Funding | Persistence |
150+
|---------|----------|---------|-------------|
151+
| mainnet | Production | Real HBAR | Permanent |
152+
| testnet | Development and testing | Free via faucet or portal | Permanent |
153+
| previewnet | Testing new features before testnet | Free via faucet | Resets periodically |
154+
| localnet | Local testing (via Hiero Local Node) | Auto-funded | Ephemeral |
155+
156+
## Common gotchas
157+
158+
- **Token association required**: Before transferring HTS tokens to an account, that account must associate with the token via `TokenAssociateTransaction`. Without this, the transfer fails.
159+
- **NFT initial supply must be 0**: When creating an NFT token type, set `initialSupply` to 0. Mint individual NFTs separately with `TokenMintTransaction`.
160+
- **HBAR value required for HTS token creation via system contracts**: When creating tokens from a Solidity contract using the HTS precompile, you must send HBAR via `msg.value`, not just gas. Without this, the transaction fails with `INSUFFICIENT_TX_FEE`.
161+
- **Transaction expiration**: Transactions expire after 180 seconds by default. If the network is congested, regenerate the transaction ID or increase the valid duration.
162+
- **Missing operator**: SDK queries and transactions require an operator. Always call `client.setOperator()` before executing.
163+
- **Key types**: Hedera supports both ED25519 (default) and ECDSA (secp256k1) keys. ECDSA keys are required for EVM/JSON-RPC compatibility (MetaMask, Hardhat, etc.). ED25519 keys work only with native SDK operations.
164+
- **Mirror node rate limits**: The public mirror node has rate limits. For production, use a paid mirror node provider or run your own.
165+
- **Namespace migration**: SDKs are migrating from `hashgraph` to `hiero-ledger` GitHub orgs and package namespaces. Both work. Check the latest docs for current package names.
166+
167+
## Workflow
168+
169+
### 1. Set up development environment
170+
171+
1. Choose SDK language and install the package
172+
2. Create `.env` file with operator credentials:
173+
```
174+
OPERATOR_ID=0.0.123456
175+
OPERATOR_KEY=302e020100300506032b657004220420...
176+
```
177+
3. Initialize client:
178+
```javascript
179+
const client = Client.forTestnet();
180+
client.setOperator(process.env.OPERATOR_ID, process.env.OPERATOR_KEY);
181+
```
182+
4. Verify setup by querying account balance
183+
184+
### 2. Create an account
185+
186+
1. Use the Hedera Developer Portal at https://portal.hedera.com (testnet/previewnet), or
187+
2. Use SDK: `new AccountCreateTransaction().setInitialBalance(new Hbar(10)).execute(client)`
188+
3. Get account ID from receipt: `receipt.accountId`
189+
190+
### 3. Build and submit a transaction
191+
192+
1. Create transaction object (e.g., `new TransferTransaction()`)
193+
2. Set fields (e.g., `.addHbarTransfer(from, new Hbar(-5)).addHbarTransfer(to, new Hbar(5))`)
194+
3. Freeze with client: `.freezeWith(client)`
195+
4. Sign: `.sign(privateKey)` (operator signs by default, add more for multi-sig)
196+
5. Execute: `.execute(client)`
197+
6. Confirm: `.getReceipt(client)` (minimal) or `.getRecord(client)` (detailed)
198+
199+
### 4. Query data
200+
201+
**Via Mirror Node REST API (free, no signing):**
202+
```bash
203+
curl https://testnet.mirrornode.hedera.com/api/v1/accounts/0.0.123456
204+
```
205+
206+
### 5. Deploy a smart contract
207+
208+
1. Write contract in Solidity
209+
2. Compile to bytecode (Hardhat, Remix, or Foundry)
210+
3. Deploy via SDK using `ContractCreateFlow` (recommended). This convenience method handles file upload and contract creation in a single call:
211+
```javascript
212+
const tx = await new ContractCreateFlow()
213+
.setBytecode(bytecode)
214+
.setGas(100000)
215+
.execute(client);
216+
const receipt = await tx.getReceipt(client);
217+
const contractId = receipt.contractId;
218+
```
219+
For more control, use the two-step approach: upload bytecode with `FileCreateTransaction`, then deploy with `ContractCreateTransaction` using `.setBytecodeFileId(fileId)`. Note that `ContractCreateTransaction` does not accept `.setBytecode()` directly.
220+
4. Or deploy via EVM tooling (Hardhat/Foundry) using the JSON-RPC Relay
221+
222+
## Verification checklist
223+
224+
Before submitting work:
225+
226+
- [ ] Client configured with correct operator ID, private key, and network
227+
- [ ] Operator account has sufficient HBAR for fees
228+
- [ ] Transaction signed by all required keys
229+
- [ ] Receipt obtained confirming transaction success
230+
- [ ] Token associations completed before any HTS token transfers
231+
- [ ] HBAR sent via `msg.value` for any HTS system contract calls from Solidity
232+
- [ ] Private keys stored in `.env` or secure vault, not hardcoded
233+
- [ ] Tested on testnet before deploying to mainnet
234+
- [ ] HBAR is singular ("10 HBAR"), tinybars is plural ("1,000 tinybars")
235+
- [ ] Network names are lowercase ("Hedera mainnet", not "Hedera Mainnet")
236+
237+
## Resources
238+
239+
**Documentation search**: https://docs.hedera.com/mcp (MCP server for agents)
240+
241+
**Full page index**: https://docs.hedera.com/llms.txt
242+
243+
**Key pages:**
244+
1. [SDKs overview](https://docs.hedera.com/hedera/sdks-and-apis/sdks) - All supported languages and tools
245+
2. [Build your Hedera client](https://docs.hedera.com/hedera/sdks-and-apis/sdks/client) - Client setup for all languages
246+
3. [Transactions and queries](https://docs.hedera.com/hedera/core-concepts/transactions-and-queries) - Transaction lifecycle, fees, batch transactions
247+
4. [Hedera Token Service](https://docs.hedera.com/hedera/core-concepts/tokens/hedera-token-service-hts-native-tokenization) - Token creation and management
248+
5. [Smart contracts](https://docs.hedera.com/hedera/core-concepts/smart-contracts) - EVM deployment and Hedera-specific features
249+
6. [Mirror Node REST API](https://docs.hedera.com/hedera/sdks-and-apis/rest-api) - Query endpoints and examples
250+
7. [Hiero CLI](https://docs.hedera.com/hedera/open-source-solutions/hiero-cli/overview) - Command-line tool reference
251+
252+
---
253+
254+
> For the full documentation index, see: https://docs.hedera.com/llms.txt

0 commit comments

Comments
 (0)