Skip to content
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
120 lines (83 sloc) 5.06 KB
FATIP Title Status Category Author Created
100 FAT Token Chain ID Derivation Standard Accepted Core Devon Katz <> 8-17-2018


This standard defines how to derive a FAT Token Chain ID from its Token ID and Issuer Identity Chain ID.


Factom indexes chains by a 32 byte Chain ID. Chain IDs are deterministically generated from the ordered set of Name IDs for the chain, the External IDs of the very first entry in the chain. Thus a predictable format for the Name IDs of a Token Chain allows users to easily find the Chain ID for a given token, and allows implementations to filter and detect Token Chains established on Factom.


Issuer and Issuer Identity Chain

An Issuer is any entity creating a token. An Issuer must have a valid Identity Chain that they control. The Identity Chain establishes the currently accepted public key. The Token Chain specification may require a valid signature from the Identity's current key for certain special entries, like those controlling token initialization and coinbase transactions. An Issuer may control more than one Identity Chain.

Token ID

A Unicode string unique to the Issuer's Identity. It should be something short and memorable related to the token.

Note that the same Token ID may be issued under two different Identities. Tokens sharing the same Token ID under different Identities are still distinct tokens. Ultimately it is up to users to decide which Issuer's token they wish to use. Depending on the power that the Issuer has according to the Token Specification, trust in an Issuer may be necessary to trust the integrity of future decisions concerning the token.

Token Chain Name IDs

The Token Chain ID is calculated by using the Token ID and the Issuer's Identity Chain ID.

Name ID Index Encoding Example Details
0 Unicode String "token" Must be exactly equal
1 Unicode String "test" Any valid Unicode String
2 Unicode String "issuer" Must be exactly equal
3 32 Raw Bytes 0x88 88 88 07 e4 f3 bb b9 a2 b2 29 64 5a b6 d2 f1 84 22 41 90 f8 3e 78 76 16 74 c2 36 2a ca 44 25 Must be a valid Identity Root Chain ID

The Name IDs follow a key/value pair format. Thus the Name IDs can be thought of like this: "token": <Token ID>, "issuer": <Issuer Identity Chain ID>.

Quoted strings indicate that the quoted text is used (without quotes) as the External ID.

Chain ID Derivation

From the Factom Documentation:

A ChainID is a series of SHA256 hashes of Chain Name segments. The ChainID is 32 bytes long. The ChainID must be the hash of something to only have opaque data in the higher level block structures.

The algorithm hashes each segment of the Chain Name. Those hashes are concatenated, and are hashed again into a single 32 byte value.

Getting a ChainID from a single segment Chain Name would be equivalent of hashing the Chain Name twice.

ChainID = SHA256( SHA256(Name[0]) | SHA256(Name[1]) | ... | SHA256(Name[X]) )

The standard human readable form of a Chain IDs is a hex encoded string.

For example, the hex encode Chain ID for the above example Name IDs in the table is b54c4310530dc4dd361101644fa55cb10aec561e7874a7b786ea3b66f2c6fdfb.

The External IDs of the first entry in a chain are called the Chain's Name Segments or Name IDs. We use the term External ID in this document to refer to a chain's Name Segments. Name Segments are just a special term for the External IDs of the first entry in a chain.


Because the Token Chain ID is determined by the Token ID and Issuer ID, there is no way to alter these values once the Token Chain is created.

Creating a Token Chain is necessary but generally not sufficient to issue a FAT token. The various FAT token specifcations describe additional steps required to issue a token, typically involving the creation of an entry that includes a signature from the Issuer's Identity. This disincentivizes squatting on Token IDs, as all Token IDs are scoped by the Identity Chain they are issued under. If someone wishes to create a Token Chain under an Identity they do not control, at worst they have simply created a Token Chain that will never get initialized by the entity controling the Identity. At best, they have paid the EC's for a Token Chain that the Issuer was intending to create anyway.

This specification does not strictly require that the Identity Chain exist prior to creating the Token Chain. However, the Identity Chain ID of course must be known at the time that the Token Chain is created. It is generally unwise and impractical to create a Token Chain based on an Identity whose chain has not yet been created and published.


Copyright and related rights waived via CC0.

You can’t perform that action at this time.