Proof Request with Requested Predicates

In ACA-Py, requested predicates are conditions used in proof requests to ensure that certain attributes meet specific criteria without revealing the actual attribute values.

Predicates enable verifiers to request proofs that certain numeric attributes (like age, income, or date) satisfy conditions such as greater than (>), less than (<), greater than or equal to (>=), or less than or equal to (<=) a specified value.

This allows for selective disclosure, enhancing privacy by only proving the required attribute conditions without disclosing the exact values.

The Credential

In order to make a proof request with requested predicates, the credential will need to have an attribute with a value that is an integer. However, if a credential is issued as a string of integers, ACA-Py can convert that to an integer to perform the predicate check.

Furthermore, it is important for the verifier to understand how a credential attribute was set by an issuer to accurately incorporate a predicate in the proof request.

The Proof Request

Let's take a look at the requested_predicates object in the indy_proof_request object.

    "requested_predicates":{
        "name": string,
        "p_type": string,
        "p_value": int,
        "restrictions": <restrictions>,
        "non_revoked": <non_revoc_interval>,
    }

The name field is the same as in the requested_attributes; it refers to the attribute of the credential that is being checked.
The p_type can be one of the following strings:
- >= greater or equal
- <= less or equal
- > greater as
- < less than
The p_value is the integer that the credential value is being checked against.
The restrictions field is used to put restrictions on the credential attribute the prover can respond with. Please take a look at this for more information on restrictions.
non-revoked: See the revocation section of the documentation for information on how to check if a credential is revoked.

Example Proof Flow

Below is an example of a proof request with a requested_predicates on the attribute dob (date of birth). The goal of the predicate is to determine if the holder is over the age of 18, without sharing the holder's date of birth.

It has been noted that the verifier needs to understand how a credential attribute has been set to accurately incorporate a predicate. Let's take a look at the credential that has been used here:

{
  "attrs": {
    "dob": "19900101",
    "surname": "Demo",
    "name": "Alice"
  },
  "cred_def_id": "JQKddffbKAw46ERuwLK5cF:3:CL:16:Demo_cred_def",
  "cred_rev_id": "1",
  "referent": "484f7946-b897-4767-914f-9a9357d4c2db",
  "rev_reg_id": "JQKddffbKAw46ERuwLK5cF:4:JQKddffbKAw46ERuwLK5cF:3:CL:16:Demo_cred_def:CL_ACCUM:5c7eb3ed-fbf3-4bf0-a711-ecd8a9365236",
  "schema_id": "4dcSmgArjVgpnfjiy6yNAo:2:Demo_schema:0.1.0"
}

We can see that the dob has the format yyyymmdd, so the verifier can check if a holder's birth date is before the date required to be 18 years old. So the verifier needs to check that: {holder's_dob} <= {date_18_years_ago}.

Issue proof request

 POST v1/verifier/send-request

with body:

{
  "comment": "Demo",
  "trace": true,
  "type": "indy",
  "indy_proof_request": {
    "requested_attributes": {},
    "requested_predicates": {
      "age_over_18": {
        "name": "dob",
        "p_type": "<=",
        "p_value": 20060530,
        "restrictions": [
          {
            "cred_def_id": "JQKddffbKAw46ERuwLK5cF:3:CL:16:Demo_cred_def"
          }
        ]
      }
    }
  },
  "save_exchange_record": true,
  "connection_id": "b993c5db-71bc-4733-a0d9-a72b106ce435"
}

Note the restriction on the cred_def_id above. This ensures the credential comes from a specific issuer and credential definition where we know how the dob has been set.

The holder checks if they have a credential that can satisfy the proof request

GET v1/verifier/proofs/v2-8797794c-cbc0-46be-9a63-2e5d1dc06f6c/credentials

Response:

[
  {
    "cred_info": {
      "attrs": {
        "dob": "19900101",
        "surname": "Demo",
        "name": "Alice"
      },
      "cred_def_id": "JQKddffbKAw46ERuwLK5cF:3:CL:16:Demo_cred_def",
      "cred_rev_id": "1",
      "referent": "484f7946-b897-4767-914f-9a9357d4c2db",
      "rev_reg_id": "JQKddffbKAw46ERuwLK5cF:4:JQKddffbKAw46ERuwLK5cF:3:CL:16:Demo_cred_def:CL_ACCUM:5c7eb3ed-fbf3-4bf0-a711-ecd8a9365236",
      "schema_id": "4dcSmgArjVgpnfjiy6yNAo:2:Demo_schema:0.1.0"
    },
    "interval": null,
    "presentation_referents": ["age_over_18"]
  }
]

The response above shows that the credential returned can be used to respond to the requested predicate age_over_18.

The holder accepts the proof request

POST v1/verifier/accept-request

with body:

{
  "proof_id": "v2-8797794c-cbc0-46be-9a63-2e5d1dc06f6c",
  "type": "indy",
  "indy_presentation_spec": {
    "requested_attributes": {},
    "requested_predicates": {
      "age_over_18": {
        "cred_id": "484f7946-b897-4767-914f-9a9357d4c2db"
      }
    },
    "self_attested_attributes": {}
  },
  "save_exchange_record": true
}

