# Z-Imburse Docs: ZImburseEscrow Contract Interactions
The following documentation describes actual interaction with the ZImburseEscrow.

## Contract Construction
The [`ZImburseEscrow` constructor](https://github.com/Mach-34/z-imburse/blob/main/contracts/z_imburse_escrow/src/main.nr#L77-L80) publicly initializes a new instance of the ZImburse contract. The constructor simply takes:
* an address for the `ZImburseRegistry` contract
* an address for the USDC payment `Token` contract
* a string title that describes what the escrow does

Additionally, the execution will retrieve the `context.msg_sender()` as the admin. [A SharedImmutable<EscrowDefinitoin>](https://github.com/Mach-34/z-imburse/blob/main/contracts/z_imburse_escrow/src/main.nr#L77-L80) will be created to allow constrained private access control by the admin, checks against DKIM key hashes in the registry, and initiation of token transfers for reimbursement.

:::info
We need to update this function to call the registry contract and not use `prove_contract_inclusion` in the registry.
:::

## Calling the Registry
We cannot have cyclic dependencies in Nargo.toml. Guveb `ZImburseRegistry` will call `ZImburseEscrow` contracts when checking the integrity of their implementation, we cannot simply import the registry contract and into the escrow and call using the derived API. Instead, we need to [manually construct the function call to check DKIM key hashes from the registry](https://github.com/Mach-34/z-imburse/blob/main/contracts/z_imburse_escrow/src/main.nr#L77-L80). This is an ugly pattern compared to the normal API for calling other contracts, but it unavoidably the only solution.

## Giving Entitlements
As mentioned in [`EntitlementNote` docs](https://hackmd.io/@IQZ-5dJ4QGGu4K6oX71X7w/HkYwMgAg1l), there is a single `EntitlementNote` struct type but two different manifestations: spot and recurring. Contracts on Aztec are actually collections of verifier keys, and there is no marginal cost on deployment based on the size of the contracts. Therefore, a minor optimization is made by segregating [ZImburseEscrow::give_spot_entitlement](https://github.com/Mach-34/z-imburse/blob/main/contracts/z_imburse_escrow/src/main.nr#L77-L80) and [ZImburseEscrow::give_recurring_entitlement](https://github.com/Mach-34/z-imburse/blob/main/contracts/z_imburse_escrow/src/main.nr#L77-L80).

Both functions generally perform the same logic:
1. Check there is no existing entitlement for the user (not safe, to be fixed)
2. Check that the `context.msg_sender()` is the escrow admin
3. Create the {recurring | spot} `EntitlementNote`
4. Add the `EntitlementNote` to the `EntitlementSet` for the recipient and also to self as a receipt

The admin always supplies three parameters:
- `recipient`: the address receiving the entitlement
- `max_amount`: the maximum amount the recipient can claim when proving a receipt email
- `verifier_id`: the ID of the verifier type that governs the verification logic assoicated with the entitlement

Additionally, if the admin is creating a spot entitlement, they supply:
- `date_start`: the unix timestamp (no milliseconds) at which receipts start being valid for the entitlement
- `date_end`: the unix timestamp at which receipts stop being valid for the entitlement
- `destination`: optionally used destination that receipts for travel expenses must match

These parameters define the constraints by which claimants can reimburse themselves.

:::info
There is nothing stopping an admin from creating unfunded obligations in a `ZImburseEscrow` contract. If we were only dealing with Spot (one-time use) entitlements, we could easily constrain a check to the balance of the Escrow contract before allowing the creation of new `EntitlementNotes`. However, we cannot predict and therefore constrain the full cost of a recurring entitlement. Even if we did use `EntitlementNote::date_start` and `EntitlementNote::date_end` to constrain access, we don't want to force inefficient capital allocation by requiring funds to be locked up far before they need to be used.

Our solution is that the admin and claimant have an existing social relationship, and the claimant should encourage the admin to provide liquidity if none is available. Advisory on this weak point would be interesting.
:::

## Claiming Entitlements
To claim an entitlement, users will run a [JS input generator](https://github.com/Mach-34/z-imburse/blob/main/src/email_inputs/linode.ts#L57-L109) that performs the standard [ZKEmail.nr generateEmailVerifierInputsFromDkimResult](https://github.com/zkemail/zkemail.nr/blob/main/js/src/index.ts#L113) parsing along with additional input generation for receipt-specific parsing.

Aztec Contracts are unable to parse some of the inputs like `BoundedVec` or `RSAPubkey` as function parameters, so a [messy serialization utility is employed](https://github.com/Mach-34/z-imburse/blob/main/circuits/zimburse_verifiers/src/linode/constants.nr#L43-L97) to flatten the structs into types that aztec.nr is comfortable parsing.

### Linode
Linode entitlements [mostly consist of common logic](https://github.com/Mach-34/z-imburse/blob/main/contracts/z_imburse_escrow/src/library_methods.nr#L10-L65) between spot and recurring entitlements:
1. Attempt to retrieve an `EntitlementNote` owned by the caller for the specific verifier type (linode)
2. Ensure the caller is the owner of the note (this may be redundant)
3. [perform zkemail verification of the email receipt](https://github.com/Mach-34/z-imburse/blob/main/circuits/zimburse_verifiers/src/linode/main.nr#L9-L56), extracting out the values like amount billed, a timestamp, and the dkim key hash
4. make a private call to the `ZImburseRegistry::check_dkim_hash_private` contract to check that the DKIM key that signed the email is a valid DKIM key for the verifier type (anchoring the email in a root of trust)
5. Determine the [amount to reimburse](https://github.com/Mach-34/z-imburse/blob/main/contracts/z_imburse_escrow/src/types/entitlement_note.nr#L251-L257) - the lesser of `EntitlementNote.max_amount` or `billed_amount` from the receipt
6. Emit an email nullifier to prevent the email from being reused by another user by hashing the dkim signature and emitting it as a nullifier
7. Call the `Token::shield` contract function to withdraw from the public balance of the escrow into a transparent note that the claimant can anonymously redeem

#### Spot

#### Recurring