CloudCoin File Format 9

The plaintext coin file format. Format 9 is what a wallet holds when file encryption is off, and it is the only format used for exporting coins to other people.

Format byte 9 / 0x09

Single-coin size 439 bytes

Coins per file 1 to 65535

Encryption None

⚠️ Format 9 encryption is retired — read this first

Byte 5 of the header is an encryption_type field, and older CloudCoin software used it to encrypt coin files in place (value 1 = AES-128-CTR, value 4 = AES-256-CTR). The current core no longer reads or writes those encrypted variants. A Format 9 file is valid only with encryption_type = 0.

The reason is not that AES is broken. The old scheme derived its key with a single SHA-256 pass over the password (fast to brute-force), reused a nonce derived from the key rather than a random one, and — worst of all — stored a small password-check value inside the file. That check value let anyone holding a stolen file test candidate passwords offline at enormous speed, which is exactly the attack encryption is supposed to prevent.

Encryption now lives in Format 10, which was designed specifically so that a stolen file gives an attacker nothing to test against. If the core meets a Format 9 file with a non-zero encryption_type, it reports RESULT_UNSUPPORTED_FORMAT and tells the user to restore a plaintext backup. It does not attempt to decrypt it and it does not treat it as corrupt.

1. What a Format 9 file is for

Format 9 serves two distinct roles, and the difference matters:

Wallet storage (single-coin). Every coin in a wallet folder lives in its own file containing exactly one coin. This is what the core reads and writes during ordinary operation when encryption is off.
Export (multi-coin). When coins are sent to another person, many coins may be packed into one file. Multi-coin files are export-only — the core never stores them inside a wallet folder, and they are always plaintext, because the recipient does not have your password.

A single-coin Format 9 file is exactly 439 bytes: a 32-byte file header, a 7-byte coin record header, and 400 bytes of authenticity numbers. A multi-coin file is 32 + (407 × coin_count) bytes.

2. File header (32 bytes)

Offset	Size	Field	Description
0	1	`file_format`	Format version. 0x09 for this format. The first byte is how software decides which parser to use.
1	1	`reserved`	Reserved; written as 1.
2–3	2	`coin_id`	Big-endian coin identifier. 0x0006 = CloudCoin.
4	1	`experimental`	Free for application use.
5	1	`encryption_type`	MUST be 0x00 (plaintext). Values 1 and 4 are the retired encrypted variants described above.
6–7	2	`token_count`	Big-endian count of coins in this file. `1` for wallet files.
8–14	7	`password_hash`	Legacy field from the retired encryption. Unused and zero in current files.
15	1	`future_use`	Reserved.
16–31	16	`extra`	Dual purpose — see below.

The `extra` field

Bytes 16–31 mean different things depending on token_count:

Single-coin file: bytes 16–28 hold the packed 13-byte POWN status (see below) and bytes 29–31 hold a 24-bit task identifier.
Multi-coin file: the 16 bytes hold the ASCII motto Live Free or Die. This is how a reader can tell an export bundle at a glance.

3. Coin records

After the header, each coin is 407 bytes: a 7-byte record header followed by 400 bytes of authenticity numbers.

Offset (within record)	Size	Field	Description
0	1	`split`	Split identifier; 0.
1	1	`shard`	Shard identifier; 0.
2	1	`denomination`	Signed byte, −8 through +11. Determines the coin's value.
3–6	4	`serial_number`	Big-endian 32-bit serial number.
7–406	400	`ans`	25 authenticity numbers, 16 bytes each, in RAIDA index order 0 through 24.

⚠️ These 400 bytes are the money

The authenticity numbers are the coin. Anyone who learns 13 of the 25 can take ownership of it by changing those ANs at the RAIDA servers. In a Format 9 file they sit on disk in the clear — which is precisely the exposure Format 10 exists to remove.

4. POWN status encoding

For single-coin files, bytes 16–28 record what the RAIDA last said about each of the 25 authenticity numbers. Two statuses are packed per byte, one nibble each:

byte_offset = 16 + floor(n / 2) even n → high nibble (bits 7–4) odd n → low nibble (bits 3–0)

That covers 25 nibbles across 12.5 bytes; the unused low nibble of byte 28 is padding and is always 0x9. The common status values are 0x0 (unknown/untried), 0xA (confirmed authentic), and 0xF (confirmed counterfeit). A coin is considered authentic when at least 13 of the 25 report 0xA.

POWN is a cache, not proof. It records what the RAIDA said the last time anybody asked. It is stored in the clear, it is not authenticated, and anyone with write access to the file can change it. Software must never treat it as evidence of ownership or authenticity — it exists so the wallet can show a status without going to the network. Format 10 keeps POWN in the clear for exactly the same reason.

5. Reading and writing

Read byte 0. 0x09 selects this parser; 0x0A selects the Format 10 parser.
Verify coin_id is 0x0006.
If encryption_type is not zero, stop: this is a retired encrypted variant and is unsupported.
Read token_count. Verify the physical file size equals 32 + (407 × token_count) — a mismatch means truncation or a malformed count, and the file must be rejected rather than parsed.
Read each 407-byte record. For single-coin files, decode POWN from extra.

Writes are atomic: the core writes a temporary file in the destination folder, flushes it, and renames it over the target, so a crash or removed USB drive can never leave a half-written coin.

6. Relationship to Format 10

The two formats are two states of the same wallet, and the first byte tells them apart:

	Format 9	Format 10
First byte	0x09	0x0A
Single-coin size	439 bytes	612 bytes (fixed)
Coins per file	1 or many	Always exactly 1
Authenticity numbers	Plaintext	Encrypted (AES-256-CTR)
Used for export	Yes — the only export format	Never; wallet-internal only

A wallet is either all Format 9 or all Format 10. Encrypting converts every coin file one way; decrypting converts them back. Exported coins are always written as Format 9, because the recipient has no way to derive your password-based key.

For how the conversion is driven, what happens to the password, and an honest assessment of what the encryption does and does not protect against, see How file encryption works.