The verifier's proof records

The verifier's webhook events will update on the topic proofs:

{
  "wallet_id": "c32d6406-c200-4b5f-a126-c301ef112477",
  "topic": "proofs",
  "origin": "tenant faber",
  "group_id": "GroupA",
  "payload": {
    "connection_id": "b993c5db-71bc-4733-a0d9-a72b106ce435",
    "created_at": "2025-01-30T09:24:07.325448Z",
    "error_msg": null,
    "parent_thread_id": null,
    "presentation": null,
    "presentation_request": null,
    "proof_id": "v2-284e8535-fa1a-4aac-8121-d192747030a0",
    "role": "verifier",
    "state": "done",
    "thread_id": "17e82614-1304-4c1c-8778-fc81ba18ee4c",
    "updated_at": "2025-01-30T09:29:37.117900Z",
    "verified": true
  }
}

We can see above that the proof request is complete (state: done) and the predicate is satisfied (verified: true).

Let's take a look at the verifier's proof record of the above exchange. Take note of the fact that the revealed_attrs field is empty and the dob attribute has not been revealed.

Note that some large payloads are obfuscated in the following response for readability.


  {
    "connection_id": "b993c5db-71bc-4733-a0d9-a72b106ce435",
    "created_at": "2025-01-30T09:24:07.325448Z",
    "error_msg": null,
    "parent_thread_id": "17e82614-1304-4c1c-8778-fc81ba18ee4c",
    "presentation": {
      "identifiers": [
        {
          "cred_def_id": "JQKddffbKAw46ERuwLK5cF:3:CL:16:Demo_cred_def",
          "rev_reg_id": "JQKddffbKAw46ERuwLK5cF:4:JQKddffbKAw46ERuwLK5cF:3:CL:16:Demo_cred_def:CL_ACCUM:5c7eb3ed-fbf3-4bf0-a711-ecd8a9365236",
          "schema_id": "4dcSmgArjVgpnfjiy6yNAo:2:Demo_schema:0.1.0",
          "timestamp": null
        }
      ],
      "proof": {
        "aggregated_proof": {
          "c_hash": "68083911735211467518460000736130275255547049313413354347790350217175401850873",
          "c_list": [
            [...],
            [...],
            [...],
            [...],
            [...],
            [...]
          ]
        },
        "proofs": [
          {
            "non_revoc_proof": null,
            "primary_proof": {
              "eq_proof": {
                "a_prime": ...,
                "e": "119387358330875008402881076664442056750743658498957523102535902524764053894914591462886392266566631581734329790860931884982192173917395976",
                "m": {
                  "name": "7206276404206857526783008541561244555270605578873171016811937079648008986898196821392261775064255800859371904017451184715729911369974354710297447142369137945850835288326799057347",
                  "dob": "7368174653071291467509243264983933988639387392718531361951217165284981758551875371467982169180823227163338243768448614046815815061385189049986863952228267732988077455166323300407",
                  "surname": "9277859084159715510916067354455243694867960264025518355252696241577763324112627218858326603964984582107518819046740146145718105070048856832278651029469711744592187338261777919850",
                  "master_secret": "15045190061493745649555708650672366392238186118529591984135989041588891839998311612694530842691834680254513558290039881402761553159200315443609127293501475087910035652196924119659"
                },
                "m2": ...,
                "revealed_attrs": {},
                "v": ...
              },
              "ge_proofs": [
                {
                  "alpha": ...,
                  "mj": ...,
                  "predicate": {
                    "attr_name": "dob",
                    "p_type": "LE",
                    "value": 20060530
                  },
                  "r": {...},
                  "t": {...},
                  "u": {...}
                }
              ]
            }
          }
        ]
      },
      "requested_proof": {
        "predicates": {
          "age_over_18": {
            "sub_proof_index": 0
          }
        },
        "revealed_attr_groups": null,
        "revealed_attrs": {},
        "self_attested_attrs": {},
        "unrevealed_attrs": {}
      }
    },
    "presentation_request": {
      "name": "Proof",
      "non_revoked": null,
      "nonce": "824421356049834403305010",
      "requested_attributes": {},
      "requested_predicates": {
        "age_over_18": {
          "name": "dob",
          "non_revoked": null,
          "p_type": "<=",
          "p_value": 20060530,
          "restrictions": [
            {
              "cred_def_id": "JQKddffbKAw46ERuwLK5cF:3:CL:16:Demo_cred_def"
            }
          ]
        }
      },
      "version": "1.0"
    },
    "proof_id": "v2-284e8535-fa1a-4aac-8121-d192747030a0",
    "role": "verifier",
    "state": "done",
    "thread_id": "17e82614-1304-4c1c-8778-fc81ba18ee4c",
    "updated_at": "2025-01-30T09:29:37.117900Z",
    "verified": true
  }

Hooray! 🥳🎉 Well done, you now know how to send and respond to a predicate proof.

acapy-cloud