Skip to content

Commit d65ae6b

Browse files
bumblefudgebumblefudge
authored
Add CAIP-350 profiles for bip122, starknet (#172)
2 parents fd4b593 + e2a40a8 commit d65ae6b

2 files changed

Lines changed: 244 additions & 0 deletions

File tree

‎bip122/caip350.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
---
2+
namespace-identifier: bip122-caip350
3+
title: BIP122 Namespace - Interoperable Address
4+
binary-key: 0001
5+
author: Orca (@0xrcinus), Mono (@0xMonoAx)
6+
discussions-to: https://ethereum-magicians.org/t/erc-7930-interoperable-addresses/23365
7+
status: Draft
8+
type: Standard
9+
created: 2026-01-29
10+
requires: CAIP-2
11+
---
12+
13+
## Namespace Reference
14+
15+
ChainType binary key: `0x0001`
16+
17+
[CAIP-104] namespace: `bip122`
18+
19+
## Chain reference
20+
21+
See this namespace's [CAIP-2](caip2.md) profile. The chain reference is the first 32 characters (16 bytes) of the genesis block hash in lowercase hex.
22+
23+
### Text representation
24+
25+
```
26+
<genesis_hash_prefix>
27+
```
28+
29+
This is the first 32 lowercase hex characters (16 bytes) of the genesis block hash as defined in [BIP122][].
30+
31+
> **Note:** Per [CAIP-350], the full chain identifier is `bip122:<genesis_hash_prefix>` (e.g., `bip122:000000000019d6689c085ae165831e93`, `bip122:000000000933ea01ad0ee984209779ba`).
32+
33+
##### Text representation -> customary (CAIP-2) conversion
34+
35+
The text representation (chain reference) is the same as the chain reference in the [CAIP-2](caip2.md) chain identifier; no conversion is needed.
36+
37+
##### Customary (CAIP-2) conversion - text representation conversion
38+
39+
The chain reference in the [CAIP-2](caip2.md) chain identifier is the same as the text representation; no conversion is needed.
40+
41+
#### Binary representation
42+
43+
The chain reference is the 16 bytes corresponding to the first 32 hex characters of the genesis block hash. Bytes are in the same order as the hex string (first two hex characters encode the first byte, etc.).
44+
45+
#### Text -> binary conversion
46+
47+
Decode the 32-character lowercase hex string to 16 bytes (RFC-4616 base16, no 0x-prefix).
48+
49+
#### Binary -> text conversion
50+
51+
Encode the 16 bytes as 32 lowercase hex characters (RFC-4616 base16, no 0x-prefix).
52+
53+
#### Examples
54+
55+
| Chain | Text (chain reference) | Binary |
56+
|-------|------------------------|--------------------------------|
57+
| Bitcoin mainnet | `000000000019d6689c085ae165831e93` | `0x000000000019d6689c085ae165831e93` |
58+
| Bitcoin testnet | `000000000933ea01ad0ee984209779ba` | `0x000000000933ea01ad0ee984209779ba` |
59+
| Litecoin mainnet | `12a765e31ffd4059bada1e25190f6e98` | `0x12a765e31ffd4059bada1e25190f6e98` |
60+
61+
## Addresses
62+
63+
See this namespace's [CAIP-10](caip10.md) profile. BIP122 supports multiple address types (P2SH, SegWit, Taproot) with different native encodings (base58btc, bech32, bech32m).
64+
65+
### Text representation
66+
67+
```
68+
<address>
69+
```
70+
71+
Where `<address>` is the full native ASCII form (base58btc, bech32, or bech32m) as in [CAIP-10](caip10.md)—e.g. P2SH `35PBEaofpUeH8VnnNSorM1QZsadrZoQp4N`, SegWit `bc1qwz2lhc40s8ty3l5jg3plpve3y3l82x9l42q7fk`, or Taproot `bc1pmzfrwwndsqmk5yh69yjr5lfgfg4ev8c0tsc06e`.
72+
73+
#### Text representation -> native representation conversion
74+
75+
No transformation; the text representation is the native representation.
76+
77+
#### Native representation -> text representation conversion
78+
79+
No transformation; the native representation is the text representation.
80+
81+
### Binary representation
82+
83+
The binary representation uses a one-byte type prefix followed by the decoded payload (without checksum):
84+
85+
- **0x01 — P2SH**: 1 byte version (network-dependent) + 20 bytes script hash (21 bytes total after type).
86+
- **0x02 — Witness (SegWit / Taproot)**: 1 byte witness version (0 for P2WPKH, 1 for P2TR, etc.) + 20 or 32 bytes program (22 or 34 bytes total after type).
87+
88+
Checksums are omitted in binary; they can be recomputed when converting back to text.
89+
90+
#### Text -> binary conversion
91+
92+
1. Detect address type from prefix (e.g. `3` for P2SH, `bc1q`/`tb1q` etc. for witness).
93+
2. Decode using the appropriate scheme ([base58btc][] for P2SH, [bech32][]/[bech32m][] for witness) and strip checksum.
94+
3. Prepend type byte 0x01 (P2SH) or 0x02 (witness), then append version byte and hash/program bytes as above.
95+
96+
#### Binary -> text conversion
97+
98+
1. Read the type byte (0x01 or 0x02).
99+
2. For 0x01: read 21 bytes (1 version + 20 hash), encode with base58btc including checksum for the target network.
100+
3. For 0x02: read 1 byte witness version, then 20 or 32 bytes program; encode with [bech32][] or [bech32m][] (and correct HRP for network).
101+
102+
### Examples
103+
104+
| Text (Bitcoin mainnet) | Binary (hex, after type byte) |
105+
|------------------------|-------------------------------|
106+
| P2SH `35PBEaofpUeH8VnnNSorM1QZsadrZoQp4N` | `0x01` + base58btc-decoded payload (version + 20-byte hash) |
107+
| SegWit `bc1qwz2lhc40s8ty3l5jg3plpve3y3l82x9l42q7fk` | `0x02` + `0x00` + 20-byte witness program |
108+
| Taproot `bc1pmzfrwwndsqmk5yh69yjr5lfgfg4ev8c0tsc06e` | `0x02` + `0x01` + 32-byte witness program |
109+
110+
## Error handling
111+
112+
When converting from this profile's [CAIP-2] encoding to this profile's [CAIP-350] encoding, the chain reference is already fully specified (32 hex chars), so no loss of information or difference of expression occurs. For addresses, invalid or unsupported native encodings (e.g. legacy P2PKH excluded from [CAIP-10](caip10.md)) should be rejected with an appropriate error.
113+
114+
## Implementation considerations
115+
116+
Legacy P2PKH addresses are excluded from [CAIP-10](caip10.md) and therefore from this profile. Only P2SH, SegWit, and Taproot address types are supported. Implementations must use the correct HRP and version bytes per network (e.g. mainnet vs testnet, or other BIP122 chains).
117+
118+
## References
119+
120+
[BIP122]: https://github.com/bitcoin/bips/blob/master/bip-0122.mediawiki
121+
[BIP13]: https://github.com/bitcoin/bips/blob/master/bip-0013.mediawiki
122+
[BIP173]: https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki
123+
[BIP350]: https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki
124+
[base58btc]: https://datatracker.ietf.org/doc/html/draft-msporny-base58-02
125+
[bech32]: https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki
126+
[bech32m]: https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki
127+
[CAIP-2]: https://chainagnostic.org/CAIPs/caip-2
128+
[CAIP-10]: https://chainagnostic.org/CAIPs/caip-10
129+
[CAIP-104]: https://chainagnostic.org/CAIPs/caip-104
130+
[CAIP-350]: https://chainagnostic.org/CAIPs/caip-350

‎starknet/caip350.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
---
2+
namespace-identifier: starknet-caip350
3+
title: StarkNet Namespace - Interoperable Address
4+
binary-key: 0003
5+
author: Orca (@0xrcinus), Mono (@0xMonoAx)
6+
discussions-to: https://ethereum-magicians.org/t/erc-7930-interoperable-addresses/23365
7+
status: Draft
8+
type: Standard
9+
created: 2026-01-29
10+
requires: CAIP-2
11+
---
12+
13+
## Namespace Reference
14+
15+
ChainType binary key: `0x0003`
16+
17+
[CAIP-104] namespace: `starknet`
18+
19+
## Chain reference
20+
21+
See this namespace's [CAIP-2](caip2.md) profile. Chains are identified by string identifiers (e.g. `SN_MAIN`, `SN_GOERLI`) that are encoded as field elements on the chain but expressed as ASCII strings in [CAIP-2].
22+
23+
### Text representation
24+
25+
```
26+
<chain_id_string>
27+
```
28+
29+
Where `<chain_id_string>` is the case-sensitive chain identifier (e.g. `SN_MAIN`, `SN_GOERLI`).
30+
31+
> **Note:** Per [CAIP-350], the full chain identifier is `starknet:<chain_id_string>` (e.g., `starknet:SN_MAIN`, `starknet:SN_GOERLI`).
32+
33+
#### Text representation -> customary (CAIP-2) conversion
34+
35+
The text representation (chain reference) is the same as the chain reference in the [CAIP-2](caip2.md) chain identifier; no conversion is needed.
36+
37+
#### Customary (CAIP-2) conversion - text representation conversion
38+
39+
The chain reference in the [CAIP-2](caip2.md) chain identifier is the same as the text representation; no conversion is needed.
40+
41+
### Binary representation
42+
43+
The chain reference is the UTF-8 encoding of the chain ID string. Length is variable (e.g. 7 bytes for `SN_MAIN`, 9 bytes for `SN_GOERLI`). The ChainReference field in binary Interoperable Addresses must carry this byte sequence; higher-level framing (e.g. length prefix) is defined by [ERC-7930][] / [CAIP-350][].
44+
45+
#### Text -> binary conversion
46+
47+
Encode the chain ID string as UTF-8 bytes.
48+
49+
#### Binary -> text conversion
50+
51+
Decode the bytes to the chain ID string (for all current identifiers, the bytes are UTF-8/ASCII).
52+
53+
#### Examples
54+
55+
| Chain | Text (chain reference) | Binary |
56+
|-------|------------------------|--------------------------------|
57+
| StarkNet mainnet | `SN_MAIN` | `0x534e5f4d41494e` |
58+
| StarkNet Goerli | `SN_GOERLI` | `0x534e5f474f45524c49` |
59+
60+
## Addresses
61+
62+
See this namespace's [CAIP-10](caip10.md) profile. StarkNet addresses are 32-byte field elements, represented as `0x` followed by 64 hexadecimal characters (zero-padded), with optional [EIP-55][] checksum.
63+
64+
### Text representation
65+
66+
```
67+
<address>
68+
```
69+
70+
Where `<address>` is the 32-byte field element as in [CAIP-10](caip10.md): `0x` followed by 64 hex characters (EIP-55 checksum recommended), e.g. `0x02DdfB499765c064eaC5039E3841AA5f382E73B598097a40073BD8B48170Ab57`.
71+
72+
##### Text representation -> native representation conversion
73+
74+
Strip the `0x` prefix and decode the 64 hex characters to 32 bytes. Checksum validation (if present) follows [EIP-55][].
75+
76+
##### Native representation -> text representation conversion
77+
78+
Encode the 32 bytes as 64 hex characters with `0x` prefix. Apply [EIP-55][] checksum for the canonical text form.
79+
80+
#### Binary representation
81+
82+
The address is stored as the raw 32 bytes (big-endian), as in the native field element representation. No length prefix is needed for fixed-size addresses.
83+
84+
#### Text -> binary conversion
85+
86+
Remove the `0x` prefix and decode the 64 hex characters to 32 bytes (via [RFC-4616] base16).
87+
88+
#### Binary -> text conversion
89+
90+
Encode the 32 bytes as 64 hex characters and prepend `0x`. Apply [EIP-55][] checksum casing for the canonical form.
91+
92+
### Examples
93+
94+
| Text | Binary (hex of Address field) |
95+
|------|-------------------------------|
96+
| `0x02DdfB499765c064eaC5039E3841AA5f382E73B598097a40073BD8B48170Ab57` | `0x02ddfb499765c064eac5039e3841aa5f382e73b598097a40073bd8b48170ab57` (32 bytes) |
97+
98+
## Error handling
99+
100+
When converting from [CAIP-2] to this profile, the chain reference is fully determined by the chain ID string, so no loss of information occurs. If a chain ID is unknown or the UTF-8 encoding is invalid, implementations should signal an error.
101+
102+
## Implementation considerations
103+
104+
The interoperable format uses the chain ID string for text representation and its UTF-8 encoding for binary. Chain IDs may be resolved via the `starknet_chainId` method when needed (e.g. to discover the identifier for a connected node). Addresses are always 32 bytes; leading zero in hex is normal for field elements below 2^255.
105+
106+
## References
107+
108+
[CAIP-2]: https://chainagnostic.org/CAIPs/caip-2
109+
[CAIP-10]: https://chainagnostic.org/CAIPs/caip-10
110+
[CAIP-104]: https://chainagnostic.org/CAIPs/caip-104
111+
[CAIP-350]: https://chainagnostic.org/CAIPs/caip-350
112+
[EIP-55]: https://eips.ethereum.org/EIPS/eip-55
113+
[ERC-7930]: https://eips.ethereum.org/EIPS/eip-7930
114+
[RFC-4616]: https://datatracker.ietf.org/doc/html/rfc4616

0 commit comments

Comments
 (0)