Soft Binding: BlockFact Image Watermark
C2PA soft binding algorithm io.blockfact.image.watermark.32 and the BlockFact Soft Binding Resolution API
Algorithm
When the BlockFact app captures a photo, it computes a Poseidon hash over the capture data and registers it on StarkNet together with a zero-knowledge proof. The same hash is embedded into the image as an invisible, fragile spatial-domain watermark (least-significant-bit embedding in the pixel data). The watermarked image is stored losslessly (PNG), on its own or inside a .facti container.
If the image's metadata is later stripped — including its embedded C2PA manifest — the hash can still be read from the pixels and used to find the original registration.
- Type: watermark
- Decoded media types: image
- Payload: the capture's Poseidon registration hash (up to 254 bits)
- Soft binding value (32-bit): the first 32 bits of the embedded payload, base64-encoded (4 bytes). Used with
/matches/byBinding. - Robustness: survives lossless copies (for example a PNG whose metadata was removed). Lossy re-encoding (JPEG), resizing, cropping or rotation removes the mark.
- Extraction: server-side, via the Resolution API below.
How resolution works
BlockFact anchors provenance on StarkNet instead of storing C2PA manifests on a server — images and their manifests never leave the user's device. The resolver therefore answers with the on-chain registration the watermark points to, which any client can verify on StarkNet independently. Because the C2PA query result can only carry manifest identifiers, the registration is returned in a blockfact member of the result and matchesis empty.
Resolution API
Base URL: https://api.blockfact.io/api/soft-binding/v1 — implements the C2PA Soft Binding Resolution API (2.4).
| Route | Use |
|---|---|
| POST /matches/byContent?alg=… | Upload a PNG or .facti. The first ~2 MB of a PNG is enough. |
| POST /matches/byReference?alg=… | Large files: the service downloads the first 2 MB from an HTTPS URL. |
| GET /matches/byBinding?alg=…&value=… | Look up the 32-bit value (base64). |
| GET /services/capabilities | Supported optional endpoints. |
| GET /services/supportedAlgorithms | Supported algorithm names. |
| GET /services/status | Service status. |
The service also accepts the legacy name io.blockfact.audio.watermark.32 (soft binding list entry #45), which identifies the same image watermark. Storing manifests or bindings is not offered.
Example
curl -X POST -H "Content-Type: image/png" --data-binary @photo.png \
"https://api.blockfact.io/api/soft-binding/v1/matches/byContent?alg=io.blockfact.image.watermark.32"{
"matches": [],
"blockfact": {
"watermarkRead": true,
"registrationFound": true,
"registrations": [{
"contentId": "0x743e…442",
"registeredAt": "2026-08-15T03:44:06Z",
"network": "starknet-mainnet",
"contract": "0x028d…d344",
"txHash": "0x3738…f41",
"explorer": "https://voyager.online/tx/0x3738…f41"
}],
"note": "Watermark resolved to an on-chain BlockFact registration (StarkNet, ZK-verified). …"
}
}Result fields
| watermarkRead | true when the asset was examined for the watermark (byContent / byReference). |
| registrationFound | true when the watermark resolved to a registration on StarkNet. |
| registrations[].contentId | Registration key on the BlockFact ContentRegistrationV2 contract. |
| registrations[].contract | Contract address; call get_content(contentId) to verify independently. |
| registrations[].txHash | Registration transaction, when indexed. |
Status codes
- 200 — the query ran; see
blockfact.registrationFound. - 400 — missing or unsupported
alg, or a malformed value or URL. - 403 — store routes (manifests, bindings) are not offered.
- 413 — upload too large; use
byReferenceor send the first ~2 MB. - 415 — not a decodable image.