Skip to content

Commit bfa5965

Browse files
bumblefudgebumblefudge
authored
Add haneul namespace and CAIP-2 spec (#168)
2 parents d65ae6b + c4edc0f commit bfa5965

File tree

2 files changed

+157
-0
lines changed

2 files changed

+157
-0
lines changed

‎haneul/README.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
namespace-identifier: haneul
3+
title: Haneul Ecosystem
4+
author: Geunhwa Jeong (@GeunhwaJeong)
5+
discussions-to: https://github.com/ChainAgnostic/namespaces/pull/168
6+
status: Draft
7+
type: Informational
8+
created: 2026-01-19
9+
updated: 2026-01-19
10+
---
11+
12+
# Namespace for Haneul Chains
13+
14+
Haneul is a Layer 1 smart contract platform that uses a Move-based, object-centric data model and is optimized for parallel execution. Transactions in Haneul operate on objects rather than accounts, allowing independent operations to be executed in parallel without coordination. This enables high throughput while preserving safety and determinism.
15+
16+
A Haneul network is maintained by a validator committee responsible for processing transactions, reaching consensus, and producing checkpoint digests — cryptographic summaries of network state at fixed intervals. These checkpoints serve as the canonical state and ensure consistency across nodes.
17+
18+
Each network is uniquely identified by its genesis checkpoint digest — the cryptographic hash of the very first checkpoint, signed by the original validator set. This digest anchors the network's identity in verifiable history and validator consensus.
19+
20+
## Rationale
21+
22+
Because chain identity and state in Haneul revolve around checkpoints and objects rather than blocks and accounts, standard CAIP identifiers (e.g., for chains, accounts, and assets) must be adapted accordingly.
23+
24+
This namespace defines how Haneul's architecture maps to cross-chain standards to support consistent and interoperable multi-chain tooling.
25+
26+
## Governance
27+
28+
Haneul protocol upgrades and standards are coordinated by Haneul Labs in collaboration with core contributors and the broader developer community. Changes are proposed through HIPs (Haneul Improvement Proposals), with open discussion and reference implementations maintained on GitHub.
29+
30+
## References
31+
32+
- [Haneul GitHub] — Official GitHub repository for the Haneul blockchain.
33+
- [Haneul TypeScript SDK] — Official TypeScript SDK for Haneul.
34+
35+
[Haneul GitHub]: https://github.com/GeunhwaJeong/haneul
36+
[Haneul TypeScript SDK]: https://github.com/GeunhwaJeong/haneul-ts-sdks
37+
38+
## Copyright
39+
40+
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

‎haneul/caip2.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
---
2+
namespace-identifier: haneul-caip2
3+
title: Haneul Namespace - Chains
4+
author: Geunhwa Jeong (@GeunhwaJeong)
5+
discussions-to: https://github.com/ChainAgnostic/namespaces/pull/168
6+
status: Draft
7+
type: Informational
8+
created: 2026-01-19
9+
updated: 2026-02-11
10+
---
11+
12+
# CAIP-2
13+
14+
_For context, see the [CAIP-2][] specification._
15+
16+
## Introduction
17+
18+
The Haneul namespace in CAIP-2 uses human-readable chain identifiers — such as `mainnet`, `testnet`, and `devnet` — to identify specific Haneul networks. These identifiers are **stable**, **concise**, and **easy to communicate**, and can be resolved to a unique genesis checkpoint digest through a supported Haneul RPC interface.
19+
20+
This design provides both developer ergonomics and cryptographic assurance, allowing developers to work with simple names while still supporting verifiable chain identification.
21+
22+
## Specification
23+
24+
### Semantics
25+
26+
A valid CAIP-2 identifier in the Haneul namespace takes the form:
27+
28+
`haneul:<network>`
29+
30+
Where `<network>` is one of the following reserved, stable identifiers:
31+
32+
- `mainnet`
33+
- `testnet`
34+
- `devnet`
35+
36+
### Syntax
37+
38+
#### Regular Expression
39+
40+
`^haneul:(mainnet|testnet|devnet)$`
41+
42+
Only these exact network identifiers are currently supported. Network names are lowercase ASCII strings with a maximum length of 7 characters. The resolved chain identifier returned by RPC is 4 bytes (8 hex characters), derived from the first 4 bytes of the 32-byte Blake2b-256 genesis checkpoint digest.
43+
44+
#### Example
45+
46+
`haneul:testnet`
47+
48+
### Governance
49+
50+
New network identifiers and chain resets are decided by Haneul Labs. Adding a new network name requires a protocol-level code change and validator coordination. Resets of `testnet` and `devnet` may occur during protocol upgrades or development cycles; `mainnet` is not expected to be reset under normal circumstances.
51+
52+
### Resolution Mechanics
53+
54+
To resolve a CAIP-2 `haneul:<network>` identifier into a unique chain identifier, clients typically query a trusted full node associated with the specified network. While the `haneul_getChainIdentifier` JSON-RPC method is commonly used for this purpose, resolution is not limited to JSON-RPC. Other node interfaces, such as GraphQL, may also support retrieving identifiers pertinent to locating records, such as a genesis checkpoint digest unique to each chain.
55+
56+
**Sample request**
57+
58+
```json
59+
{
60+
"jsonrpc": "2.0",
61+
"id": 1,
62+
"method": "haneul_getChainIdentifier",
63+
"params": []
64+
}
65+
```
66+
67+
**Sample response (for testnet):**
68+
69+
```json
70+
{
71+
"jsonrpc": "2.0",
72+
"id": 1,
73+
"result": "afd5afb7"
74+
}
75+
```
76+
77+
The response returns the first four bytes of the genesis checkpoint digest for the network.
78+
79+
## Rationale
80+
81+
This approach allows developers to use intuitive, readable CAIP-2 identifiers (e.g., `haneul:testnet`) while still achieving unambiguous and verifiable identification of the underlying chain through the genesis checkpoint digest.
82+
83+
The separation of **stable identifiers** (e.g., `haneul:testnet`) from the **unambiguous chain identifier** (e.g., the identifier returned by `haneul_getChainIdentifier`) is particularly important because:
84+
85+
- **`testnet` and `devnet` may be reset** by Haneul maintainers, resulting in a new genesis state. A reset is a complete reinitialization — all on-chain state, including balances, objects, and smart contract data, is wiped and a new genesis checkpoint is produced. Only the stable network name (e.g., `testnet`) persists across resets.
86+
- When this happens, the **genesis checkpoint digest changes**, meaning the underlying chain identifier is no longer the same.
87+
- If clients depended directly on the digest as the CAIP-2 identifier, each reset would break compatibility or require external coordination.
88+
- By resolving the digest dynamically via RPC, clients can ensure they're talking to the correct chain, without needing to change the CAIP-2 identifier they rely on.
89+
90+
This pattern balances human readability, forward compatibility, and security.
91+
92+
### Backwards Compatibility
93+
94+
There are no legacy identifiers or alternate forms for Haneul chains.
95+
96+
## Test Cases
97+
98+
Below are manually composed examples:
99+
100+
#### Haneul Testnet
101+
102+
- **CAIP-2 Chain ID:** `haneul:testnet`
103+
- **Resolved Chain Identifier:** `afd5afb7`
104+
105+
## References
106+
107+
- [Haneul GitHub] — Official GitHub repository for the Haneul blockchain.
108+
- [Haneul TypeScript SDK] — Official TypeScript SDK for Haneul.
109+
- [CAIP-2] — Chain ID Specification.
110+
111+
[Haneul GitHub]: https://github.com/GeunhwaJeong/haneul
112+
[Haneul TypeScript SDK]: https://github.com/GeunhwaJeong/haneul-ts-sdks
113+
[CAIP-2]: https://chainagnostic.org/CAIPs/caip-2
114+
115+
## Copyright
116+
117+
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

0 commit comments

Comments
 (0)