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).

RouteUse
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/capabilitiesSupported optional endpoints.
GET /services/supportedAlgorithmsSupported algorithm names.
GET /services/statusService 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

watermarkReadtrue when the asset was examined for the watermark (byContent / byReference).
registrationFoundtrue when the watermark resolved to a registration on StarkNet.
registrations[].contentIdRegistration key on the BlockFact ContentRegistrationV2 contract.
registrations[].contractContract address; call get_content(contentId) to verify independently.
registrations[].txHashRegistration 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 byReference or send the first ~2 MB.
  • 415 — not a decodable image.