Z-Imburse Docs: EntitlementSet

# Z-Imburse Docs: EntitlementSet ## EntitlementSet [EntitlementSet](https://github.com/Mach-34/z-imburse/blob/main/contracts/z_imburse_escrow/src/types/entitlement_set.nr) is a wrapper around `Map<PrivateSet<EntitlementNote>>` with abstractions. :::info To prevent collisions in TXE where all accounts can see eachother's notes, we map the "scope" (address of user we want to act as) to the private set. This introduces additional constraints and complexity that may not be necessary, but we could not find an API to prevent this bevaior from occuring in multi-tenant PXE's (essentially just the TXE) ::: ### Unconstrained [`EntitlementSet::view_entitlements`](https://github.com/Mach-34/z-imburse/blob/main/contracts/z_imburse_escrow/src/types/entitlement_set.nr#L48) can be used to view entitlements (including entitlement "receipts", the entitlement note duplicate sent to an admin) in the unconstrained context for clients. It simply provides the options to set parameters to match for `EntitlementNote.recipient`, `EntitlementNote.verifier_id`, and `EntitlementNote.spot`. A [maximum of 10 notes](https://github.com/AztecProtocol/aztec-packages/blob/a00acd4ac88f34d7d176710a1e8158f69ccc1717/noir-projects/aztec-nr/aztec/src/note/constants.nr#L5) can be returned from a single call, so there is an additional `offset` parameter that can be used to paginate responses. If 10 notes are returned in the current call, it will return a true value indicating there are more notes to get (prompting client to continue retrieving notes). When (amount of notes in the PXE) % 10 == 0, this value will unavoidably return true, prompting the extra retrieval of an empty page of notes. ### Private Context #### Getting Matching Entitlements There are cases where admins or recipients want to either retrieve an entitlement or deny the existence of an entitlement. This can be done with [`EntitlementSet::get_matching_entitlement`](https://github.com/Mach-34/z-imburse/blob/main/contracts/z_imburse_escrow/src/types/entitlement_set.nr#L101C12-L130). This function is similar to `EntitlementSet::view_notes`, except the arguments are not optional - the exact match for recipient, verifier_id, and spot must be found. This is mainly used by participants who want to claim a reimbursement. :::info While the PXE cannot provide a non-existent note and pass the kernel checks, it can refuse to provide an existing note. It is possible that abuse of this mechanic as an admin could deny access to a recurring entitlement that a recipient has without actually nullifying it in the current circuit (i.e. they can retrieve the EntitlementNote from `view_entitlements`, but claiming a recurring entitlement only returns one of the entitlements). This of course can be resolved by the participant manually removing the note from their PXE, but a future version would simply be robust and handle multiple entitlements of the same type to exist for one user gracefully. ::: #### Adding New Entitlements Entitlements can be added to storage with [`EntitlementSet::add_entitlement_with_receipt`](https://github.com/Mach-34/z-imburse/blob/main/contracts/z_imburse_escrow/src/types/entitlement_note.nr#L139-L153). As mentioned in the ["Entitlement Nullification"](https://hackmd.io/@IQZ-5dJ4QGGu4K6oX71X7w/HkYwMgAg1l#Entitlement-Nullification) section, when an admin gives a participant an entitlement, they will also duplicate the note and store it for themselves so that they can see the obligations of the escrow as well as nullify entitlements if they so choose. #### Nullifying Entitlements When an admin revokes an entitlement or a participant consumes a spot entitlement, they can "pop" the note from the set to return it into the circuit and also destroy it in storage using [`EntitlementSet::nullify_entitlement`](https://github.com/Mach-34/z-imburse/blob/main/contracts/z_imburse_escrow/src/types/entitlement_note.nr#L155-L191). The logic is essentially `EntitlementSet::get_matching_entitlement` except: 1. It destroys the note it returns 2. It will fail if it does not find a note, and therefore the return is not optional