diff --git a/massa/README.md b/massa/README.md new file mode 100644 index 0000000..76d3224 --- /dev/null +++ b/massa/README.md @@ -0,0 +1,79 @@ +--- +namespace-identifier: massa +title: Massa +author: ["Billy Rennekamp (@okwme)"] +discussions-to: https://github.com/0xcounting/FAR/issues/1 +status: Draft +type: Informational +created: 2026-09-14 +--- + +# Namespace for Massa blockchains + +Massa is a layer-1 blockchain whose block production is spread over 32 parallel threads, giving it a block graph rather than a single chain of blocks. +It also runs autonomous smart contracts, which can schedule their own future execution without an external caller, and hosts websites on chain through DeWeb. +The `massa` namespace covers networks that run the Massa node software and expose its JSON-RPC and gRPC interfaces. +Individual networks in the namespace are identified by the node's `chain_id`, as specified in the [Massa CAIP-2 profile][]. + +## Address prefixes + +Massa addresses are structured strings rather than opaque blobs, and reading them saves an implementer a surprising amount of work. +An address is the character `A`, then a category character, then a base58check-encoded payload. +The category character is `U` for a user address, which is derived from a public key, and `S` for a smart contract address. +So `AU1…` is a wallet and `AS1…` is a deployed contract, and the distinction is visible without any node round trip. + +The `1` that almost every Massa address carries in third position is **not** part of a fixed prefix. +The base58check payload encodes a varint version number followed by the 32-byte hash, and the current address version is `0`. +A varint `0` is the single byte `0x00`, and base58 renders a leading zero byte as the digit `1`, so the version shows through as a `1`. +An implementer who hard-codes the literal three-character prefixes `AU1` and `AS1` will therefore break on the first address issued under address version 1. +The correct parse is: match `A`, read the category character `U` or `S`, base58check-decode the remainder, and read the leading varint as the version. + +The burn address `AU1111111111111111111111111111111112m1s9K` is a useful worked example, since its hash is all zero bytes and every one of those bytes renders as another `1`. + +## Rationale + +`massa` is the ecosystem's own name, is five characters long, and uses only lowercase letters, so it satisfies the CAIP-2 namespace production `[-a-z0-9]{3,8}` directly. +No abbreviation or disambiguation was needed, and no competing spelling is in circulation. + +Massa's `chain_id` is a `u64` that was added, explicitly citing [EIP-155][] and [EIP-1344][] as precedent, so that an operation signed for one Massa network cannot be replayed on another. +It is therefore exactly the discriminator CAIP-2 is asking for: a value that already defines, inside the protocol, which network a signed payload belongs to. +The values are also a small joke that is worth knowing, because it makes them memorable and self-checking. +MainNet's `77658377` is the ASCII code points of `MASM` written out in sequence — `M`=77, `A`=65, `S`=83, `M`=77. +BuildNet's `77658366` is `MASB`, and SecureNet's `77658383` is `MASS`. + +This namespace was drafted by the maintainers of FAR, an open cross-reference between CAIP-19, CoinGecko and ISO 24165 identifiers, which needs a CAIP-2 for this chain in order to name the assets that exist on it. +The authors do not represent the Massa ecosystem. +It is offered as a starting point for the Massa community to correct, adopt or replace, and the authors would rather it carry a maintainer's name than theirs. + +## Governance + +Massa's protocol is developed by Massa Labs in the open, in the [Massa reference implementation][]. +Protocol-level parameter and behaviour changes are shipped as Massa Improvement Proposals (MIPs) through an in-protocol versioning mechanism: a MIP is announced, votes are gathered from block producers, and the network activates it at an agreed point. +The currently active version is reported by the node as `current_mip_version` in the [`get_status`][] response, which was `1` at the time of writing, corresponding to MIP-0001. +Application-level conventions, including the MRC-20 fungible token standard, live in [Massa standards][] rather than in the node repository. + +## References + +- [Massa documentation][] - Concepts, node operation, and network constants +- [Massa reference implementation][] - The Rust node, and the source of the `CHAINID` constant +- [Massa network constants][] - Published `CHAINID`, genesis timestamp, and thread count per network +- [`get_status`][] - JSON-RPC method that reports a node's `chain_id` +- [Massa public networks][] - Endpoints for MainNet and BuildNet +- [Massa operation format][] - Binary serialization and the base58check encoding used by addresses +- [Massa standards][] - Community token and wallet standards, including MRC-20 +- [Massa CAIP-2 profile][] - The chain ID specification in this namespace + +[Massa documentation]: https://docs.massa.net/ +[Massa reference implementation]: https://github.com/massalabs/massa +[Massa network constants]: https://docs.massa.net/docs/node/constants +[`get_status`]: https://docs.massa.net/docs/build/api/jsonrpc +[Massa public networks]: https://docs.massa.net/docs/build/networks-faucets/public-networks +[Massa operation format]: https://docs.massa.net/docs/learn/operation-format-execution +[Massa standards]: https://github.com/massalabs/massa-standards +[Massa CAIP-2 profile]: ./caip2.md +[EIP-155]: https://eips.ethereum.org/EIPS/eip-155 +[EIP-1344]: https://eips.ethereum.org/EIPS/eip-1344 + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). diff --git a/massa/caip2.md b/massa/caip2.md new file mode 100644 index 0000000..efb7c27 --- /dev/null +++ b/massa/caip2.md @@ -0,0 +1,195 @@ +--- +namespace-identifier: massa-caip2 +title: Massa Namespace - Blockchain ID Specification +author: ["Billy Rennekamp (@okwme)"] +discussions-to: https://github.com/0xcounting/FAR/issues/1 +status: Draft +type: Standard +created: 2026-09-14 +requires: CAIP-2 +--- + +# CAIP-2 + +*For context, see the [CAIP-2][] specification.* + +## Introduction + +Every Massa node is configured with an unsigned 64-bit `chain_id`. +The value is mixed into the signed form of every operation, so an operation signed for one Massa network is invalid on any other, which is the same replay-protection role [EIP-155][] plays for EVM chains. +The `massa` CAIP-2 profile identifies a network by encoding that `chain_id` as a canonical unsigned decimal string. + +## Specification + +### Semantics + +A Massa chain ID consists of the literal namespace `massa`, a colon, and a reference holding the network's `chain_id`. +Two networks configured with the same `chain_id` have the same CAIP-2 chain ID by definition. +The `chain_id` is a protocol constant of the node build, not a runtime-negotiated value, so it is stable for the lifetime of a network. + +### Syntax + +```text +chain_id: "massa:" + reference +namespace: massa +reference: 0 | [1-9][0-9]{0,19} +``` + +The reference must match the following regular expression: + +```regex +^(0|[1-9][0-9]{0,19})$ +``` + +The parsed value must additionally be in the unsigned 64-bit integer range `0` through `18446744073709551615`, inclusive. +The regular expression alone is not sufficient to enforce the upper bound. +The longest possible reference is 20 digits, which is within the 32-character limit CAIP-2 places on references, so no truncation is ever needed. + +The reference uses ASCII decimal digits with no sign, base prefix, digit separators, surrounding whitespace, or leading zeroes. + +### Resolution Mechanics + +To resolve the chain ID reported by a Massa JSON-RPC endpoint, call the [`get_status`][] method: + +```json +{ + "jsonrpc": "2.0", + "method": "get_status", + "params": [], + "id": 1 +} +``` + +The `chain_id` is returned as a JSON number at `result.chain_id`. +The following is an abbreviated response from a MainNet node at `https://mainnet.massa.net/api/v2`: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "version": "MAIN.5.0", + "chain_id": 77658377, + "current_mip_version": 1, + "config": { + "genesis_timestamp": 1705312800000, + "thread_count": 32 + } + } +} +``` + +Validate the returned value as a `u64`, serialize it in canonical unsigned decimal form, and prefix it with `massa:`. +The example response therefore resolves to `massa:77658377`. + +The same value is also readable from on-chain code through the AssemblyScript smart-contract SDK, so a contract can assert which network it is executing on. + +## Rationale + +`chain_id` is the only value in the Massa protocol whose purpose is to say which network a signed payload belongs to. +Using it requires no registry, no transformation, and no trusted third party, and it works identically for the public networks and for privately operated ones. + +Decimal encoding matches the JSON-RPC representation, which returns `chain_id` as a JSON number rather than a string. +It also avoids having two textual forms for one network, which is what a hexadecimal or zero-padded encoding would introduce. + +The genesis block hash was considered and rejected as the reference. +Massa produces blocks in 32 parallel threads, so "the genesis block" is 32 blocks rather than one, and no single hash is canonical for a network. + +The published values are derived from four-letter network codes written out as ASCII code points, which is a useful sanity check when reviewing a value by eye. +`MASM` (MainNet) is `77 65 83 77`, giving `77658377`. +`MASB` (BuildNet) is `77 65 83 66`, giving `77658366`. +`MASS` (SecureNet) is `77 65 83 83`, giving `77658383`. +`MASL` (LabNet) is `77 65 83 76`, giving `77658376`. + +## Well-Known Networks + +The following table allows clients to label well-known networks without an RPC round trip. +It is informative; the resolution method above remains authoritative. + +| Network | `chain_id` | CAIP-2 chain ID | +| --- | ---: | --- | +| Massa MainNet | `77658377` | `massa:77658377` | +| Massa BuildNet (public test network) | `77658366` | `massa:77658366` | +| Massa SecureNet | `77658383` | `massa:77658383` | +| Massa LabNet | `77658376` | `massa:77658376` | +| Sandbox (local development) | `77` | `massa:77` | + +The MainNet and BuildNet values were read from live nodes and also appear in the [Massa network constants][] documentation. +All five values are defined in the `CHAINID` constant of the [Massa reference implementation][], which selects them from the node's version string. + +## Private Networks and Collisions + +The sandbox value `77` is a fixed constant shared by every node built with a `SAND*` version string. +Every local sandbox in the world therefore resolves to `massa:77`, and that identifier must not be treated as naming one globally unique network. + +An operator running a private Massa network with a modified `CHAINID` is choosing a value that no registry allocates. +If two distinct networks pick the same `chain_id`, this profile cannot distinguish them and their CAIP-2 chain IDs collide. +Such operators should pick a value well away from the five above and keep it stable for the life of the network. + +## Backwards Compatibility + +There was no previously registered CAIP-2 profile for Massa. +This profile does not change any native Massa identifier. + +`chain_id` was introduced during the Massa testnet phase, before MainNet launch, and MainNet has carried `77658377` since genesis, so no legacy form needs to be accepted. + +## Test Cases + +### Valid identifiers + +| Identifier | Reason | +| --- | --- | +| `massa:77658377` | Massa MainNet | +| `massa:77658366` | Massa BuildNet, the public test network | +| `massa:77658383` | Massa SecureNet | +| `massa:77` | Local sandbox, not a globally unique network | +| `massa:0` | Valid zero reference | +| `massa:18446744073709551615` | Upper `u64` boundary, 20 digits | + +### Invalid identifiers + +| Identifier | Reason | +| --- | --- | +| `massa:` | Empty reference | +| `massa:00` | Non-canonical zero | +| `massa:077658377` | Leading zero | +| `massa:-1` | Signed value | +| `massa:0x4a0f909` | Hexadecimal representation | +| `massa:77_658_377` | Digit separator | +| `massa: 77658377` | Leading whitespace | +| `massa:18446744073709551616` | Above the `u64` maximum | +| `massa:MASM` | Four-letter network code rather than the numeric `chain_id` | +| `MASSA:77658377` | Incorrect namespace casing | + +## Additional Considerations + +Massa addresses carry a category character and a version byte that a later CAIP-10 profile will need to specify; see the [namespace README][] for the `AU1…` / `AS1…` scheme. +A later CAIP-19 profile will need to distinguish the native coin MAS from MRC-20 tokens, which are ordinary smart contracts identified by an `AS…` address. + +## Security Considerations + +Resolving a chain ID through `get_status` establishes only what the queried endpoint reports. +It does not authenticate the endpoint, and it does not make an operator-chosen `chain_id` globally unique. +Applications that depend on a trusted chain identity should use authenticated endpoints, or corroborate the reported `chain_id` against the `genesis_timestamp` and other configuration values in the same response. + +## References + +- [CAIP-2][] - Blockchain ID specification +- [Massa reference implementation][] - The `CHAINID` constant and its per-network values +- [`get_status`][] - JSON-RPC method that reports `chain_id` +- [Massa network constants][] - Published `CHAINID` values for MainNet and BuildNet +- [Massa public networks][] - Public endpoints used to verify the values in this document +- [EIP-155][] - The replay-protection design Massa's `chain_id` cites as precedent +- [namespace README][] - Massa namespace overview and address prefix scheme + +[CAIP-2]: https://chainagnostic.org/CAIPs/caip-2 +[Massa reference implementation]: https://github.com/massalabs/massa/blob/main/massa-models/src/config/constants.rs +[`get_status`]: https://docs.massa.net/docs/build/api/jsonrpc +[Massa network constants]: https://docs.massa.net/docs/node/constants +[Massa public networks]: https://docs.massa.net/docs/build/networks-faucets/public-networks +[EIP-155]: https://eips.ethereum.org/EIPS/eip-155 +[namespace README]: ./README.md + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).