Glittr Output Structure

In this page, we will learn about the Glittr output structure. The Glittr output consists of 5 parts:

• OP_RETURN opcode: the native Bitcoin opcode for the return data.

• Glittr Magic prefix: used to mark the Glittr transaction; Glittr uses string bytes of "GLITTR", *this will change latter, will use more compact prefix.

• Header

• The Glittr message payload: where the actual data goes

[OP_RETURN][GLITTR][Header][Payload]

The data should be less than or equal to 80 bytes

Header

The header is a 1-byte data that consists of 2 parts:

• Version number: 6-bit number, 0 - 63

• Flags:

  • Compressed flag

  • Reserved flag

0x[000000][0][0]
0x[Version Number][Flag 1][Flag 2]

Version Number

Version number is for transaction versioning. It's a 6-bit number (0 - 63) used to handle different schema changes in the future so older versions can still be supported on the core. Currently, only version 0 is used.

Compressed Flag

The compressed flag indicates whether the message is compressed or not.

Glittr Message Payload

Payload is the actual data that's going to be sent to the transaction (transfer, contract creation, or contract call).

Encoding

The payload uses Borsh encoding to encode the data. The encoding is based on Borsh . We chose Borsh for simplicity and smaller size. The encoding is already implemented in the SDK, so users don't need to manually encode the data.

Data Type

To improve size efficiency, we use custom data types for the payload values like varuint/varint and azbase26, more details can be found on the glittr core repository.

Varuint/Varint

Varuint is a data type based on SQLite 4 Varuint type , supporting up to u128. For varint (signed or negative values), we use the zigzag method to convert it to unsigned integer.

AZBase26

Instead of using UTF8 for strings, we use a data type called AZBase26. As the name suggests, this data type is based on base26 encoding for characters A-Z, making it suitable for tickers or token names.

Compression

We use brotli for the payload compression, the compression is optional, it means the payload can be compressed or not compressed. If the compressed length is less than the non-compressed length, it will use compressed bytes and mark the header compressed flag as true. Sometimes if the data is too dense, the compressed version is larger than the non-compressed version, so the flag will be set to false.

Example

Compressed Payload

Payload has a lot of data, so the compression will play with it, most of the time the compressed version is smaller than the non-compressed version, the header will mark the compressed flag as true.

const tx: OpReturnMessage = {
  contract_creation: {
    contract_type: {
      nft: {
        asset_image: Array.from(
          Buffer.from(
            "50350a3820380a3235350affffffffffffffffffff13ff13ffffffffff13ff13ffffffffff13343434ffffffff1300fc0000ffffff139e9e9e9effffff13131313ffffff131334343434ff",
            "hex"
          )
        ),
        supply_cap: encodeVaruint(1),
        live_time: encodeVarint(0),
      },
    },
  },
  contract_call: {
    contract: null,
    call_type: {
      mint: {
        pointer: encodeVaruint(1),
      },
    },
  },
};

await txBuilder.compress(tx);

Glittr output structure{
  compressed: Buffer(80) [ 106, 6, 71, 76, 73, 84, 84, 82, 71, 2, 27, 96, 0, 248, 143, 196, 56, 22, 114, 176, 210, 184, 9, 42, 189, 230, 82, 59, 93, 178, 230, 154, 20, 188, 242, 0, 244, 64, 58, 89, 3, 194, 239, 24, 167, 131, 222, 244, 96, 54, 248, 194, 116, 45, 224, 192, 11, 181, 30, 240, 233, 219, 237, 237, 180, 170, 170, 198, 212, 204, 132, 161, 127, 171, 129, 76, 198, 86, 177, 2 ],

  nonCompresed: Buffer(108) [ 106, 6, 71, 76, 73, 84, 84, 82, 76, 98, 2, 0, 1, 3, 75, 0, 0, 0, 80, 53, 10, 56, 32, 56, 10, 50, 53, 53, 10, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 19, 255, 19, 255, 255, 255, 255, 255, 19, 255, 19, 255, 255, 255, 255, 255, 19, 52, 52, 52, 255, 255, 255, 255, 19, 0, 252, 0, 0, 255, 255, 255, 19, 158, 158, 158, 158, 255, 255, 255, 19, 19, 19, 19, 255, 255, 255, 19, 19, 52, 52, 52, 52, 255, 1, 1, 0, 0, 0, 0, 1, 0, 0, 1, 1, 0, 0, 0, 0 ]
}

That example show that brotli compression is effective to reduce the size of data, the compressed version is smaller than the non-compressed version (28 bytes saved).

Non Compressed payload

Payload is to dense, so the compressed version is larger than the non-compressed version, the header will mark the compressed flag as false.

const tx: OpReturnMessage = {
  contract_call: {
    contract: null,
    call_type: {
      mint: {
        pointer: encodeVaruint(1),
      },
    },
  },
};

await txBuilder.compress(tx);

{
  compressed: Buffer(23) [ 106, 6, 71, 76, 73, 84, 84, 82, 14, 0, 27, 10, 0, 248, 167, 0, 2, 194, 150, 72, 41, 121, 174 ],

  nonCompressed: Buffer(21) [ 106, 6, 71, 76, 73, 84, 84, 82, 12, 0, 0, 0, 1, 0, 0, 1, 1, 0, 0, 0, 0 ],
}

On the example above the non compressed length is smaller than compressed length, this is possible because the data is already to dense, the brotli compression added some overhead to it that's why the compressed length is larger than the non compressed length.

Exceeded 80 bytes

Output has a limit of 80 bytes, so if the payload is larger than 80 bytes, the transaction will be rejected.

  const tx: OpReturnMessage = {
    contract_creation: {
      contract_type: {
        moa: {
          divisibility: 18,
          live_time: encodeVarint(0),
          mint_mechanism: {
            free_mint: {
              amount_per_mint: encodeVaruint(1)
            }
          },
          commitment: {
            public_key: Array.from(creatorAccount.p2pkh().keypair.publicKey),
            args: {
              fixed_string: encodeBase26("LONGFIXEDSTRING"),
              string: "verylongstring"
            }
          }
        }
      }
    }
  };

  const builder = await txBuilder.compress(tx);

{
  builder: Buffer(94) [ 106, 6, 71, 76, 73, 84, 84, 82, 76, 84, 0, 11, 39, 128, 0, 1, 0, 0, 0, 18, 0, 0, 0, 1, 0, 1, 0, 1, 3, 43, 203, 217, 207, 189, 189, 158, 255, 43, 218, 153, 53, 246, 204, 42, 111, 160, 201, 8, 218, 58, 170, 80, 174, 216, 13, 104, 176, 175, 179, 69, 26, 1, 166, 205, 216, 182, 139, 181, 188, 188, 142, 88, 0, 14, 0, 0, 0, 118, 101, 114, 121, 108, 111, 110, 103, 115, 116, 114, 105, 110, 103, 0, 0, 3 ],
}

That example show that if the payload is larger than 80 bytes, the transaction will be rejected, the total transaction bytes is 94 bytes which exceeded the bitcoin output size, the solution is to reduce the value like use shorter args.string or args.fixed_string value.