Skip to content

Commit fc77c08

Browse files
bumblefudgebumblefudge
authored
Add Stellar namespace CAIP-10 and CAIP-19 specifications (#157)
2 parents d381189 + c1af9ed commit fc77c08

2 files changed

Lines changed: 356 additions & 0 deletions

File tree

‎stellar/caip10.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
---
2+
namespace-identifier: stellar-caip10
3+
title: Stellar Namespace - Addresses
4+
author: Pelle Braendgaard (@pelle)
5+
discussions-to: https://github.com/ChainAgnostic/namespaces/pull/157
6+
status: Draft
7+
type: Standard
8+
created: 2025-11-6
9+
requires: ["CAIP-2", "CAIP-10"]
10+
---
11+
12+
# CAIP-10
13+
14+
*For context, see the [CAIP-10][] specification.*
15+
16+
## Rationale
17+
18+
In [CAIP-10][], a string-based general account address scheme is defined.
19+
Stellar supports multiple address formats to accommodate different use cases:
20+
21+
### Classic Addresses (G-addresses)
22+
23+
Classic Stellar addresses are Ed25519 public keys encoded using Stellar's `strkey` format (base32 encoding as defined in [RFC 4648]).
24+
A classic Stellar address has the following characteristics:
25+
26+
* It is exactly 56 characters long
27+
* It starts with the character `G`
28+
* It uses base32 encoding with character set `[A-Z][2-7]`
29+
* It is case-insensitive (though conventionally uppercase)
30+
* It includes a CRC16 checksum for error detection
31+
* It may optionally include a memo appended with a hyphen (`-`) separator
32+
33+
### Muxed Accounts (M-addresses)
34+
35+
Muxed accounts (introduced in Protocol 13, [CAP-0027]) encode both a classic address and a 64-bit unsigned integer ID into a single string.
36+
A muxed account address has the following characteristics:
37+
38+
* It is exactly 69 characters long
39+
* It starts with the character `M`
40+
* It uses base32 encoding (same character set as G-addresses)
41+
* It is case-insensitive (though conventionally uppercase)
42+
* It encodes both the underlying G-address and a 64-bit memo ID
43+
* It includes a checksum for validation
44+
* Muxed accounts are a client-side abstraction; only the underlying G-address
45+
exists on the ledger
46+
47+
### Federated Addresses
48+
49+
Federated addresses (defined in SEP-0002) provide human-readable addressing in the format `username*domain.com`.
50+
These addresses must be resolved to a G-address or M-address via the federation protocol before use in transactions.
51+
For CAIP-10 purposes, federated addresses should be resolved to their canonical G or M format.
52+
53+
### Syntax
54+
55+
The `account_id` is a case-insensitive string in the form:
56+
57+
```sh
58+
account_id: chain_id + ":" + account_address
59+
chain_id: See [CAIP-2][]
60+
account_address: classic_address | muxed_address
61+
classic_address: G[A-Z2-7]{55} + optional_memo
62+
optional_memo: ("-" + memo_value)?
63+
memo_value: memo_text | memo_id | memo_hash
64+
memo_text: [^\-]{1,28}
65+
memo_id: [0-9]{1,20}
66+
memo_hash: [0-9a-fA-F]{64}
67+
muxed_address: M[A-Z2-7]{68}
68+
```
69+
70+
### Semantics
71+
72+
The `chain_id` is specified by the [CAIP-2][] which describes the blockchain id
73+
(typically `stellar:pubnet` or `stellar:testnet`).
74+
75+
The `account_address` represents an account on the Stellar network and can be
76+
expressed in multiple formats:
77+
78+
1. **Classic Address (G-address)**: A base32-encoded Ed25519 public key,
79+
optionally followed by a memo. Memos are used to identify specific recipients
80+
or purposes at the destination address and come in several types:
81+
82+
* **MEMO_TEXT**: A string up to 28 bytes, encoded in ASCII or UTF-8
83+
* **MEMO_ID**: A 64-bit unsigned integer (0 to 18446744073709551615)
84+
* **MEMO_HASH**: A 32-byte hash (64 hex characters)
85+
* **MEMO_RETURN**: A 32-byte hash intended as the hash of a transaction being refunded
86+
87+
When included, the memo is separated from the address by a hyphen (`-`).
88+
89+
2. **Muxed Address (M-address)**: A compact format that encodes both the classic
90+
G-address and a 64-bit memo ID into a single base32-encoded string starting
91+
with `M`. Muxed addresses eliminate the need for separate memo handling and
92+
reduce user error. They are particularly useful for custodial services and
93+
exchanges that use pooled accounts.
94+
95+
**Important Notes**:
96+
97+
* Memos (especially `MEMO_ID`) are critical for exchange deposits and withdrawals
98+
* Forgetting a memo when sending to an exchange typically results in lost funds
99+
or delayed crediting
100+
* Muxed addresses provide a safer alternative by embedding the memo ID directly
101+
in the address
102+
* Only `MEMO_ID` can be encoded in muxed addresses; `MEMO_TEXT` and `MEMO_HASH` require
103+
classic addresses with appended memos
104+
105+
## Test Cases
106+
107+
This is a list of manually composed examples
108+
109+
```sh
110+
# Pubnet classic address (without memo)
111+
stellar:pubnet:GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ
112+
113+
# Testnet classic address (without memo)
114+
stellar:testnet:GCEZWKCA5VLDNRLN3RPRJMRZOX3Z6G5CHCGSNFHEYVXM3XOJMDS674JZ
115+
116+
# Classic address with MEMO_ID
117+
stellar:pubnet:GDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOKY3B2WSQHG4W37-123456789
118+
119+
# Classic address with MEMO_TEXT
120+
stellar:pubnet:GDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOKY3B2WSQHG4W37-payment-reference
121+
122+
# Classic address with MEMO_HASH (hex-encoded)
123+
stellar:pubnet:GDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOKY3B2WSQHG4W37-b64aa7c0f6d5f5f6e8f1d1c7f5e5d5c5f5e5d5c5f5e5d5c5f5e5d5c5f5e5d5c5
124+
125+
# Muxed address (Pubnet) with embedded ID 0
126+
stellar:pubnet:MA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJUAAAAAAAAAAAACJUQ
127+
128+
# Muxed address (Pubnet) with embedded ID 420
129+
stellar:pubnet:MA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJUAAAAAAAAAABUTGI4
130+
131+
# Muxed address (Testnet)
132+
stellar:testnet:MCEZWKCA5VLDNRLN3RPRJMRZOX3Z6G5CHCGSNFHEYVXM3XOJMAAAAAAAAAAAJLKA
133+
```
134+
135+
## Backwards Compatibility
136+
137+
Classic G-addresses without memos maintain full backward compatibility with
138+
existing Stellar implementations. Muxed M-addresses (Protocol 13+) may not be
139+
supported by older clients and should be verified before use.
140+
141+
## References
142+
143+
* [Stellar Account Addressing][] - Overview of Stellar account addressing
144+
* [SEP-0023: Strkey][SEP-0023] - Specification for strkey encoding used in Stellar addresses
145+
* [CAP-0027: Muxed Accounts][CAP-0027] - Proposal for muxed account support
146+
* [Stellar Memos][] - Detailed explanation of memo types and usage
147+
* [SEP-0002: Federation Protocol][SEP-0002] - Human-readable federated addresses
148+
* [Pooled Accounts Guide][] - Guide to muxed accounts and memos for pooled accounts
149+
150+
151+
[CAIP-2]: ./caip2.md
152+
[CAIP-10]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-10.md
153+
[Stellar Account Addressing]: https://developers.stellar.org/docs/learn/fundamentals/stellar-data-structures/accounts
154+
[SEP-0023]: https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0023.md
155+
[CAP-0027]: https://stellar.org/protocol/cap-27
156+
[RFC 4648]: https://datatracker.ietf.org/doc/html/rfc4648
157+
[Stellar Memos]: https://developers.stellar.org/docs/learn/encyclopedia/transactions-specialized/memos
158+
[SEP-0002]: https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0002.md
159+
[Pooled Accounts Guide]: https://developers.stellar.org/docs/learn/encyclopedia/transactions-specialized/pooled-accounts-muxed-accounts-memos
160+
161+
## Copyright
162+
163+
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

‎stellar/caip19.md‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
---
2+
namespace-identifier: stellar-caip19
3+
title: Stellar Namespace - Assets
4+
author: Pelle Braendgaard (@pelle)
5+
discussions-to: https://github.com/ChainAgnostic/namespaces/pull/157
6+
status: Draft
7+
type: Standard
8+
created: 2025-11-06
9+
requires: ["CAIP-2", "CAIP-10", "CAIP-19", "CAIP-20"]
10+
---
11+
12+
# CAIP-19
13+
14+
*For context, see the [CAIP-19][] specification.*
15+
16+
## Rationale
17+
18+
In the Stellar ecosystem, assets can be represented in several distinct formats.
19+
The native asset (lumens/XLM) is identified using the SLIP-44 coin type registry (coin type 148), while issued assets are uniquely identified by combining an asset code (1-12 characters) with an issuer account address, separated by a hyphen.
20+
Additionally, Protocol 18 introduced liquidity pool shares (defined in [CAP-38]) which represent fractional ownership in automated market maker pools, and Protocol 20 introduced Soroban smart contract tokens following the SEP-41 token interface standard.
21+
22+
## Syntax
23+
24+
After the [CAIP-2] namespace+chainID, a slash defines an `asset_namespace` and an `asset_reference`.
25+
Stellar supports multiple asset types with different identification schemes:
26+
27+
### Asset Namespaces
28+
29+
| Namespace | Description | Reference Format |
30+
| :--- | :--- | :--- |
31+
| `slip44` | Native lumens (XLM) via SLIP-44 | `148` (Stellar's coin type) |
32+
| `asset` | Issued asset with code and issuer | `{asset_code}-{issuer_address}` |
33+
| `cap38` | Liquidity pool shares (CAP-38) | `{pool_id}` (64-char hex hash) |
34+
| `sep41` | Soroban smart contract token (SEP-41) | `{contract_address}` (56-char strkey) |
35+
36+
### Asset Code Requirements
37+
38+
Asset codes for issued assets must:
39+
40+
- Consist of printable ASCII characters (octets `0x21` through `0x7e`)
41+
- Be 1-12 characters in length
42+
- Be case-sensitive
43+
- Not contain the hyphen character (`-`) as it is used as the delimiter
44+
45+
### Issuer Address
46+
47+
The issuer address must be a valid Stellar G-address (56 characters, starting with `G`).
48+
49+
### Liquidity Pool ID
50+
51+
Liquidity pool IDs are deterministically calculated as:
52+
53+
- SHA-256 hash of the liquidity pool parameters
54+
- Pool parameters include: pool type and both assets in lexicographical order
55+
- Represented as a 64-character lowercase hexadecimal string
56+
- Only one pool can exist for a given asset pair
57+
58+
### Contract Address
59+
60+
Soroban contract addresses are:
61+
62+
- Stellar `strkey`-encoded contract addresses (56 characters, starting with `C`)
63+
- For Stellar Asset Contracts (SAC), the address can be derived from the classic asset identifier
64+
- Can be obtained using: `stellar contract id asset --asset {code}:{issuer} --network {network}`
65+
66+
## RegEx
67+
68+
The RegEx validation strings are as follows:
69+
70+
```sh
71+
asset_id: asset_type
72+
asset_type: chain_id + "/" + asset_namespace + ":" + asset_reference
73+
chain_id: namespace + ":" + blockchain_id (as defined in [CAIP-2])
74+
75+
asset_namespace: "slip44" | "asset" | "cap38" | "sep41"
76+
77+
asset_reference: slip44_ref | asset_ref | cap38_ref | sep41_ref
78+
slip44_ref: "148"
79+
asset_ref: asset_code + "-" + issuer_address
80+
asset_code: [!-,.-~]{1,12}
81+
issuer_address: G[A-Z2-7]{55}
82+
cap38_ref: [0-9a-f]{64}
83+
sep41_ref: C[A-Z2-7]{55}
84+
```
85+
86+
Note: The `asset_code` regex `[!-,.-~]` excludes the hyphen character (ASCII 0x2D) from the printable ASCII range (0x21-0x7E) since hyphen is used as the delimiter.
87+
88+
## Semantics
89+
90+
### Native Asset (XLM/Lumens)
91+
92+
The native asset is identified using the `slip44` namespace with coin type `148` as registered in the SLIP-44 registry.
93+
The native asset is unique and does not require an issuer.
94+
It is used for:
95+
96+
- Transaction fees (which are burned/destroyed)
97+
- Minimum account balance requirements (base reserves)
98+
- Bridge currency for cross-asset transactions
99+
100+
Example: `stellar:pubnet/slip44:148`
101+
102+
### Issued Assets
103+
104+
Issued assets are created by issuers and must be explicitly trusted by recipients before they can be received.
105+
The combination of asset code (1-12 characters) and issuer address uniquely identifies an asset.
106+
On the Stellar network, asset codes of 1-4 characters are stored as `AlphaNum4`, while codes of 5-12 characters are stored as `AlphaNum12`, but both use the same `asset` namespace in [CAIP-19].
107+
108+
Examples:
109+
110+
- USDC issued by Circle: `asset:USDC-{issuer_address}`
111+
- Custom 8-character code: `asset:MYTOKEN8-{issuer_address}`
112+
113+
### Liquidity Pool Shares (CAP-38)
114+
115+
Liquidity pool shares represent fractional ownership in constant product automated market maker pools (CPAMM) as defined in [CAP-38]. These shares:
116+
117+
- Are non-transferable (cannot be sent between accounts)
118+
- Can be minted by depositing assets into the pool
119+
- Can be redeemed for the underlying assets
120+
- Are identified by a deterministic pool ID hash
121+
- Use the `cap38` namespace
122+
123+
### Soroban Contract Tokens (SEP-41)
124+
125+
Soroban contract tokens follow the [SEP-41] token interface standard and include:
126+
127+
- Stellar Asset Contracts (SAC): Wrapped versions of classic Stellar assets with smart contract functionality
128+
- Custom [CAP-46-6] -compliant tokens: Fully custom tokens implemented as Soroban smart contracts
129+
- All tokens use the `sep41` namespace and are identified by their contract address
130+
131+
## Examples
132+
133+
```sh
134+
# Native asset (lumens/XLM) on Pubnet
135+
stellar:pubnet/slip44:148
136+
137+
# Native asset on Testnet
138+
stellar:testnet/slip44:148
139+
140+
# USDC (4-character code) on Pubnet
141+
stellar:pubnet/asset:USDC-GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN
142+
143+
# Custom token with 8-character code on Pubnet
144+
stellar:pubnet/asset:MYCOIN88-GDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOKY3B2WSQHG4W37
145+
146+
# Single character asset code on Testnet
147+
stellar:testnet/asset:X-GCEZWKCA5VLDNRLN3RPRJMRZOX3Z6G5CHCGSNFHEYVXM3XOJMDS674JZ
148+
149+
# Liquidity pool (XLM-USDC pool) on Pubnet
150+
stellar:pubnet/cap38:67260c4c1807b262ff851b0a3fe141194936bb0215b2f77447f1df11998eabb9
151+
152+
# Soroban token contract (USDC) on Pubnet
153+
stellar:pubnet/sep41:CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75
154+
155+
# Custom Soroban token contract on Testnet
156+
stellar:testnet/sep41:CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABSC4
157+
```
158+
159+
## Backwards Compatibility
160+
161+
Issued Stellar assets (represented here as the `asset` namespace) correspond to the native Stellar `alphanum4` and `alphanum12` asset types, which have been supported since the genesis of the Stellar network and maintain full backward compatibility.
162+
163+
Liquidity pool shares were introduced in Protocol 18 (November 2021) and may not be supported by older clients.
164+
165+
Soroban contract tokens were introduced in Protocol 20 (February 2024) and require Soroban-aware clients and tooling.
166+
167+
## References
168+
169+
- [Stellar Assets Overview][] - Overview of asset types on Stellar
170+
- [SLIP-44][] - Registered coin types for HD wallets
171+
- [CAIP-20][] - Asset Reference for the SLIP44 Asset Namespace
172+
- [CAP-38: Automated Market Makers][CAP-38] - Liquidity pools specification
173+
- [CAP-46-6: Smart Contract Standardized Asset][CAP-46-6] - Soroban token standard
174+
- [SEP-41: Token Interface][SEP-41] - Standard token interface for Soroban
175+
- [Stellar Asset Contract][] - Documentation for Stellar Asset Contracts
176+
- [Liquidity Pools Guide][] - Guide to using liquidity pools on Stellar
177+
178+
179+
[CAIP-2]: ./caip2.md
180+
[CAIP-10]: ./caip10.md
181+
[CAIP-19]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-19.md
182+
[CAIP-20]: https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-20.md
183+
[SLIP-44]: https://github.com/satoshilabs/slips/blob/master/slip-0044.md
184+
[Stellar Assets Overview]: https://developers.stellar.org/docs/learn/fundamentals/stellar-data-structures/assets
185+
[CAP-38]: https://github.com/stellar/stellar-protocol/blob/master/core/cap-0038.md
186+
[CAP-46-6]: https://github.com/stellar/stellar-protocol/blob/master/core/cap-0046-06.md
187+
[SEP-41]: https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0041.md
188+
[Stellar Asset Contract]: https://developers.stellar.org/docs/tokens/stellar-asset-contract
189+
[Liquidity Pools Guide]: https://developers.stellar.org/docs/learn/encyclopedia/sdex/liquidity-on-stellar-sdex-liquidity-pools
190+
191+
## Copyright
192+
193+
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

0 commit comments

Comments
 (0)