Bitcoin Faces Indexing #14
Description
After seeing a ton of new Bitcoin Faces on ord.io and the successful launch of bitcoinfaces.xyz this week, it's time to talk about indexing.
The goals here should be to identify:
- what constitutes a Bitcoin Face as part of this collection
- how to verify if a Bitcoin Face and given string match
- how to verify first is first for minted Bitcoin Faces
Here we go!
Table of Contents
- What is a Bitcoin Face?
- What are the layers?
- How a Bitcoin Face is created
- Parsing the SVG code
- Creating the Standard
What is a Bitcoin Face?
A Bitcoin Face is a deterministically generated SVG image based on an input string.
A Bitcoin Face consists of:
- an SVG file that contains references for each layer
- for each layer, an image tag with href set to
/content/{inscriptionId}
For example: Bitcoin Face for firstisfirst
<svg
id="bitcoin-face-for-firstisfirst"
width="100%"
height="100%"
viewBox="0 0 1025 1025"
xmlns="http://www.w3.org/2000/svg"
xmlns:xlink="http://www.w3.org/1999/xlink"
>
<image
id="background-1"
xlink:href="/content/6c6b83ccf5db73fd371f0dcaa62fb607c58dc86c99b068982f9c28e112328781i0"
x="0"
y="0"
width="100%"
height="100%"
></image>
<image
id="body-1"
xlink:href="/content/4891fc56d297684275f904cbd5747537d02f3c8fefe5731d3f2797cc28589b31i0"
x="0"
y="0"
width="100%"
height="100%"
></image>
<image
id="head-1"
xlink:href="/content/b88b81635faad19f654f28fd5502c4a5008a073cb24529568d7bc9e9f6584420i0"
x="0"
y="0"
width="100%"
height="100%"
></image>
<image
id="ears-1"
xlink:href="/content/49f8014d388de06928f604d2ac6eb7380d2fcfa441570ce96004e62da21945b5i0"
x="0"
y="0"
width="100%"
height="100%"
></image>
<image
id="mouth-1"
xlink:href="/content/f46333c7aae731f501743274b0b73f59c1863233a2948a4d42ca580b4a315600i0"
x="0"
y="0"
width="100%"
height="100%"
></image>
<image
id="nose-1"
xlink:href="/content/87191d4187f614618f37629169f5b552bdaa9a2aac4b226e693885023a181d7di0"
x="0"
y="0"
width="100%"
height="100%"
></image>
<image
id="eyes-1"
xlink:href="/content/4bd9a298dd80421f63753d25a3316753f9bd38a4a1eb57e2b1175ff20ea8ee93i0"
x="0"
y="0"
width="100%"
height="100%"
></image>
</svg>
What are the layers?
The layers are based on the attributes for each Bitcoin Face, which includes:
- 7 required layers
- 4 optional layers
- 3 eye types
export const REQUIRED_LAYERS = [
"background",
"body",
"head",
"ears",
"eyes",
"nose",
"mouth",
] as const;
export const OPTIONAL_LAYERS = ["chain", "earring", "glasses", "hat"] as const;
export const EYE_TYPES = ["normal", "laser", "starburst"] as const;
The layers are defined in this constant on GitHub:
Lines 51 to 175 in d193c36
Inscriptions
The layers are inscribed at the address below:
bc1pr7znvmc9drttp5d2hwuexxaggm9tk594nq8gptqltvfqendzfh4sthsml4
Layer Order
Layer order is defined in the layer creation process:
const order: Layers[] = [
"background",
"body",
"head",
"ears",
"chain",
"mouth",
"nose",
"hat",
"eyes",
];
How a Bitcoin Face is created
The generator for Bitcoin Faces currently takes the input string and goes through the following steps:
Normalization
Transforms the input string into a standardized format by decoding URI components, converting to lowercase, and removing leading/trailing whitespaces. This ensures consistency before hashing.
const normalizedName = decodeURIComponent(name).toLowerCase().trim();
Hashing
Converts the normalized string into a hash array using SHA-256. The string is converted to a Uint8Array which is provided to SHA-256 to produce a hash, and the result is returned as a new Uint8Array.
const encoder = new TextEncoder();
const data = encoder.encode(input);
const hashBuffer = await crypto.subtle.digest("SHA-256", data);
const hashArray = Array.from(new Uint8Array(hashBuffer));
Layer Selection
Selects face layers from a list of all possible combinatinos, based on hash array, by iterating over attributes using hash values.
// calculates layer index
function calculateLayerIndex(
hashArray: number[],
hashIndex: number,
length: number
): number {
return hashArray[hashIndex % hashArray.length] % length;
}
Create Layers
Iterates over selected layers to create <image /> tags with links to /content/inscriptionId.
return order
.map((key: Layers) => {
const value = layers[key];
if (value === undefined) return "";
if (onchain) {
return `<image id="${key}-1" xlink:href="${host}/${value}" x="0" y="0" width="100%" height="100%"></image>`;
}
return value;
})
.filter((str) => str !== "")
.join("\n");
Create SVG
Wraps <image /> tags in final SVG format.
return `<svg id="bitcoin-face-for-${name}" width="${width}" height="${height}" viewBox="0 0 1025 1025" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">\n${svgLayers}\n</svg>`;
Parsing the SVG code
Identifying as part of the collection
SVG attribute tags do not have a defined order, and therefore some parsing is required in order to consistently identify if a Bitcoin Face SVG file is part of the collection.
For example, the API uses a local version of the SVG files to serve quick responses, and there is a test that makes sure it matches what's on-chain bytaking the inscription ID, pulling the SVG from an API, then comparing the local SVG content to it.
In order to do this, the SVG image code must be normalized and returned as a string, which is done by this function:
const cleanedSVG = data
.replace(/>\s+/g, ">")
.replace(/\s+</g, "<")
.replace(/\s+/g, " ")
.trim();
If we take that a step further, we could strip down one of these SVGs to a list of it's layer hashes, e.g. for firstisfirst:
const firstisfirstContentHashes = [
"6c6b83ccf5db73fd371f0dcaa62fb607c58dc86c99b068982f9c28e112328781", // "background-9"
"4891fc56d297684275f904cbd5747537d02f3c8fefe5731d3f2797cc28589b31", // "body-6"
"b88b81635faad19f654f28fd5502c4a5008a073cb24529568d7bc9e9f6584420", // "head-1"
"49f8014d388de06928f604d2ac6eb7380d2fcfa441570ce96004e62da21945b5", // "ears-1"
"f46333c7aae731f501743274b0b73f59c1863233a2948a4d42ca580b4a315600", // "nose-3"
"87191d4187f614618f37629169f5b552bdaa9a2aac4b226e693885023a181d7d", // "mouth-3"
"4bd9a298dd80421f63753d25a3316753f9bd38a4a1eb57e2b1175ff20ea8ee93", // "eyes-starburst-9"
];
As long as the array of hashes (or "recursive content") matches the available hashes in the collection, then we know it's a valid Bitcoin Faces SVG.
If we hash the content hashes, we have a single string that we can verify a Bitcoin Face against and use as it's identity.
Identifying first is first
Considering the approach above for identifying a Bitcoin Face from the collection, determining first is first would require:
- Detecting Bitcoin Face SVGs from inscription content
- Recording the order of Bitcoin Face SVG inscriptions
This approach is favorable to just a hash of the content, considering a valid (but minimal) version of the SVG could be:
<svg>
<image
id="background-1"
xlink:href="/content/6c6b83ccf5db73fd371f0dcaa62fb607c58dc86c99b068982f9c28e112328781i0"
></image>
<image
id="body-1"
xlink:href="/content/4891fc56d297684275f904cbd5747537d02f3c8fefe5731d3f2797cc28589b31i0"
></image>
<image
id="head-1"
xlink:href="/content/b88b81635faad19f654f28fd5502c4a5008a073cb24529568d7bc9e9f6584420i0"
></image>
<image
id="ears-1"
xlink:href="/content/49f8014d388de06928f604d2ac6eb7380d2fcfa441570ce96004e62da21945b5i0"
></image>
<image
id="mouth-1"
xlink:href="/content/f46333c7aae731f501743274b0b73f59c1863233a2948a4d42ca580b4a315600i0"
></image>
<image
xlink:href="/content/87191d4187f614618f37629169f5b552bdaa9a2aac4b226e693885023a181d7di0"
></image>
<image
xlink:href="/content/4bd9a298dd80421f63753d25a3316753f9bd38a4a1eb57e2b1175ff20ea8ee93i0"
></image>
</svg>
There can also be discrepencies between the tag attribute order, depending on image compression/optimization software commonly used by inscription services. An SVG <use> tag could be implemented instead of <image>.
Creating the Standard
The outline above would allow us to be as inclusive as possible while still supporting anything people want to create with the layers already inscribed.
Would really love to hear from @bruffstar @jnapp18 or anyone else closer to indexing/verification/minting.
Note
We welcome input from anyone who wants to get involved! We want to identify standards that will apply to marketplaces, service providers, and any other potential integrations for Bitcoin Faces.