The basics of managing KERI identifiers using the KLI:

• Keystore Creation: A keystore, essential for managing identifiers, is created using kli init, requiring a name, passcode, and salt
• Identifier Inception: New identifiers (AIDs) are created within a named keystore using kli incept, which also starts their Key Event Log (KEL)
• Key Event Log (KEL): The KEL tracks an AID's history with fields like version (v), event type (t), identifier prefix (i), signing threshold (kt), and keys (k)
• Displaying identifiers:kli status displays an AID information and the KEL
• Listing Identifiers: The kli list command displays all identifiers managed within a specific keystore

Key rotation is essential for security hygiene, cryptographic agility, and enabling recovery or delegation. KERI uses a "pre-rotation" strategy where the commitment (digest) for the next set of keys is included in the current key establishment event (`icp` or `rot`). This secures the rotation process even if the currently active key is compromised.

• The two-step cooperative process of delegated inception.
• Performing delegated key rotation.
• Examining the Key Event Logs (KELs) of both the delegator and the delegate to understand how the delegation is anchored and verified.
## Introduction to Delegated AIDs In KERI, delegation is a powerful mechanism that allows one AID (the delegator) to authorize another AID (the delegate) to perform certain actions such as signing. This is achieved through a cooperative cryptographic process where both parties participate in establishing the relationship. The primary purpose of delegation in KERI is to allow **scaling of signing authority** by setting up **delegation hierarchies**. The delegation process is as follows: #### Delegation Process Diagram  #### Process Steps The process steps illustrated in the Delegation Process Diagram above are: 1. Create the Delegator AID. You did this earlier in the training. 2. Create the Proxy AID. 3. Create the Delegate AID and specify the Proxy AID as the communication proxy using the `--proxy` flag to `kli incept`. This process waits for completion until the Delegator AID approves the delegation. It can time out and would need to be restarted. 4. The Proxy AID signs the delegation request from the Delegate AID. 5. The Proxy AID sends the delegation request to the Delegator AID. 6. The Delegator AID receives the signed delegation request, along with the Proxy AID's KEL, verifies the signature on the delegation request, and then chooses to approve or deny the delegation. - In the case of an approval the Delegator AID creates an anchor (seal) and adds that anchor to it's KEL using an interaction event which signifies the Delegator's approval of the delegation. The delegator then sends its KEL containing this anchor, and witness receipts for the interaction event, to the Delegate. 7. The Delegate AID completes delegation by receiving from the Delegator AID a current copy of the delegator's KEL which now includes the anchoring delegation approval seal from the delegator combined with any witness receipts for the delegator's interaction event including this seal. #### Result of Delegation Once the delegation process shown above is complete you will end up with a simple delegation chain that looks like the following ```mermaid graph BT %% Define event nodes DELEGATOR["Delegator 🔑"] DELEGATE["Delegate 🔑"] %% Define backward chaining DELEGATE -- delegated from --> DELEGATOR %% UML appearance classDef eventBox fill:#f5f5f5,stroke:#000,stroke-width:1px,rx:5px,ry:5px,font-size:14px; class DELEGATOR,DELEGATE, eventBox; ``` #### Aspects of KERI Delegation The strong cryptographic binding between delegator and delegate allow the delegator to fractionalize, or split up, their signing authority into multiple smaller units that allow for the straightforward scaling of signing authority. Placing an object called an "anchor" in the delegator's key event log is used to signify delegation approval. This delegation anchor is also known as a "seal." Major aspects of KERI delegation include: - Cooperative Establishment: The creation (inception) and subsequent management (e.g., rotation) of a delegated AID requires coordinated, cooperative actions from both the delegate (initiating the request) and the delegator (confirming and anchoring the event). - Cryptographic Binding: The delegated AID's prefix is a self-addressing identifier (SAID) derived from its own delegated inception event. This inception event, in turn, includes the delegator's AID, creating a strong cryptographic link between the delegator and the delegate. - Anchoring: The delegator anchors the delegation to it's KEL by including a "delegated event seal" in one of its own key events. This seal contains the delegate's AID, the sequence number of the delegated event, and a digest of that delegated event. - An anchor of this form is used for both delegated inception when an identifier is set up and also for delegated rotations when keys of the delegate are changed. The delegator must approve of a delegated rotation in order for a delegated identifier to rotate keys. The anchor in the KEL of the delegator functions as that approval. - Delegated Authority: The delegator typically retains ultimate establishment control authority, while the delegate might be authorized for specific non-establishment events such as signing (interaction events) or further, limited delegations. - Hierarchical Structures: Delegation can be applied recursively, enabling the creation of complex hierarchical key management structures. #### Hierarchical Delegation Diagram  This notebook will walk through the KLI commands to perform delegated inception and delegated rotation, illustrating how these concepts are put into practice. ## Initial Setup ### Step 1: Create Keystores and Delegator AID First, we'll set up the necessary keystores and a primary AID for the delegator. We will also initialize a keystore for the delegate. For brevity and simplicity in this notebook, passcodes for keystores are omitted using the `--nopasscode` flag. In a production deployment you would generally want to use the `--passcode ` argument to secure a keystore. The `keystore_init_config.json` file is used to pre-configure the keystores with witness information. ```python # Imports and Utility functions from scripts.utils import exec, exec_bg, clear_keri from scripts.utils import pr_continue, pr_title, pr_message clear_keri() pr_title("Initializing keystores") # Delegate Keystore delegate_keystore="delegate_keystore" delegate_salt= exec("kli salt") !kli init --name {delegate_keystore} \ --nopasscode \ --salt {delegate_salt} \ --config-dir ./config \ --config-file keystore_init_config.json # Delegator Keystore delegator_keystore="delegator_keystore" delegator_salt=exec("kli salt") !kli init --name {delegator_keystore} \ --nopasscode \ --salt {delegator_salt} \ --config-dir ./config \ --config-file keystore_init_config.json pr_title("Incepting delegator AID") # Delegator AID delegator_alias = "delegator_alias" !kli incept --name {delegator_keystore} \ --alias {delegator_alias} \ --icount 1 \ --isith 1 \ --ncount 1 \ --nsith 1 \ --wits BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha \ --wits BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM \ --wits BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX \ --toad 2 \ --transferable pr_title("Generating OOBIs") # OOBI Exchange # Delegator generates an OOBI for its AID delegator_oobi = exec(f"kli oobi generate --name {delegator_keystore} --alias {delegator_alias} --role witness") print("Delegator OOBI: " + delegator_oobi) pr_title("Resolving OOBIs") # Delegate's keystore resolves the Delegator's OOBI !kli oobi resolve --name {delegate_keystore} \ --oobi-alias {delegator_alias} \ --oobi {delegator_oobi} pr_continue() ``` Proceeding with deletion of '/usr/local/var/keri/' without confirmation. ✅ Successfully removed: /usr/local/var/keri/ Initializing keystores KERI Keystore created at: /usr/local/var/keri/ks/delegate_keystore KERI Database created at: /usr/local/var/keri/db/delegate_keystore KERI Credential Store created at: /usr/local/var/keri/reg/delegate_keystore Loading 3 OOBIs... http://witness-demo:5642/oobi/BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha/controller?name=Wan&tag=witness succeeded http://witness-demo:5643/oobi/BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM/controller?name=Wes&tag=witness succeeded http://witness-demo:5644/oobi/BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX/controller?name=Wil&tag=witness succeeded KERI Keystore created at: /usr/local/var/keri/ks/delegator_keystore KERI Database created at: /usr/local/var/keri/db/delegator_keystore KERI Credential Store created at: /usr/local/var/keri/reg/delegator_keystore Loading 3 OOBIs... http://witness-demo:5642/oobi/BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha/controller?name=Wan&tag=witness succeeded http://witness-demo:5643/oobi/BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM/controller?name=Wes&tag=witness succeeded http://witness-demo:5644/oobi/BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX/controller?name=Wil&tag=witness succeeded Incepting delegator AID Waiting for witness receipts... Prefix EHDW4TgdyYTkUwxtZlIt03poPBA4Ouk5w4LJ6MTJJRLB Public key 1: DG7EhH42hjxj77O-InfYucbj7AacdEbZKnMw2qhKrarD Generating OOBIs Delegator OOBI: http://witness-demo:5642/oobi/EHDW4TgdyYTkUwxtZlIt03poPBA4Ouk5w4LJ6MTJJRLB/witness Resolving OOBIs http://witness-demo:5642/oobi/EHDW4TgdyYTkUwxtZlIt03poPBA4Ouk5w4LJ6MTJJRLB/witness resolved You can continue ✅ ## Creating Delegated Identifiers Delegation is a multi-step process involving both the entity wishing to become a delegate and the entity granting the delegation (the delegator). The above delegation process diagram is repeated for convenience.  ### Step 2: Delegate Incepts Proxy The delegate needs an AID that can initiate the delegation request. This "proxy" AID is a regular AID within the delegate's keystore. It will be used to facilitate communication between the in-process delegate and the delegator until the delegator confirms the delegation and the process is complete. ```python # Delegate proxy pr_title("Incepting delegate proxy AID") # This AID is in the delegate's keystore and is used to initiate the delegation request. delegate_proxy_alias = "delegate_proxy_alias" !kli incept --name delegate_keystore \ --alias delegate_proxy_alias \ --icount 1 \ --isith 1 \ --ncount 1 \ --nsith 1 \ --wits BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha \ --wits BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM \ --wits BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX \ --toad 2 \ --transferable pr_continue() ``` Incepting delegate proxy AID Waiting for witness receipts... Prefix ECIiDbnDdnPSDqCY4eewKF_6-ZcizO9fkIX6AMYmnr5z Public key 1: DM864_xepY76KkPFfrOASZcGZ4kywBsiteRn2Gm55X8w You can continue ✅ ### Steps 3, 4, and 5: Delegate requests delegated AID Inception, Proxy signs and forwards request During the setup process the delegate uses a proxy AID to send a signed delegation request to the delegator. #### A Proxy is Required for Secure Communications The use of the proxy as shown in steps 3-5 below is necessary because the delegated identifier is not fully set up and thus cannot be used to sign anything until the delegator approves the delegation. This means the delegate cannot sign its own delegation request. So, to request the inception of a new, delegated AID a separate non-delegated AID is used as a one-time, temporary communication proxy. This proxy signs the delegation request so that it can be verifiable by the delegator.  #### kli incept for the delegate When using `kli incept` during delegation the following arguments are needed: - `--name` and `--alias`: Define the keystore and the alias for the new delegated AID being created. - `--delpre`: Specifies the prefix of the AID that will be delegating authority. - `--proxy`: Specifies the alias of the AID within the `delegate_keystore` that is making the request and will serve as the communication proxy between the delegator and the delegate (`delegate_alias`). The `kli incept --delpre` command will initiate the process and then wait for the delegator to confirm. We run this in the background (`exec_bg`) because it will pause. ```python pr_title("Incepting delegated AID") delegator_pre = exec(f"kli aid --name {delegator_keystore} --alias {delegator_alias}") pr_message("Delegator prefix: " + delegator_pre) delegate_alias = "delegate_alias" # Incept delegate. Note --delpre and --proxy parameters # The command runs in the background since it waits for the delegator's confirmation # exec_bg (execute in background) does that. Output is sent to a log file. # This pattern of exec_bg is repeated throughout the notebook command = f""" kli incept --name {delegate_keystore} \ --alias {delegate_alias} \ --icount 1 \ --isith 1 \ --ncount 1 \ --nsith 1 \ --wits BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha \ --toad 1 \ --transferable \ --delpre {delegator_pre} \ --proxy {delegate_proxy_alias} > ./logs/delegate_incept.log """ exec_bg(command) pr_continue() ``` Incepting delegated AID Delegator prefix: EHDW4TgdyYTkUwxtZlIt03poPBA4Ouk5w4LJ6MTJJRLB Command kli incept --name delegate_keystore --alias delegate_alias --icount 1 --isith 1 --ncount 1 --nsith 1 --wits BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha --toad 1 --transferable --delpre EHDW4TgdyYTkUwxtZlIt03poPBA4Ouk5w4LJ6MTJJRLB --proxy delegate_proxy_alias > ./logs/delegate_incept.log started with PID: 914 You can continue ✅ ### Step 6: Delegator confirms delegation The delegator now needs to confirm the delegation request. The `kli delegate confirm` command checks for pending delegation requests for the specified delegator AID and, if `--auto` is used, automatically approves them. This action creates an interaction event in the delegator's KEL that anchors the delegate's inception event as a "seal" which functions as a proof of delegation approval. ```python # Delegator confirmation pr_title("Confirming delegation") command = f""" kli delegate confirm --name {delegator_keystore} \ --alias {delegator_alias} \ --interact \ --auto """ output = exec(command, True) pr_message(output) pr_continue() ``` Confirming delegation ['Delegagtor Prefix EHDW4TgdyYTkUwxtZlIt03poPBA4Ouk5w4LJ6MTJJRLB', 'Delegate EESIOsSAKBrCvozIIAKcj87hQvntj_wcWiTHuu7AZPI7 inception Anchored at Seq. No. 1', 'Delegate EESIOsSAKBrCvozIIAKcj87hQvntj_wcWiTHuu7AZPI7 inception event committed.'] You can continue ✅ Now, let's examine the status of the newly created delegated AID. ```python pr_title(f"Delegated AID status") !kli status --name delegate_keystore --alias delegate_alias --verbose ``` Delegated AID status Alias: delegate_alias Identifier: EESIOsSAKBrCvozIIAKcj87hQvntj_wcWiTHuu7AZPI7 Seq No: 0 Delegated Identifier Delegator: EHDW4TgdyYTkUwxtZlIt03poPBA4Ouk5w4LJ6MTJJRLB ✔ Anchored Witnesses: Count: 1 Receipts: 1 Threshold: 1 Public Keys: 1. DB5PKs2yTLWkgoaboz2rR0g_im9FBkQF2g8VWcjt6oUP Witnesses: 1. BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha { "v": "KERI10JSON00018d_", "t": "dip", "d": "EESIOsSAKBrCvozIIAKcj87hQvntj_wcWiTHuu7AZPI7", "i": "EESIOsSAKBrCvozIIAKcj87hQvntj_wcWiTHuu7AZPI7", "s": "0", "kt": "1", "k": [ "DB5PKs2yTLWkgoaboz2rR0g_im9FBkQF2g8VWcjt6oUP" ], "nt": "1", "n": [ "EPnrEmgwqaIp50GHyR9jplHipD5mOwn7sG5QkD7p2adM" ], "bt": "1", "b": [ "BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha" ], "c": [], "a": [], "di": "EHDW4TgdyYTkUwxtZlIt03poPBA4Ouk5w4LJ6MTJJRLB" } Key observations from the delegate's status: - `Delegated Identifier`: This line confirms it's a delegated AID. - `Delegator: ✔ Anchored`: This shows the delegator's prefix and confirms that the delegation has been successfully anchored in the delegator's KEL. - In the JSON event data: - `"t": "dip"`: This signifies a Delegated Inception Event. This is the establishment event for the delegated AID. - `"di"`: This field contains the prefix of the Delegator AID. It cryptographically links this delegated AID back to its delegator. The prefix of a delegated AID is a SAID of its own `dip` event, which includes the delegator's AID. This creates the strong cryptographic binding characteristic of KERI delegation. ## Rotating Delegated Identifiers Rotating the keys of a delegated AID also follows a cooperative, two-step process, similar to its inception. The delegate initiates the rotation, and the delegator must confirm it. #### Delegated Rotation Steps: 1. Delegate performs a rotation with `kli rotate`. 2. Delegator approves the rotation with `kli delegate confirm`. The delegate uses `kli rotate` with the`--proxy` parameter. This command is run in the background as it waits for the delegator's confirmation. The delegator confirms the delegated rotation with `kli delegate confirm`. This action creates a new anchoring event in the delegator's KEL for the delegate's rotation. The use of the `--interact` flag to `kli delegate confirm` instructs the delegator to anchor the approving seal in an interaction event. ```python pr_title(f"Rotating delegated AID") command = f""" kli rotate --name {delegate_keystore} \ --alias {delegate_alias} \ --proxy {delegate_proxy_alias} """ exec_bg(command) command = f""" kli delegate confirm --name {delegator_keystore} \ --alias {delegator_alias} \ --interact \ --auto """ output = exec(command, True) # Show the output of the background processes pr_message(f"Rotation") pr_message(output) pr_continue() ``` Rotating delegated AID Command kli rotate --name delegate_keystore --alias delegate_alias --proxy delegate_proxy_alias started with PID: 946 Rotation ['Delegagtor Prefix EHDW4TgdyYTkUwxtZlIt03poPBA4Ouk5w4LJ6MTJJRLB', 'Delegate EESIOsSAKBrCvozIIAKcj87hQvntj_wcWiTHuu7AZPI7 rotation Anchored at Seq. No. 2', 'Delegate EESIOsSAKBrCvozIIAKcj87hQvntj_wcWiTHuu7AZPI7 rotation event committed.'] You can continue ✅ Now, let's examine the status of the delegate AID after the rotation. ```python pr_title(f"Delegated AID status") !kli status --name delegate_keystore --alias delegate_alias --verbose ``` Delegated AID status Alias: delegate_alias Identifier: EESIOsSAKBrCvozIIAKcj87hQvntj_wcWiTHuu7AZPI7 Seq No: 1 Delegated Identifier Delegator: EHDW4TgdyYTkUwxtZlIt03poPBA4Ouk5w4LJ6MTJJRLB ✔ Anchored Witnesses: Count: 1 Receipts: 1 Threshold: 1 Public Keys: 1. DN4WorNlMd_93dpHTFMLZoKT2LUH2na3UyMy55JuXZvu Witnesses: 1. BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha { "v": "KERI10JSON00018d_", "t": "dip", "d": "EESIOsSAKBrCvozIIAKcj87hQvntj_wcWiTHuu7AZPI7", "i": "EESIOsSAKBrCvozIIAKcj87hQvntj_wcWiTHuu7AZPI7", "s": "0", "kt": "1", "k": [ "DB5PKs2yTLWkgoaboz2rR0g_im9FBkQF2g8VWcjt6oUP" ], "nt": "1", "n": [ "EPnrEmgwqaIp50GHyR9jplHipD5mOwn7sG5QkD7p2adM" ], "bt": "1", "b": [ "BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha" ], "c": [], "a": [], "di": "EHDW4TgdyYTkUwxtZlIt03poPBA4Ouk5w4LJ6MTJJRLB" } { "v": "KERI10JSON000160_", "t": "drt", "d": "EPMRGelfgPh4Nzt3EnvE00iIfqLz8Gvc2e8XV1Xq_8Sx", "i": "EESIOsSAKBrCvozIIAKcj87hQvntj_wcWiTHuu7AZPI7", "s": "1", "p": "EESIOsSAKBrCvozIIAKcj87hQvntj_wcWiTHuu7AZPI7", "kt": "1", "k": [ "DN4WorNlMd_93dpHTFMLZoKT2LUH2na3UyMy55JuXZvu" ], "nt": "1", "n": [ "EGAdXMUkWeRBtcdMbQIJ--eNpbdktxX3UgC9D7-EaQqt" ], "bt": "1", "br": [], "ba": [], "a": [] } Observations from the delegate's KEL after rotation: - `Seq No: 1`: The sequence number has incremented. - A new event has been added to the KEL with `"t": "drt"`. This signifies a Delegated Rotation Event. It's also an establishment event. - The public keys `k` and next key digest `n` have changed, reflecting the rotation. - The delegate's AID prefix `i` remains the same. ## Understanding the Delegator's KEL Let's now examine the delegator's KEL to see how these delegation operations are recorded and anchored. ```python pr_title(f"Delegator AID status") !kli status --name delegator_keystore --alias delegator_alias --verbose ``` Delegator AID status Alias: delegator_alias Identifier: EHDW4TgdyYTkUwxtZlIt03poPBA4Ouk5w4LJ6MTJJRLB Seq No: 2 Witnesses: Count: 3 Receipts: 3 Threshold: 2 Public Keys: 1. DG7EhH42hjxj77O-InfYucbj7AacdEbZKnMw2qhKrarD Witnesses: 1. BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha 2. BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM 3. BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX { "v": "KERI10JSON0001b7_", "t": "icp", "d": "EHDW4TgdyYTkUwxtZlIt03poPBA4Ouk5w4LJ6MTJJRLB", "i": "EHDW4TgdyYTkUwxtZlIt03poPBA4Ouk5w4LJ6MTJJRLB", "s": "0", "kt": "1", "k": [ "DG7EhH42hjxj77O-InfYucbj7AacdEbZKnMw2qhKrarD" ], "nt": "1", "n": [ "ECxpSF1SUwO0frr7yy_AiTwXgbHfMg16yy6c9_Uf7o0Q" ], "bt": "2", "b": [ "BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha", "BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM", "BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX" ], "c": [], "a": [] } { "v": "KERI10JSON00013a_", "t": "ixn", "d": "EFkNaQOyxLhMcXSdK4Vb_d5_ze_xua9hM9YQ02LO_wZY", "i": "EHDW4TgdyYTkUwxtZlIt03poPBA4Ouk5w4LJ6MTJJRLB", "s": "1", "p": "EHDW4TgdyYTkUwxtZlIt03poPBA4Ouk5w4LJ6MTJJRLB", "a": [ { "i": "EESIOsSAKBrCvozIIAKcj87hQvntj_wcWiTHuu7AZPI7", "s": "0", "d": "EESIOsSAKBrCvozIIAKcj87hQvntj_wcWiTHuu7AZPI7" } ] } { "v": "KERI10JSON00013a_", "t": "ixn", "d": "EGKBpLEeTiIelhhR79KwFUSUD5bwKpytkebovqwLCxXL", "i": "EHDW4TgdyYTkUwxtZlIt03poPBA4Ouk5w4LJ6MTJJRLB", "s": "2", "p": "EFkNaQOyxLhMcXSdK4Vb_d5_ze_xua9hM9YQ02LO_wZY", "a": [ { "i": "EESIOsSAKBrCvozIIAKcj87hQvntj_wcWiTHuu7AZPI7", "s": "1", "d": "EPMRGelfgPh4Nzt3EnvE00iIfqLz8Gvc2e8XV1Xq_8Sx" } ] } Key observations from the delegator's KEL: - Sequence Number `s: "1"` (Interaction Event): - This event was created when the delegator confirmed the delegated inception. - The `a` (anchors/payload) array contains a delegated event seal: - `"i"`: The prefix of the delegate AID. - `"s": "0"`: The sequence number of the delegate's event being anchored (the `dip` event at sequence 0). - `"d"`: The SAID (digest) of the delegate's `dip` event. - Sequence Number `s: "2"` (Interaction Event): - This event was created when the delegator confirmed the delegated rotation. - The `a` array contains another delegated event seal: - `"i"`: The prefix of the delegate AID. - `"s": "1"`: The sequence number of the delegate's event being anchored (the drt event at sequence 1). - `"d"`: The SAID (digest) of the delegate's drt event. These seals embedded within interaction events, specifically the "a" attributes section of the interaction events, in the delegator's KEL are the cryptographic proof that the delegator authorized the delegate's inception and rotation events. Conversely, the delegated AID's `dip` event also contains a di field pointing to the delegator, and its establishment events (like `dip` and `drt`) implicitly include a delegating event location seal that refers back to the specific event in the delegator's KEL that authorized them (though not explicitly shown in the simplified `kli status` output for the delegate, this is part of the full event structure). This creates the verifiable, cooperative link between the two AIDs.
ℹ️ NOTE
---
The security of KERI's cooperative delegation model is robust. To illicitly create or rotate a delegated AID, an attacker would generally need to compromise keys from both the delegator and the delegate (specifically, the delegate's pre-rotated keys and the delegator's current signing keys for the anchoring event). Furthermore, the delegator has mechanisms to recover a compromised delegation using something called "superseding delegated recovery rotation," covered in depth in a separate training.
📝 SUMMARY
---
KERI delegation allows an AID (delegator) to authorize another AID (delegate) for specific purposes. This is a cooperative process requiring actions from both parties.
• Delegated Inception (dip): The delegate initiates a request (e.g., via a proxy AID). The delegator confirms this by creating an anchoring event in its KEL, which contains a seal pointing to the delegate's dip event. The delegate's dip event includes the delegator's AID in its di field. The delegate's AID prefix is a SAID of its dip event.
• Delegated Rotation (drt): Similar to inception, the delegate initiates the rotation, and the delegator confirms with another anchoring event in its KEL. The delegate's KEL will show a drt event.
• Anchoring: The delegator's KEL contains seals (AID, sequence number, and digest of the delegate's event) that provide verifiable proof of the authorized delegation. This creates a strong, bi-directional cryptographic link.
• Security: The cooperative nature enhances security, as unauthorized delegation typically requires compromising keys from both entities.
[<- Prev (Connecting Controllers)](101_45_Connecting_controllers.ipynb) | [Next (Multisignature Identifiers) ->](101_48_Multisignature_Identifiers.ipynb) # KERI Core: Multi-Signature Group Identifiers
🎯 OBJECTIVE
---
This notebook introduces the concept of multi-signature (multisig) group Autonomic Identifiers (AIDs) in KERI. It will demonstrate how to:
• Set up individual AIDs that will participate in a multisig group.
• Configure and incept a multisig group AID where actions require signatures from multiple participants.
• Perform interaction events with the multisig group AID.
• Rotate the keys for the multisig group AID.
• Understand the structure of inception (icp), interaction (ixn), and rotation (rot) events for multisig group AIDs.
## Introduction to Multi-Signature Identifiers Multi-signature (multisig) identifier schemes in KERI enhance security and enable collective control over an identifier by requiring signatures from multiple authorized keys to validate an event. This is particularly useful for organizations or groups where shared authority is necessary. A multi-signature identifier is also known as a group identifier, or multi-signature group identifier. A multi-signature group AID is essentially an identifier whose controlling authority is distributed among a set of participating AIDs. Each key event for this group AID, such as inception, interaction, or rotation, must be authorized by a sufficient number of these participating AIDs according to the defined signing threshold. The signing threshold may be changed with a rotation event and group members may be added or removed as needed. #### Illustration of end product The result of this training will be the creation of a multisig group identifier illustrated in the middle of the diagram below.  ## Initial Setup of Participant AIDs The setup involves: - Individual Participant AIDs: Each entity that will be part of the multisig group first has its own individual AID. - Group Configuration: A configuration is defined specifying which AIDs are members of the group and the signing threshold (e.g., 2 out of 3 participants must sign). - Group Inception: The multisig group AID is incepted. This is a cooperative process where participating AIDs signal their agreement to form the group. The resulting group AID prefix is a self-addressing identifier derived from its inception event data, which includes a list of member AID prefixes and the threshold policies for signing and rotation. - Group Operations: Subsequent operations like interaction events or key rotations for the group AID also require the specified threshold of signatures from the participating AIDs. For this notebook, we will create two AIDs, `party1_alias` and `party2_alias`, each in its own keystore. These will act as the initial members of our multisig group. ```python # Imports and Utility functions from scripts.utils import exec, exec_bg, clear_keri from scripts.utils import pr_continue, pr_title, pr_message import json import time clear_keri() # Party 1 Keystore party1_keystore = "party1_keystore" party1_salt= "0AAW49QDCAuz0I-R1yCY8wa6" # Use hardcoded salt so that the AID stays the same. Swap with `exec("kli salt")` for a dynamic salt. party1_alias = "party1_alias" pr_title("Initializing keystores") # The `keystore_init_config.json` file is used here # to pre-configure the keystores with default witness information. !kli init --name {party1_keystore} \ --nopasscode \ --salt {party1_salt} \ --config-dir ./config \ --config-file keystore_init_config.json # multisig2 Keystore party2_keystore = "party2_keystore" party2_salt = "0AC_OfvFyZcKRspiawo-Pgwz" # Use hardcoded salt so that the AID stays the same. Swap with `exec("kli salt")` for a dynamic salt. party2_alias = "party2_alias" !kli init --name {party2_keystore} \ --nopasscode \ --salt {party2_salt} \ --config-dir ./config \ --config-file keystore_init_config.json pr_title("Incepting multisig parts") # multisig1 AID inception !kli incept --name {party1_keystore} \ --alias {party1_alias} \ --icount 1 \ --isith 1 \ --ncount 1 \ --nsith 1 \ --wits BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha \ --wits BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM \ --wits BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX \ --toad 2 \ --transferable # multisig2 AID Inception !kli incept --name {party2_keystore} \ --alias {party2_alias} \ --icount 1 \ --isith 1 \ --ncount 1 \ --nsith 1 \ --wits BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha \ --wits BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM \ --wits BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX \ --toad 2 \ --transferable pr_continue() ``` Proceeding with deletion of '/usr/local/var/keri/' without confirmation. ✅ Successfully removed: /usr/local/var/keri/ Initializing keystores KERI Keystore created at: /usr/local/var/keri/ks/party1_keystore KERI Database created at: /usr/local/var/keri/db/party1_keystore KERI Credential Store created at: /usr/local/var/keri/reg/party1_keystore Loading 3 OOBIs... http://witness-demo:5642/oobi/BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha/controller?name=Wan&tag=witness succeeded http://witness-demo:5643/oobi/BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM/controller?name=Wes&tag=witness succeeded http://witness-demo:5644/oobi/BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX/controller?name=Wil&tag=witness succeeded KERI Keystore created at: /usr/local/var/keri/ks/party2_keystore KERI Database created at: /usr/local/var/keri/db/party2_keystore KERI Credential Store created at: /usr/local/var/keri/reg/party2_keystore Loading 3 OOBIs... http://witness-demo:5642/oobi/BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha/controller?name=Wan&tag=witness succeeded http://witness-demo:5643/oobi/BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM/controller?name=Wes&tag=witness succeeded http://witness-demo:5644/oobi/BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX/controller?name=Wil&tag=witness succeeded Incepting multisig parts Waiting for witness receipts... Prefix ELPvwxEI6nEv_Imtv89jgACiDvCFlgl50Ls6UatFtLyY Public key 1: DOKTEjSCgBNZLr62VaTUbQh1dpP7n6KUaIfZhak-aaXU Waiting for witness receipts... Prefix EOZIXcOdHPFkSEN_85QbeFC4GKo4nVqVx70RuDug-jBB Public key 1: DDyva00Vg_tIbK9V15XiIodr0tS3JDLqQvQC23DTp-h6 You can continue ✅ ## Creating the Multi-Signature Group AID With the individual participant AIDs in place, now proceed to create the multisig group AID. This involves several steps: - authorizing mailbox roles for discovery - exchanging OOBIs - configuring the multisig parameters - cooperatively incepting the group AID. ### Adding Mailbox Role To allow the cooperative inception process, each participant AID needs to authorize one of its witnesses to act as a `mailbox`. This allows other participants to send messages (like the group inception proposal) to them indirectly via this witness.  The `kli ends add` command is used to authorize an end role. `--eid`: Specifies the prefix of the witness AID being authorized for the new role. `--role`: Defines the role being assigned. ```python # Add new endpoint role authorization. pr_title("Adding mailbox role") role = "mailbox" !kli ends add --name {party1_keystore} \ --alias {party1_alias} \ --eid BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM \ --role {role} # Add new endpoint role authorization. !kli ends add --name {party2_keystore} \ --alias {party2_alias} \ --eid BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX \ --role {role} pr_continue() ``` Adding mailbox role End role authorization added for role mailbox End role authorization added for role mailbox You can continue ✅ ### Resolving OOBIs Next, the participants need to discover each other. This is done by generating and resolving Out-of-Band Introductions (OOBIs) that point to their newly authorized mailbox endpoints. ```python # OOBI Generation pr_title("Generating OOBIs") # party1 generates mailbox OOBI for its AID party1_oobi = exec(f"kli oobi generate --name {party1_keystore} --alias {party1_alias} --role {role}") # party2 generates mailbox OOBI for its AID party2_oobi = exec(f"kli oobi generate --name {party2_keystore} --alias {party2_alias} --role {role}") pr_message("Party 1 OOBI: " + party1_oobi) pr_message("Party 2 OOBI: " + party2_oobi) # OOBI Exchange pr_title("Resolving OOBIs") !kli oobi resolve --name {party1_keystore} \ --oobi-alias {party2_alias} \ --oobi {party2_oobi} !kli oobi resolve --name {party2_keystore} \ --oobi-alias {party1_alias} \ --oobi {party1_oobi} pr_continue() ``` Generating OOBIs Party 1 OOBI: http://witness-demo:5643/oobi/ELPvwxEI6nEv_Imtv89jgACiDvCFlgl50Ls6UatFtLyY/mailbox/BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM Party 2 OOBI: http://witness-demo:5644/oobi/EOZIXcOdHPFkSEN_85QbeFC4GKo4nVqVx70RuDug-jBB/mailbox/BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX Resolving OOBIs http://witness-demo:5644/oobi/EOZIXcOdHPFkSEN_85QbeFC4GKo4nVqVx70RuDug-jBB/mailbox/BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX resolved http://witness-demo:5643/oobi/ELPvwxEI6nEv_Imtv89jgACiDvCFlgl50Ls6UatFtLyY/mailbox/BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM resolved You can continue ✅ ### Configuring the Multi-Signature Group Setting up the configuration for a multi-signature group identifier is similar to a single-signature identifier with the exception of the "aids" field where the participants are defined as a list of member AID prefixes. All of the other typical configuration including transferability, witnesses, TOAD, and signing and rotation thresholds still apply. The parameters for the multisig group AID are defined in a JSON configuration file. This file specifies: - `aids`: A list of the prefixes of the participating AIDs. - `transferable`: Whether the group AID itself will be transferable (i.e., its keys can be rotated). - `wits`: A list of witness AIDs for the group AID. - `toad`: The Threshold of Accountable Duplicity for the group AID's events. This defines how many witness receipts are needed for an event to be considered accountable by the controller group. - `isith`: The initial signing threshold for the group AID's inception event. This can be an integer (e.g., "2" for 2-of-N) or a list of weights for a weighted threshold scheme. For this example, "2" means both participants must sign. - `nsith`: The signing threshold for the next key set (for future rotations). Similar to isith. ```python # Multisig participants Configuration pr_title(f"Building multisig config file") # Multisig participants prefixes party1_pre = exec(f"kli aid --name {party1_keystore} --alias {party1_alias}") party2_pre = exec(f"kli aid --name {party2_keystore} --alias {party2_alias}") pr_message("Party 1 prefix: " + party1_pre) pr_message("Party 2 prefix: " + party1_pre) # multisig configuration multisig_inception_config = { "aids": [ party1_pre, party2_pre ], "transferable": True, "wits": [ "BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha", "BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM", "BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX" ], "toad": 2, "isith": "2", "nsith": "2" } # Specify the filename file_path = './config/multisig/multisig_inception_config.json' # Write the configuration data to the JSON file with open(file_path, 'w') as f: json.dump(multisig_inception_config, f, indent=2) pr_message(f"Multisig config: {file_path}") !cat {file_path} pr_continue() ``` Building multisig config file Party 1 prefix: ELPvwxEI6nEv_Imtv89jgACiDvCFlgl50Ls6UatFtLyY Party 2 prefix: ELPvwxEI6nEv_Imtv89jgACiDvCFlgl50Ls6UatFtLyY Multisig config: ./config/multisig/multisig_inception_config.json { "aids": [ "ELPvwxEI6nEv_Imtv89jgACiDvCFlgl50Ls6UatFtLyY", "EOZIXcOdHPFkSEN_85QbeFC4GKo4nVqVx70RuDug-jBB" ], "transferable": true, "wits": [ "BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha", "BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM", "BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX" ], "toad": 2, "isith": "2", "nsith": "2" } You can continue ✅ ### Incepting the Multi-Signature Group AID The inception of a multisig group AID is a cooperative process. One participant (here, `party1_alias`) initiates the group inception using `kli multisig incept`. - `--group`: Assigns a human-readable alias to the multisig group AID being created. - `--file`: Points to the JSON configuration file created in the previous step. This command will propose the inception event and wait for other members to join and sign. The other participant(s) (here, `party2_alias`) join the proposed inception using `kli multisig join`. - `--group`: Specifies the alias of the group they are joining. - `--auto`: Automatically approves the join request **(in a real scenario, this would be an interactive confirmation)**. This command will fetch the proposed event, sign it, and send its signature back. Once all required signatures are gathered, the inception event is finalized and published to the witnesses. These commands are run in the background here, as they would normally be interactive, waiting for each other. ```python pr_title(f"Incepting multisig AID") multisig_group = "multisig_group" command = f""" kli multisig incept --name {party1_keystore} \ --alias {party1_alias} \ --group {multisig_group} \ --file {file_path} > ./logs/multisig_event.log """ incept1_process = exec_bg(command) command = f""" kli multisig join --name {party2_keystore} \ --group {multisig_group} \ --auto > ./logs/multisig_join.log """ join_process = exec_bg(command) while(incept1_process.poll() is None or join_process.poll() is None): print("Waiting for multisig inception to complete...\n") time.sleep(2) # Show the output of the background processes pr_message(f"Multisig Event") !cat ./logs/multisig_event.log pr_message(f"Multisig Join") !cat ./logs/multisig_join.log pr_continue() ``` Incepting multisig AID Command kli multisig incept --name party1_keystore --alias party1_alias --group multisig_group --file ./config/multisig/multisig_inception_config.json > ./logs/multisig_event.log started with PID: 2386 Command kli multisig join --name party2_keystore --group multisig_group --auto > ./logs/multisig_join.log started with PID: 2387 Waiting for multisig inception to complete... Waiting for multisig inception to complete... Multisig Event Group identifier inception initialized for EEyK9sCty5qBjnAmc_-2fcsW-68sHfMgpH6bzc2vO0h- Alias: multisig_group Identifier: EEyK9sCty5qBjnAmc_-2fcsW-68sHfMgpH6bzc2vO0h- Seq No: 0 Group Identifier Local Indentifier: ELPvwxEI6nEv_Imtv89jgACiDvCFlgl50Ls6UatFtLyY ✔ Fully Signed Witnesses: Count: 3 Receipts: 3 Threshold: 2 Public Keys: 1. DOKTEjSCgBNZLr62VaTUbQh1dpP7n6KUaIfZhak-aaXU 2. DDyva00Vg_tIbK9V15XiIodr0tS3JDLqQvQC23DTp-h6 Multisig Join Waiting for group multisig events... Group Multisig Inception proposed: Participants: +-------+--------------+----------------------------------------------+ | Local | Name | AID | +-------+--------------+----------------------------------------------+ | | party1_alias | ELPvwxEI6nEv_Imtv89jgACiDvCFlgl50Ls6UatFtLyY | | * | party2_alias | EOZIXcOdHPFkSEN_85QbeFC4GKo4nVqVx70RuDug-jBB | +-------+--------------+----------------------------------------------+ Configuration: +---------------------+----------------------------------------------+ | Name | Value | +---------------------+----------------------------------------------+ | Signature Threshold | 2 | | Establishment Only | False | | Do Not Delegate | False | | Witness Threshold | 2 | | Witnesses | BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha | | | BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM | | | BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX | +---------------------+----------------------------------------------+ Alias: multisig_group Identifier: EEyK9sCty5qBjnAmc_-2fcsW-68sHfMgpH6bzc2vO0h- Seq No: 0 Group Identifier Local Indentifier: EOZIXcOdHPFkSEN_85QbeFC4GKo4nVqVx70RuDug-jBB ✔ Fully Signed Witnesses: Count: 3 Receipts: 3 Threshold: 2 Public Keys: 1. DOKTEjSCgBNZLr62VaTUbQh1dpP7n6KUaIfZhak-aaXU 2. DDyva00Vg_tIbK9V15XiIodr0tS3JDLqQvQC23DTp-h6 You can continue ✅ ### Multi-signature inception result The diagram below represents the multi-signature identifier created. Each single signature identifier contributed both a signing key and a rotation key, shown with the arrows from the single sig keystores (party1_keystore, party2_keystore) to the virtual multisig group identifier in the middle of the diagram.  ### Verifying Multi-Signature AID Status After successful inception, you can check the status of the `multisig_group` AID using `kli status --verbose`. The output shows the inception event (`icp`). Key fields for a multisig AID include: - `i`: The prefix of the multisig group AID. - `k`: A list of the public keys of the participating AIDs that form the current signing key set for the group. - `kt`: The current signing threshold (e.g., "2", meaning 2 signatures are required). - `n`: A list of digests of the public keys for the next rotation (pre-rotation). - `nt`: The signing threshold for the next key set. - `b`: The list of witness AIDs for this group AID. - `bt`: The Threshold of Accountable Duplicity (TOAD) for this group AID. This inception event (`icp`) is an establishment event that cryptographically binds the group AID to its initial set of controlling keys (the participants' keys) and the defined signing policies. ```python pr_title(f"Multisig AID status") !kli status --name party1_keystore --alias multisig_group --verbose ``` Multisig AID status Alias: multisig_group Identifier: EEyK9sCty5qBjnAmc_-2fcsW-68sHfMgpH6bzc2vO0h- Seq No: 0 Group Identifier Local Indentifier: ELPvwxEI6nEv_Imtv89jgACiDvCFlgl50Ls6UatFtLyY ✔ Fully Signed Witnesses: Count: 3 Receipts: 3 Threshold: 2 Public Keys: 1. DOKTEjSCgBNZLr62VaTUbQh1dpP7n6KUaIfZhak-aaXU 2. DDyva00Vg_tIbK9V15XiIodr0tS3JDLqQvQC23DTp-h6 Witnesses: 1. BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha 2. BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM 3. BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX { "v": "KERI10JSON000215_", "t": "icp", "d": "EEyK9sCty5qBjnAmc_-2fcsW-68sHfMgpH6bzc2vO0h-", "i": "EEyK9sCty5qBjnAmc_-2fcsW-68sHfMgpH6bzc2vO0h-", "s": "0", "kt": "2", "k": [ "DOKTEjSCgBNZLr62VaTUbQh1dpP7n6KUaIfZhak-aaXU", "DDyva00Vg_tIbK9V15XiIodr0tS3JDLqQvQC23DTp-h6" ], "nt": "2", "n": [ "EDsRlPLnlcvZZVv-T1GoEZE5x0_QtRpSoSiAOurMmLz9", "EG-jLWaS8gE9wuPCArQk_81XZkr-x3WWHuFNYt_LpZXE" ], "bt": "2", "b": [ "BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha", "BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM", "BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX" ], "c": [], "a": [] } ## Signing and Anchoring Arbitrary data in an Interaction Event When you want to sign and anchor arbitrary data to a key event log for a multisig identifier you use an interaction event. An interaction event (`ixn`) is a non-establishment event used to anchor arbitrary data to the Key Event Log (KEL) of an AID. For a multisig group AID, an interaction event must also be signed by the required threshold of participating AIDs. The `kli multisig interact` command initiates an interaction event for the group, and `kli multisig join` is used by other participants to add their signatures. ```python pr_title(f"Performing interaction event") # Anchor data for the interaction event (ixn) data = """'{"d": "arbitrary data"}'""" # Keep string format as is! command = f""" kli multisig interact --name {party1_keystore} \ --alias {multisig_group} \ --data {data} > ./logs/multisig_event.log """ interact1_process = exec_bg(command) command = f""" kli multisig join --name {party2_keystore} \ --group {multisig_group} \ --auto > ./logs/multisig_join.log """ join_process = exec_bg(command) while(interact1_process.poll() is None or join_process.poll() is None): print("Waiting for multisig interaction to complete...\n") time.sleep(2) # Show the output of the background processes pr_message(f"Multisig Event") !cat ./logs/multisig_event.log pr_message(f"Multisig Join") !cat ./logs/multisig_join.log pr_continue() ``` Performing interaction event Command kli multisig interact --name party1_keystore --alias multisig_group --data '{"d": "arbitrary data"}' > ./logs/multisig_event.log started with PID: 2399 Command kli multisig join --name party2_keystore --group multisig_group --auto > ./logs/multisig_join.log started with PID: 2401 Waiting for multisig interaction to complete... Waiting for multisig interaction to complete... Waiting for multisig interaction to complete... Waiting for multisig interaction to complete... Waiting for multisig interaction to complete... Waiting for multisig interaction to complete... Waiting for multisig interaction to complete... Waiting for multisig interaction to complete... Waiting for multisig interaction to complete... Waiting for multisig interaction to complete... Waiting for multisig interaction to complete... Waiting for multisig interaction to complete... Waiting for multisig interaction to complete... Waiting for multisig interaction to complete... Waiting for multisig interaction to complete... Waiting for multisig interaction to complete... Waiting for multisig interaction to complete... Waiting for multisig interaction to complete... Multisig Event Alias: multisig_group Identifier: EEyK9sCty5qBjnAmc_-2fcsW-68sHfMgpH6bzc2vO0h- Seq No: 1 Group Identifier Local Indentifier: ELPvwxEI6nEv_Imtv89jgACiDvCFlgl50Ls6UatFtLyY ✔ Fully Signed Witnesses: Count: 3 Receipts: 3 Threshold: 2 Public Keys: 1. DOKTEjSCgBNZLr62VaTUbQh1dpP7n6KUaIfZhak-aaXU 2. DDyva00Vg_tIbK9V15XiIodr0tS3JDLqQvQC23DTp-h6 Multisig Join Waiting for group multisig events... Group Multisig Interaction for multisig_group (EEyK9sCty5qBjnAmc_-2fcsW-68sHfMgpH6bzc2vO0h-) proposed: Data: [ { "d": "arbitrary data" } ] Alias: multisig_group Identifier: EEyK9sCty5qBjnAmc_-2fcsW-68sHfMgpH6bzc2vO0h- Seq No: 1 Group Identifier Local Indentifier: EOZIXcOdHPFkSEN_85QbeFC4GKo4nVqVx70RuDug-jBB ✔ Fully Signed Witnesses: Count: 3 Receipts: 3 Threshold: 2 Public Keys: 1. DOKTEjSCgBNZLr62VaTUbQh1dpP7n6KUaIfZhak-aaXU 2. DDyva00Vg_tIbK9V15XiIodr0tS3JDLqQvQC23DTp-h6 You can continue ✅ ### Verifying Interaction Event Let's examine the KEL for `multisig_group` again to see the `ixn` event. The interaction event (`ixn`) does not change the establishment keys but anchors data (`a` field) to the KEL. It is signed by the current authoritative keys established by the preceding `icp` event. The `p` field contains the digest of the previous event (`icp` in this case), ensuring the chain's integrity. ```python pr_title(f"Multisig AID status") !kli status --name party1_keystore --alias multisig_group --verbose ``` Multisig AID status Alias: multisig_group Identifier: EEyK9sCty5qBjnAmc_-2fcsW-68sHfMgpH6bzc2vO0h- Seq No: 1 Group Identifier Local Indentifier: ELPvwxEI6nEv_Imtv89jgACiDvCFlgl50Ls6UatFtLyY ✔ Fully Signed Witnesses: Count: 3 Receipts: 3 Threshold: 2 Public Keys: 1. DOKTEjSCgBNZLr62VaTUbQh1dpP7n6KUaIfZhak-aaXU 2. DDyva00Vg_tIbK9V15XiIodr0tS3JDLqQvQC23DTp-h6 Witnesses: 1. BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha 2. BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM 3. BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX { "v": "KERI10JSON000215_", "t": "icp", "d": "EEyK9sCty5qBjnAmc_-2fcsW-68sHfMgpH6bzc2vO0h-", "i": "EEyK9sCty5qBjnAmc_-2fcsW-68sHfMgpH6bzc2vO0h-", "s": "0", "kt": "2", "k": [ "DOKTEjSCgBNZLr62VaTUbQh1dpP7n6KUaIfZhak-aaXU", "DDyva00Vg_tIbK9V15XiIodr0tS3JDLqQvQC23DTp-h6" ], "nt": "2", "n": [ "EDsRlPLnlcvZZVv-T1GoEZE5x0_QtRpSoSiAOurMmLz9", "EG-jLWaS8gE9wuPCArQk_81XZkr-x3WWHuFNYt_LpZXE" ], "bt": "2", "b": [ "BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha", "BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM", "BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX" ], "c": [], "a": [] } { "v": "KERI10JSON0000e1_", "t": "ixn", "d": "ECFIsW1NE0jI3kd576KmSMSDqf4E_Z74Si1G9I6OdMrZ", "i": "EEyK9sCty5qBjnAmc_-2fcsW-68sHfMgpH6bzc2vO0h-", "s": "1", "p": "EEyK9sCty5qBjnAmc_-2fcsW-68sHfMgpH6bzc2vO0h-", "a": [ { "d": "arbitrary data" } ] } ## Rotation Event for Multi-Signature Group AID Rotating the keys for a multisig group AID also requires a cooperative process as each participant must first rotate the keys of its single signature identifier participating as a member of the multi-signature group prior to being able to rotate the group. This is required because each rotation of a multi-signature identifier must use new signing and rotation keys in each rotation event. ### Rotating Individual Participant Keys First, each individual participant AID must rotate its own keys for the participating single signature identifier. This ensures that when they participate in the group rotation, they are using their new, updated keys. - `kli rotate` is used for individual AID key rotation. - `kli query` is used to ensure other participants are aware of these individual rotations. Updating each participant on the latest key state via a key state refresh is required in order to create a multi-signature rotation event. This is because the rotation threshold check will fail until there are enough new keys available for a new rotation event to be created for the multi-signature identifier. ```python pr_title(f"Rotating multisig participant single signature keys") !kli rotate --name {party1_keystore} \ --alias {party1_alias} !kli query --name {party2_keystore} \ --alias {party2_alias} \ --prefix {party1_pre} !kli rotate --name {party2_keystore} \ --alias {party2_alias} !kli query --name {party1_keystore} \ --alias {party1_alias} \ --prefix {party2_pre} pr_continue() ``` Rotating multisig participant single signature keys Waiting for witness receipts... Prefix ELPvwxEI6nEv_Imtv89jgACiDvCFlgl50Ls6UatFtLyY New Sequence No. 1 Public key 1: DED9rD7Mpbtjtej7Ueyc_R6894f1hQ-YhcZtdAI0WIIn Checking for updates... Identifier: ELPvwxEI6nEv_Imtv89jgACiDvCFlgl50Ls6UatFtLyY Seq No: 1 Witnesses: Count: 3 Receipts: 3 Threshold: 3 Public Keys: 1. DED9rD7Mpbtjtej7Ueyc_R6894f1hQ-YhcZtdAI0WIIn Waiting for witness receipts... Prefix EOZIXcOdHPFkSEN_85QbeFC4GKo4nVqVx70RuDug-jBB New Sequence No. 1 Public key 1: DAz9zLvu7sXHI-YJVlNlS67B0A1SJJvG-MwlAsT2OOhF Checking for updates... Identifier: EOZIXcOdHPFkSEN_85QbeFC4GKo4nVqVx70RuDug-jBB Seq No: 1 Witnesses: Count: 3 Receipts: 3 Threshold: 3 Public Keys: 1. DAz9zLvu7sXHI-YJVlNlS67B0A1SJJvG-MwlAsT2OOhF You can continue ✅ You want to make sure that the latest sequence number, which will be sequence number one, shows in the status for each key state query. This is required so that each participant in the multisig has a new key to contribute to the multisig rotation. ### Rotating the Multi-Signature Group Keys Once the participants have rotated their individual keys, the group rotation can proceed. The `kli multisig rotate` command initiates the rotation for the group. - `--smids`: **Signing member identifiers**; specifies the list of participant AIDs that will contribute signing keys for the current rotation event. The contributed keys will be aauthorized to sign events after this rotation completes. - `--rmids`: **Rotation member identifiers**; specifies the list of participant AIDs that will contribute rotation keys, as digests, to form the set of cryptographic pre-comittments of keys (pre-rotation) that will become the next set of signing keys after the next rotation. - `--isith`: **Signing (current) threshold**; The signing threshold for the current rotation event. Here, `["1/2", "1/2"]` represents a weighted threshold where each of the two participants has a weight of 1/2, and a sum of 1 (i.e., both signatures) is required. - `--nsith`: **Next (rotation) threshold**; The signing threshold for the next set of keys (pre-rotation). Again, `kli multisig join` is used by the other participant to co-sign the group rotation event. ```python pr_title(f"Rotating multisig group") command = f""" kli multisig rotate --name {party1_keystore} \ --alias {multisig_group} \ --smids {party1_pre} \ --smids {party2_pre} \ --rmids {party1_pre} \ --rmids {party2_pre} \ --isith '["1/2", "1/2"]' \ --nsith '["1/2", "1/2"]' > ./logs/multisig_event.log """ incept_process = exec_bg(command) command = f""" kli multisig join --name {party2_keystore} \ --group {multisig_group} \ --auto > ./logs/multisig_join.log """ join_process = exec_bg(command) while(incept_process.poll() is None or join_process.poll() is None): print("Waiting for multisig rotation to complete...\n") time.sleep(2) # Show the output of the background processes pr_message(f"Multisig Event") !cat ./logs/multisig_event.log pr_message(f"Multisig Join") !cat ./logs/multisig_join.log pr_continue() ``` Rotating multisig group Command kli multisig rotate --name party1_keystore --alias multisig_group --smids ELPvwxEI6nEv_Imtv89jgACiDvCFlgl50Ls6UatFtLyY --smids EOZIXcOdHPFkSEN_85QbeFC4GKo4nVqVx70RuDug-jBB --rmids ELPvwxEI6nEv_Imtv89jgACiDvCFlgl50Ls6UatFtLyY --rmids EOZIXcOdHPFkSEN_85QbeFC4GKo4nVqVx70RuDug-jBB --isith '["1/2", "1/2"]' --nsith '["1/2", "1/2"]' > ./logs/multisig_event.log started with PID: 2471 Command kli multisig join --name party2_keystore --group multisig_group --auto > ./logs/multisig_join.log started with PID: 2472 Waiting for multisig rotation to complete... Waiting for multisig rotation to complete... Multisig Event Alias: multisig_group Identifier: EEyK9sCty5qBjnAmc_-2fcsW-68sHfMgpH6bzc2vO0h- Seq No: 2 Group Identifier Local Indentifier: ELPvwxEI6nEv_Imtv89jgACiDvCFlgl50Ls6UatFtLyY ✔ Fully Signed Witnesses: Count: 3 Receipts: 3 Threshold: 3 Public Keys: 1. DED9rD7Mpbtjtej7Ueyc_R6894f1hQ-YhcZtdAI0WIIn 2. DAz9zLvu7sXHI-YJVlNlS67B0A1SJJvG-MwlAsT2OOhF Multisig Join Waiting for group multisig events... Group Multisig Rotation proposed: Signing Members +-------+--------------+----------------------------------------------+-----------+ | Local | Name | AID | Threshold | +-------+--------------+----------------------------------------------+-----------+ | | party1_alias | ELPvwxEI6nEv_Imtv89jgACiDvCFlgl50Ls6UatFtLyY | 1/2 | | * | party2_alias | EOZIXcOdHPFkSEN_85QbeFC4GKo4nVqVx70RuDug-jBB | 1/2 | +-------+--------------+----------------------------------------------+-----------+ Rotation Members +-------+--------------+----------------------------------------------+-----------+ | Local | Name | AID | Threshold | +-------+--------------+----------------------------------------------+-----------+ | | party1_alias | ELPvwxEI6nEv_Imtv89jgACiDvCFlgl50Ls6UatFtLyY | 1/2 | | * | party2_alias | EOZIXcOdHPFkSEN_85QbeFC4GKo4nVqVx70RuDug-jBB | 1/2 | +-------+--------------+----------------------------------------------+-----------+ Configuration: +-------------------+-------+ | Name | Value | +-------------------+-------+ | Witness Threshold | 3 | +-------------------+-------+ Alias: multisig_group Identifier: EEyK9sCty5qBjnAmc_-2fcsW-68sHfMgpH6bzc2vO0h- Seq No: 2 Group Identifier Local Indentifier: EOZIXcOdHPFkSEN_85QbeFC4GKo4nVqVx70RuDug-jBB ✔ Fully Signed Witnesses: Count: 3 Receipts: 3 Threshold: 3 Public Keys: 1. DED9rD7Mpbtjtej7Ueyc_R6894f1hQ-YhcZtdAI0WIIn 2. DAz9zLvu7sXHI-YJVlNlS67B0A1SJJvG-MwlAsT2OOhF You can continue ✅ ### Verifiying rotation event Let's inspect the KEL of `multisig_group` one last time. The `rot` event (type `rot`) is an establishment event that signifies a change in the controlling keys. - `s`: The sequence number is incremented. - `p`: Contains the digest of the previous event (the ixn event in this case). - `kt`: The signing threshold for this rotation. It's now a list `["1/2", "1/2"]`, reflecting the weighted threshold specified. - `k`: The list of public keys of the participants that are now the current authoritative signers for the group. These are the new keys from the individual participant rotations. - `nt`: The signing threshold for the next rotation (pre-rotation). - `n`: A list of digests of the public keys for the next rotation. - `br`: List of witnesses to remove (empty in this case). - `ba`: List of witnesses to add (empty in this case). This `rot` event demonstrates how the control of the multisig group AID has been transferred to a new set of keys (derived from the participants' new keys) and how a new pre-rotation commitment has been made for the next cycle, all while maintaining the integrity of the KEL through cryptographic chaining and multi-signature authorization. ```python pr_title(f"Multisig AID status") !kli status --name party1_keystore --alias multisig_group --verbose ``` Multisig AID status Alias: multisig_group Identifier: EEyK9sCty5qBjnAmc_-2fcsW-68sHfMgpH6bzc2vO0h- Seq No: 2 Group Identifier Local Indentifier: ELPvwxEI6nEv_Imtv89jgACiDvCFlgl50Ls6UatFtLyY ✔ Fully Signed Witnesses: Count: 3 Receipts: 3 Threshold: 3 Public Keys: 1. DED9rD7Mpbtjtej7Ueyc_R6894f1hQ-YhcZtdAI0WIIn 2. DAz9zLvu7sXHI-YJVlNlS67B0A1SJJvG-MwlAsT2OOhF Witnesses: 1. BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha 2. BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM 3. BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX { "v": "KERI10JSON000215_", "t": "icp", "d": "EEyK9sCty5qBjnAmc_-2fcsW-68sHfMgpH6bzc2vO0h-", "i": "EEyK9sCty5qBjnAmc_-2fcsW-68sHfMgpH6bzc2vO0h-", "s": "0", "kt": "2", "k": [ "DOKTEjSCgBNZLr62VaTUbQh1dpP7n6KUaIfZhak-aaXU", "DDyva00Vg_tIbK9V15XiIodr0tS3JDLqQvQC23DTp-h6" ], "nt": "2", "n": [ "EDsRlPLnlcvZZVv-T1GoEZE5x0_QtRpSoSiAOurMmLz9", "EG-jLWaS8gE9wuPCArQk_81XZkr-x3WWHuFNYt_LpZXE" ], "bt": "2", "b": [ "BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha", "BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM", "BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX" ], "c": [], "a": [] } { "v": "KERI10JSON0000e1_", "t": "ixn", "d": "ECFIsW1NE0jI3kd576KmSMSDqf4E_Z74Si1G9I6OdMrZ", "i": "EEyK9sCty5qBjnAmc_-2fcsW-68sHfMgpH6bzc2vO0h-", "s": "1", "p": "EEyK9sCty5qBjnAmc_-2fcsW-68sHfMgpH6bzc2vO0h-", "a": [ { "d": "arbitrary data" } ] } { "v": "KERI10JSON0001d2_", "t": "rot", "d": "EO2DzHkdFWFIkkwlmowdxKBDteybwf020WVgnofejPn6", "i": "EEyK9sCty5qBjnAmc_-2fcsW-68sHfMgpH6bzc2vO0h-", "s": "2", "p": "ECFIsW1NE0jI3kd576KmSMSDqf4E_Z74Si1G9I6OdMrZ", "kt": [ "1/2", "1/2" ], "k": [ "DED9rD7Mpbtjtej7Ueyc_R6894f1hQ-YhcZtdAI0WIIn", "DAz9zLvu7sXHI-YJVlNlS67B0A1SJJvG-MwlAsT2OOhF" ], "nt": [ "1/2", "1/2" ], "n": [ "EL3IL5wyj5koej_0Fcq1ZtVEDJR7ju5RDAUcIE2SZmrn", "EBzqFJ1sxQx9f-H9XgnhXhhN-9dN2SFaiY2NINiknoVl" ], "bt": "3", "br": [], "ba": [], "a": [] }
📝 SUMMARY
---
This notebook demonstrated the creation and management of a multi-signature (multisig) group AID in KERI.
• Participant Setup: Individual AIDs for each participant were created and their mailboxes configured for discovery via OOBIs.
• Group Configuration: A JSON file defined the participating AIDs, witness set, TOAD, and signing thresholds (isith, nsith) for the group.
• Group Inception (icp): The multisig group AID was incepted cooperatively using kli multisig incept by one participant and kli multisig join by the other(s). The resulting icp event in the group's KEL lists the participants' public keys (k) and the signing threshold (kt).
• Group Interaction (ixn): An interaction event was performed by the group, requiring signatures from the participants according to the current threshold. The ixn event anchored data to the group's KEL.
• Group Rotation (rot):
  • Individual participant AIDs first rotated their own keys.
  • The multisig group AID then performed a rotation using kli multisig rotate and kli multisig join. This involved specifying the new set of signing members (--smids), the pre-rotated members for the next rotation (--rmids), and potentially new signing thresholds (--isith, --nsith), which can include weighted schemes.
  • The rot event in the group's KEL updated the list of authoritative keys (k), the signing threshold (kt), and the pre-rotation commitment (n, nt).
Throughout this process, KERI's cryptographic chaining and signature verification ensure the integrity and authenticity of the multisig group's key events.
[<- Prev (Delegated AIDs)](101_47_Delegated_AIDs.ipynb) | [Next (ACDC) ->](101_50_ACDC.ipynb) # Understanding ACDCs: Authentic Chained Data Containers
🎯 OBJECTIVE
---
Introduces the concept of Authentic Chained Data Containers (ACDCs). Explore what they are, their basic structure, how they are connected to key event logs (KELs), and why they are a secure way to share information.
## Defining ACDCs In KERI, verifiable claims are exchanged using **Authentic Chained Data Containers**, **ACDCs** for short. An ACDC is like a digital envelope that's been cryptographically sealed and tied to the key event log (KEL) of an identity. You can put data inside (like a name, an authorization, or a membership status), and the seal guarantees who created it and that the contents haven't been tampered with since it was sealed. The tie to the KEL of an AID, also known as an anchor or anchoring, provides the cryptographic verifiability and authenticity (who) for a credential. A feature of ACDCs is that they allow different parties (represented by their AIDs) to securely share and verify pieces of information or claims about themselves or others. They are KERI's secure implementation of the broader concept of Verifiable Credentials (VCs).
ℹ️ NOTE: We don't sign credentials, and you shouldn't either!

---

The security model of an ACDC is provided by a tie to a key event in a key event log, also known as a seal. This seal is then placed in a key event, whether an interaction or rotation event, in a process called "anchoring."

What this means is that ACDCs are not signed directly, rather the seal is signed, and the seal that anchors the ACDC to a particular key event provides the cryptographic verifiability for that ACDC. Critically, this seal allows verification of the ACDC even after rotating the keys of the underlying identifier that issued the ACDC.

In fact, signing an ACDC would not be terribly useful because a signature of an ACDC that is not anchored to a KEL would only be useful until the keys of the underlying signing identifier were rotated. This means that a bare signature of an ACDC would not, on its own, provide a secure, reproducible verification of that ACDC because it is missing a key index and thus, when the underlying issuing identifier rotates keys, would become unverifiable, assuming that the verifier always demands the use of the most current keys for an issuer that it knows about.

If this doesn't make a lot of sense yet that's okay. The note is included here for reference and to stimluate your thinking and further questioning.

## SAIDs: Self-Addressing Identifiers ACDCs rely on the concept of **Self-Addressing Identifiers (SAIDs)** to create identifiers for data. The SAID is generated by hashing the content it represents, after placing '###' characters as a placeholder for the SAID attribute in the data, and finally embedding the SAID within the data it is a digest of, making the data and its identifier mutually tamper-evident. SAIDs are a crucial part of ACDCs and will be presented later in the definition of credential schemas. ## ACDC Structure: Envelope and Payload Conceptually, an ACDC has two parts, the envelope and the payload. Both are shown together in the following example of a vLEI QVI credential. ### Sample ACDC - a QVI credential This sort of credential is issued to an organization who has been approved to issue vLEI credentials. In this example the rule attributes are abbreviated. ```json { "v": "ACDC10JSON000521_", "d": "EAj8mVqmr-mb6_sSagoy-GwEQdBlkPUHVkXjilAFBe1p", "i": "EN6zbvE2f8-FWP9bcYOknYXnZrCnmMS6Ot2ctYEtXIV7", "ri": "EBYWGQLsUB1q1MaD5Ub9eVP10LIk071FoxSvZPYyKVDu", "s": "EBfdlu8R27Fbx-ehrqwImnK-8Cm79sqbAQ4MmvEAYqao", "a": { "d": "EEaFWpwcg78La7agmlpklLlNADl4emfS9J71WFIxId8W", "i": "EOc_QXByf6e-4_q80tG4Kay-MOw2GYqkbiifvepIYmKi", "dt": "2025-06-11T21:26:59.963634+00:00", "LEI": "254900OPPU84GM83MG36" }, "r": { "d": "EDIai3Wkd-Z_4cezz9nYEcCK3KNH5saLvZoS_84JL6NU", "usageDisclaimer": { "l": "Usage of a valid, unexpired, and non-revoked vLEI Credential..." }, "issuanceDisclaimer": { "l": "All information in a valid, unexpired, and non-revoked..." } } } ``` Let's break this down. ### Envelope **The Envelope** consists of a few top-level fields in the ACDC object *about* the ACDC itself. ```json { "v": "ACDC10JSON000521_", "d": "EAj8mVqmr-mb6_sSagoy-GwEQdBlkPUHVkXjilAFBe1p", "i": "EN6zbvE2f8-FWP9bcYOknYXnZrCnmMS6Ot2ctYEtXIV7", "ri": "EBYWGQLsUB1q1MaD5Ub9eVP10LIk071FoxSvZPYyKVDu", "s": "EBfdlu8R27Fbx-ehrqwImnK-8Cm79sqbAQ4MmvEAYqao", ...payload fields } ``` These fields are: * `v`: Specifies the version and serialization format (like JSON or CBOR). * `d`: The unique identifier for *this specific ACDC instance*. This is a SAID. * `i`: The AID (Autonomic Identifier) of the entity that *issued* the ACDC. * `s`: The SAID of the *Schema* that defines the structure and rules for the data inside this ACDC. ### Payload **The Payload** contains the data of the credential in three main parts. In this sample the rules attributes are abbreviated. ```json { ...metadata fields "a": { "d": "EEaFWpwcg78La7agmlpklLlNADl4emfS9J71WFIxId8W", "i": "EOc_QXByf6e-4_q80tG4Kay-MOw2GYqkbiifvepIYmKi", "dt": "2025-06-11T21:26:59.963634+00:00", "LEI": "254900OPPU84GM83MG36" }, "r": { "d": "EDIai3Wkd-Z_4cezz9nYEcCK3KNH5saLvZoS_84JL6NU", "usageDisclaimer": { "l": "Usage of a valid, unexpired, and non-revoked vLEI Credential..." }, "issuanceDisclaimer": { "l": "All information in a valid, unexpired, and non-revoked..." } } } ``` The fields are: * `a` (Attributes): The core data or claims being made (e.g., name: "Alice", role: "Admin") * `e` (Edges): Optional links to *other* ACDCs, creating verifiable chains of credentials * `r` (Rules): Optional machine-readable rules or references to legal agreements (like Ricardian Contracts) associated with the credential The example shown above does not have any edges, links to other ACDCs, and thus has no "e" section. A credential with any chain to other credentials would have edges and thus data in the "e" section. ## ACDCs Security and Verifiability ACDCs leverage KERI's core security principles to provide strong guarantees: * **Authenticity:** Every ACDC is digitally signed by its issuer (`i` field). Using the issuer's KEL (Key Event Log), anyone can verify that the issuer actually created and authorized that specific ACDC. * **Integrity:** The ACDC's own identifier (`d` field) is a SAID. This means the identifier is a cryptographic hash (digest) of the ACDC's contents. If anything in the ACDC changes (even a single character), the SAID will no longer match, proving it has been tampered with. * **Schema Verification:** The schema defining the ACDC's structure is also identified by a SAID (`s` field). This ensures that everyone agrees on the structure and rules the credential must follow, and that the schema itself hasn't been tampered with. * **End-Verifiability:** Like all things in KERI, ACDCs are designed to be verifiable by anyone who receives them, relying only on the ACDC itself and the issuer's KEL, without needing to trust intermediaries. These features make ACDCs a robust foundation for building trustable digital interactions, from simple claims to complex authorization workflows. Now that you understand the basic concept of an ACDC, the next step is to learn how to define its structure using **schemas**. In the next notebook, we'll dive into creating ACDC schemas and making them verifiable with SAIDs. ## How an ACDC is Connected to an AID An ACDC connects to an AID by anchoring events from a transaction event log, a TEL, for the creation of the registry a credential is issued from as well as the issuance of the credential itself. This is shown in the below diagram.  ### Connecting regstries and ACDCs to the KEL First, before issuing an ACDC the issuer must create an ACDC registry. Since each ACDC has a reference back to the registry the ACDC was issued from then the registry must exist first. Following registry creation the issuer may issue credentials as shown in the diagram above. Transaction Event Logs (TELs) are used to anchor both registries and ACDCs to a KEL. This process is called "anchoring" and provides cryptographic verifiability to the registry and any ACDCs issued. ### ACDC Registries and its Anchor This registry will have a SAID identifier like `ELh3eYC2W_Su1izlvm0xxw01n3XK8bdV2Zb09IqlXB7A` like is shown in the below registry inception event, a `vcp` event. The below example shows both a registry creation event (`vcp` for verifiable registry inception) and its anchoring seal, the CESR event stream that looks like `-GAB0AAAAAAAAAAAAAAAAAAAAABwEOWdT7a7fZwRz0jiZ0DJxZEM3vsNbLDPEUk-ODnif3O0`. The CESR stream below is spaced out and annotated for readability. All cryptographic signatures in KERI and ACDC are expressed as CESR streams. ```json { "v" : "KERI10JSON00011c_", "i" : "ELh3eYC2W_Su1izlvm0xxw01n3XK8bdV2Zb09IqlXB7A", "ii": "EJJR2nmwyYAfSVPzhzS6b5CMZAoTNZH3ULvaU6Z-i0d8", "s" : "0", "t" : "vcp", "b" : ["BbIg_3-11d3PYxSInLN-Q9_T2axD6kkXd3XRgbGZTm6s"], "c" : [] "a" : { "d": "EEBp64Aw2rsjdJpAR0e2qCq3jX7q7gLld3LjAwZgaLXU" } } -GAB # CESR attachment group code for the TEL anchor 0AAAAAAAAAAAAAAAAAAAAABw # KEL seq. no. of the anchoring interaction event. All 'A's = 0 in Base64, the first 'B' means "1". EOWdT7a7fZwRz0jiZ0DJxZEM3vsNbLDPEUk-ODnif3O0 # SAID of KEL event anchroing this "vcp" event. ``` ### ACDC Issuance and its Anchor An issuance in a TEL includes the digest of the ACDC that was issued in the "i" field and also points to the registry the ACDC was issued from in the "ri" field, what [will become](https://trustoverip.github.io/tswg-acdc-specification/#top-level-fields) the "rd" field. ```json { "v" : "KERI10JSON00011c_", "i" : "Ezpq06UecHwzy-K9FpNoRxCJp2wIGM9u2Edk-PLMZ1H4", "s" : "0", "t" : "iss", "dt": "2021-05-27T19:16:50.750302+00:00", "ri": "ELh3eYC2W_Su1izlvm0xxw01n3XK8bdV2Zb09IqlXB7A" } -GAB 0AAAAAAAAAAAAAAAAAAAAAAw ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM ``` ### ACDC Revocation and its Anchor Somewhat different from an issuance, the TEL event for a revocation points back to the "iss" issuance event with the "p" property, to the ACDC with the "i", property, and contains a date and timestamp for when the revocation occurred. ```json { "v" : "KERI10JSON00011c_", "i" : "Ezpq06UecHwzy-K9FpNoRxCJp2wIGM9u2Edk-PLMZ1H4", "s" : "1", "t" : "rev", "dt": "2021-05-27T19:16:50.750302+00:00", "p" : "EY2L3ycqK9645aEeQKP941xojSiuiHsw4Y6yTW-PmsBg" } -GAB 0AAAAAAAAAAAAAAAAAAAAABA ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM ```
📝 SUMMARY
---
Authentic Chained Data Containers (ACDCs) are KERI's version of verifiable credentials, acting as cryptographically sealed envelopes for sharing verifiable claims. They rely on Self-Addressing Identifiers (SAIDs)—unique IDs derived from the content itself—to ensure integrity. In order to issue an ACDC a registry must be created. Both the creation of a registry and the creation of an ACDC involve creation of separate transaction event logs (TELs). A registry has its own TEL to record when the registry was created and the changing of any registry backers. Each ACDC has its own TEL to record the issuance and revocation state of the ACDC.

An ACDC consists of an 'Envelope' with metadata (like version v, its own SAID d, issuer AID i, and schema SAID s) and a 'Payload' containing the actual data (attributes a), optional links to other ACDCs (edges e), and optional rules (r). ACDCs provide authenticity via the issuer's signature, integrity through their SAID, schema verification via the schema's SAID, and are end-verifiable using the issuer's KEL.
[<- Prev (Multisignature Identifiers)](101_48_Multisignature_Identifiers.ipynb) | [Next (Schemas) ->](101_55_Schemas.ipynb) # ACDC Schemas: Defining Verifiable Structures
🎯 OBJECTIVE
---
Explain the role of schemas in defining ACDC structures, how they leverage Self-Addressing Identifiers (SAIDs) for verifiability, discover the structure of an ACDC schema, and learn how to create and process a basic schema. Understand that ACDCs are ordered field maps which means that order of attributes in any produced JSON must use a deterministic order that is canonically defined in the JSON schema.

## Purpose of Schemas Before we can issue or verify an Authentic Chained Data Container (ACDC) we need a blueprint that describes exactly what information it should contain and how that information should be structured. This blueprint is called a **Schema**. Schemas serve several purposes: * **Structure and Validation:** They define the names, data types, and constraints for the data within an ACDC. This allows recipients to validate that a received ACDC contains the expected information in the correct format. * **Interoperability:** When different parties agree on a common schema, they can reliably exchange and understand ACDCs for a specific purpose (e.g., everyone knows what fields to expect in a "Membership Card" ACDC). * **Verifiability:** As we'll see, ACDC schemas themselves are cryptographically verifiable, ensuring the blueprint hasn't been tampered with.
🔒 Security Note
---
Security is a major reason why ACDC schemas are necessary and also why ACDC schemas must be immutable. Using immutable schemas to describe all ACDCs prevents any type of malleability attack and ensures that recipients always know precisely the kind of data to expect from an ACDC.
### Ordering of attributes It is essential to understand that ACDCs are **ordered field maps**, which means that the order in which fields appear in the JSON of an ACDC must be specific and deterministic. This design constraint is non-existent in much of the Javascript world and many other credential formats, and its an essential part of what makes ACDC secure. A deterministic ordering of fields must be used in order to enable cryptographic verifiability. A non-deterministic field order would mean digest (hashing) verification would fail because attribute order would be unpredictable. So, while initially seeming inconvenient, the ordered field maps provide predictability and cryptographic verifiability.
🔒 Security Note
---
It also happens that using ordered field maps protects against data malleability attacks. If strict insertion order was not preserved or required then an attacker could inject JSON into an ACDC being shared and possibly cause undefined, unknown, or unintended behavior for the recipient of an ACDC.
#### Canonical ordering of ACDC attributes This order is set by the JSON schema document, as in the **canonical ordering** of data attributes in an ACDC is defined by the JSON schema document, **not lexicographical order**. Admittedly, ordering of attributes in JSON is not yet standard practice in the JSON and Javascript worlds, yet is essential from a security perspective. ##### Python and ordered dicts Also, as of Python 3.7 the [`json`](https://docs.python.org/3/library/json.html) built-in package preserves input (insertion) and output order of `dict` structs used for JSON serialization and deserialization, meaning insertion order is preserved. ##### Javascript and ordered Maps As of ECMAScript 2015 the [Map implementation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map), used for JSON serialization and deserialization, uses insertion order to create a predictable ordering of fields, meaning any modern Javascript implementation will preserve insertion order. #### Other languages If you use a different language implementation of KERI, ACDC, or CESR then you must ensure it preserves insertion order of attributes for ACDC validation to succeed.
⚠️ Validation Warning
---
ACDCs must have ordered field maps in order to be reliably verifiable. Any change to the order of fields that is not also consistent with the schema will result in a validation failure.
## Writing ACDC Schemas ACDC schemas are written using the **JSON Schema** specification. If you're familiar with JSON Schema, you'll find ACDC schemas very similar, with a few KERI-specific conventions. The main parts of a typical ACDC schema include metadata, properties, metadata of the properties, attributes, edges, and rules. Each of these main parts are previewed below in an abbreviated schema document. ### Sample Schema for an ACDC As a demonstration the below schema is titled "Sample Schema" which is a label of the type of credential that this schema describes. This particular schema does not have any edges, the "e" section, or rules, the "r" section. An upcoming training will explore those sections. Whitespace below was added for readability. Actual JSON Schemas use no extra whitespace. ```json { "$id" : "EJgBEKtba5ewUgG3k268YadY2eGBRrsVF6fF6tLyoRni", "$schema" : "http://json-schema.org/draft-07/schema#", "title" : "Sample Schema", "description" : "A very basic credential schema for demonstration.", "type" : "object", "credentialType": "SampleCredential", "version": "1.0.0", "properties": { "v" : {...}, "d" : {...}, "u" : {...}, "i" : {...}, "ri": {...}, "s" : {...}, "a" : {...} }, "additionalProperties": false, "required": ["v","d","i","ri","s","a"] } ``` #### Schema Metadata (Top Level) These attributes describes the schema document itself. * `$id`: This field holds the SAID of the entire schema file once processed. It's not a URL like in standard JSON Schema. It's computed after all internal SAIDs are calculated. * `$schema`: Specifies the JSON Schema version (e.g., `"http://json-schema.org/draft-07/schema#"`) * `title`, `description`: Human-readable name and explanation * `type`: Usually `"object"` for the top level of an ACDC schema * `credentialType`: A specific name for this type of credential * `version`: A semantic version for this specific credential type (e.g., `"1.0.0"`) to manage schema evolution (Distinct from the ACDC instance's `v` field). * `additionalProperties`: Controls whether the ACDC may have extra properties in addition to what is defined in the JSON Schema. The default is true. If false then adding any properties beyond those defined in the schema will cause a validation error. * `required`: declares the attributes of the "properties" section that must have data values defined in the ACDC. If any of the required properties are missing in the resulting ACDC JSON, then validation will fail. #### `properties` section (Top Level) Inside the top level "properties" attribute there are two groups of fields including ACDC metadata and ACDC data attributes (payload). These fields define what appears in the ACDC's envelope and payload. ```json { ... "properties": { "v": {"description": "Credential Version String","type": "string"}, "d": {"description": "Credential SAID", "type": "string"}, "u": {"description": "One time use nonce", "type": "string"}, "i": {"description": "Issuer AID", "type": "string"}, "rd": {"description": "Registry SAID", "type": "string"}, "s": {"description": "Schema SAID", "type": "string"}, "a": {...}, "e": {...}, "r": {...}, }, ... } ``` The metadata attributes include "v", "d", "u", "i", "rd", and "s" attributes. The data attributes, or ACDC payload, include the "a", "e", and "r" attributes. Each are explained below. ##### ACDC Metadata Fields The ACDC metadata fields describe data that shows up at the top level of an ACDC and describe the ACDC itself, such as who issued the credential, what schema it has, and any privacy-preserving attributes. * `v`: ACDC version/serialization - a CESR version string describing the version of the CESR and ACDC protocols used to encode this ACDC. * `d`: ACDC SAID - The self-addressing identifier (digest) of the issued ACDC. * `u`: salty nonce - an optional nonce used to blind the properties section during a privacy-preserving graduated disclosure negotiation. * `i`: Issuer AID - The AID prefix of the identifier who issued this ACDC. * `rd`: Registry SAID - Formerly the "ri" attribute; the SAID of the credential registry of the issuer who issued this ACDC. * `s`: Schema SAID - The SAID of the JSON schema document that describes the data in this ACDC and that will be used to validate the data going into or being pulled out of this ACDC. ### ACDC Properties Payload Sections The actual data stored inside of an ACDC including data attributes, chained credentials (edges), and any rules (legal language) defined for an ACDC. The reason chained credentials are stored in what is called an "edge" section is because chained ACDCs form a graph where the nodes are credentials and the edges are pointers between credential nodes in the graph. ```json { ... "properties": { ... "a": {...}, "e": {...}, "r": {...}, }, ... } ``` * `a`: Defines the structure for the **attributes block**, which holds the actual data or claims being made by the credential. * `e`: Defines any links to chained credentials, known as edges. * `r`: Defines any legal rules for a credential such as a terms of service or a legal disclaimer for a credential. This is where **Ricardian Contracts** enter in to an ACDC. The attribute section is where most of the action happens and is typically the largest section of a credential. We break it down next. #### ACDC Attributes Payload Section The "a" or attributes section of an ACDC payload is where the data for a credential is stored. This data may be stored in one of two ways, in the "compacted" and blinded form as a SAID, or in the "un-compacted" form where the data attribute names and values are un-blinded and visible. The blinding and un-blinding process are used to control negotiation of information disclosure during the graduated disclosure process, ACDC's form of selective disclosure. ```json { ... "properties": { ... "a": { "oneOf": [ { "description": "Attributes block SAID", "type": "string"}, { "$id": "ED614TseulOlXWhFNsOcKIKt9Na0gCByugqyKVsva-gl", "description": "Attributes block", "type": "object", ... } ] }, ... }, ... } ``` The attributes of the "a" section ACDC are as follows: * **`oneOf`**: This standard JSON Schema keyword indicates that the value for the `a` block in an actual ACDC instance can be *one of* the following two formats: 1. **Compacted Form (String):** * `{"description": "Attributes block SAID", "type": "string"}` * This option defines the *compact* representation. Instead of including the full attributes object, the ACDC can simply contain a single string value: the SAID of the attributes block itself. This SAID acts as a verifiable reference to the full attribute data, which might be stored elsewhere. **(We won't cover compact ACDCs in this material.)** 2. **Un-compacted Form (Object):** * `{"$id": "", "description": "Attributes block", "type": "object", ...}` * This option defines the full or un-compacted representation, where the ACDC includes the complete attributes object directly. ##### Inside an un-compacted ACDC attributes section You can easily identify an un-compacted ACDC attributes section because it has both an "$id" and a "properties" attribute where all the data is stored. A few metadata attributes go along with this. ```json { ... "properties": { ... "a": { "oneOf": [ { "$id": "ED614TseulOlXWhFNsOcKIKt9Na0gCByugqyKVsva-gl", "description": "Attributes block", "type": "object", "properties": { "d": {"description": "Attributes data SAID", "type": "string"}, "i": {"description": "Issuee AID", "type": "string"}, "dt": {"description": "Issuance date time", "type": "string", "format": "date-time"}, "claim": {"description": "The simple claim being made","type": "string"} }, "additionalProperties": false, "required": ["d","i","dt","claim"] } ] }, ... }, ... } ``` This schema describes a JSON object that looks like the following: ```json { "d": "ENSOVw2kLhPSNbCWlOir8BEB2N2NDskgBNDbx7L1qJsk", "i": "EOc_QXByf6e-4_q80tG4Kay-MOw2GYqkbiifvepIYmKi", "dt": "2025-06-11T21:29:49.537000+00:00", "claim": "some claim value" } ``` A lot of schema definition for a simple credential! Each of the attributes are defined as follows: * **`$id`**: This field will hold the SAID calculated for *this specific attributes block structure* after the schema is processed (`SAIDified`). Initially empty `""` when writing the schema. * **`description`**: Human-readable description of this block. * **`type`: `"object"`**: Specifies that this form is a JSON object. * **`properties`**: Defines the fields contained within the attributes object: * **`d`**: Holds the SAID calculated from the *actual data* within the attributes block * **`i`**: The AID of the **Issuee** or subject of the credential – the entity the claims are *about*. * **`dt`**: An ISO 8601 date-time string indicating when the credential was issued. * **`claim`** (and other custom fields): These are the specific data fields defined by your schema. In this example, `"claim"` is a string representing the custom information this credential conveys. You would define all your specific credential attributes here. * **`additionalProperties`, `required`:** Standard JSON Schema fields controlling whether extra properties are allowed and which defined properties must be present. (see the complete schema [here](config/schemas/sample_schema.bak.json))
ℹ️ NOTE
---
The ACDC schema definition allows for optional payload blocks called e (edges) and r (rules).
• The e section defines links (edges) to other ACDCs, creating verifiable chains of related credentials. For more details see edges.
• The r section allows embedding machine-readable rules or legal prose, such as Ricardian Contracts, directly into the credential. For more details see rules.
### Writing your ACDC Schema To write your schema, most of the customization will happen inside the payload attributes block (`a`). Here you can add claims according to specific needs. When you chain credentials you will use the "e" section. And when you set rules for your credentials you will use the "r" section. We get into each of these subjects in upcoming trainings. ### Full Schema Example The below sample schema illustrates a complete, sample credential that only has attributes, no edges, and no rules. Whitespace has been somewhat trimmed and in some places added for readability and conciseness. When you use JSON schemas then the formatting will significantly expand the line count of a schema beyond what is shown below. ```json { "$id": "EJgBEKtba5ewUgG3k268YadY2eGBRrsVF6fF6tLyoRni", "$schema": "http://json-schema.org/draft-07/schema#", "title": "Sample Schema", "description": "A very basic credential schema for demonstration.", "type": "object", "credentialType": "SampleCredential", "version": "1.0.0", "properties": { "v": { "description": "Credential Version String", "type": "string" }, "d": { "description": "Credential SAID", "type": "string" }, "u": { "description": "One time use nonce", "type": "string" }, "i": { "description": "Issuer AID", "type": "string" }, "ri": { "description": "Registry SAID", "type": "string" }, "s": { "description": "Schema SAID", "type": "string" }, "a": { "oneOf": [ { "description": "Attributes block SAID", "type": "string" }, { "$id": "ED614TseulOlXWhFNsOcKIKt9Na0gCByugqyKVsva-gl", "description": "Attributes block", "type": "object", "properties": { "d": { "description": "Attributes data SAID", "type": "string" }, "i": { "description": "Issuee AID", "type": "string" }, "dt": { "description": "Issuance date time", "type": "string", "format": "date-time" }, "claim": { "description": "The simple claim being made", "type": "string" } }, "additionalProperties": false, "required": [ "d", "i", "dt", "claim" ] } ] } }, "additionalProperties": false, "required": [ "v", "d", "i", "ri", "s", "a" ] } ``` If you want to see a production-grade credential schema that has both edges and rules, you may review the [GLEIF vLEI Official Organizational Role (OOR)](https://github.com/WebOfTrust/schema/blob/main/vLEI/legal-entity-official-organizational-role-vLEI-credential.schema.json) credential schema.
📝 SUMMARY
---
An ACDC Schema acts as an ordered, verifiable blueprint defining the structure, data types, rules, and canonical ordering for attributes within an Authentic Chained Data Container (ACDC). Written using the JSON Schema specification, they ensure ACDCs have the expected format (validation) and enable different parties to understand exchanged credentials (interoperability).

Key components include:
top-level metadata (like the schema's SAID in $id, title, credentialType, version)
a properties section defining the ACDC envelope fields (v, d, i, s, etc.)
a payload section. The main payload section is attributes (a), containing issuer/issuee info and custom claims, with optional sections for edges (e) linking other ACDCs, and rules (r).
**Remember**, all fields contained within an ACDC must be ordered according to **insertion order**, not lexicographic (alphabetical) order. This is essential for both cryptographic verifiability and security.
[<- Prev (ACDC)](101_50_ACDC.ipynb) | [Next (Saidify schema) ->](101_60_Saidify_schema.ipynb) # SAIDifying ACDC Schemas
🎯 OBJECTIVE
---
Explain the purpose and benefits of using Self-Addressing Identifiers (SAIDs) for ACDC schemas and demonstrate the practical, recursive process of calculating and embedding these SAIDs into an ACDC schema file ("SAIDifying").
## Role of Schema SAIDs A key feature of KERI and ACDCs is the use of SAIDs (Self-Addressing Identifiers) for schemas. The SAID in a schema's `$id` field is a digest of the canonical form of that schema block. Why it matters: - **Lookup:** SAIDs provide a universal, unique identifier to retrieve a specific, verified version of a schema. - **Immutability:** Once a schema version is SAIDified and published, it's cryptographically locked. New versions require a new SAID. - **Integrity:** If anyone modifies the schema file after its SAID has been calculated and embedded, the SAID will no longer match the content, making tampering evident. Calculating and embedding these SAIDs requires a specific process, often called **"SAIDifying"**. This involves calculating the SAIDs for the innermost blocks (like attributes, edges, rules) first, embedding them, and then calculating the SAID for the next level up, until the top-level schema SAID is computed. ## The SAIDification Process We have provided a sample schema and a utility function to help you SAIDfy the schema. Here are the steps. ### Step 1: Write Schema JSON First, you will create a JSON file with the basic structure as seen in the previous notebook. Since we provide the schema, you don't need to worry about it. But review the file **[sample_credential_schema.json](config/schemas/sample_schema.bak.json)**, since it is the schema you will use, initially unprocessed. Notice the `$id` fields are initially empty strings `""`. ### Step 2: Process and Embed SAIDs Now, you need to process the schema to embed the Self-Addressing Identifiers (SAIDs). For this, we use the provided **[Python script](scripts/saidify.py)** available in the scripts folder. It calculates the required digests from the content and adds the SAIDs to the file. ```python from scripts.saidify import process_schema_file # Run the saidify script process_schema_file("./config/schemas/sample_schema.bak.json", "./config/schemas/sample_schema.json", True) # Displays all "$id" values from any JSON objects found recursively in the schema file print("\ncalculated saids ($id):") !jq '.. | objects | .["$id"]? // empty' ./config/schemas/sample_schema.json ``` Successfully wrote processed data to ./config/schemas/sample_schema.json calculated saids ($id): "EJgBEKtba5ewUgG3k268YadY2eGBRrsVF6fF6tLyoRni" "ED614TseulOlXWhFNsOcKIKt9Na0gCByugqyKVsva-gl" After running this command, if you inspect output **[sample_credential_schema.json](config/schemas/sample_schema.json)**, you will see that the previously empty `"id": ""` fields (both the top-level one and the one inside the a block) have been populated with SAID strings (long Base64-like identifiers). You now have a cryptographically verifiable schema identified by its top-level SAID!
💡 TIP
---
The KERI command-line tool (`kli`) provides the kli saidify command. When used like kli saidify --file <filename> --label '<label>', it calculates a SAID for the specified file content and can embed it into the field matching the label (e.g., "$id" at the top level).

However, automatically processing nested structures and dependencies within complex ACDC schemas typically requires helper tools or custom scripts to ensure all inner SAIDs are calculated and embedded correctly before the final outer SAID is generated.
## Making Schemas Discoverable For an issuer to issue an ACDC using this schema, and for a recipient/verifier to validate it, they need access to this exact, SAIDified schema definition. How do they get it? The SAID acts as a universal lookup key. Common ways to make schemas available include: - Simple Web Server: Host the SAIDified JSON file on a basic web server. Controllers can be configured (often via OOBIs, covered later) to fetch the schema from that URL using its SAID.   - Content-Addressable Network: Store the schema on a network like IPFS, where the SAID naturally aligns with the content digest used for retrieval. - Direct Exchange: For specific interactions, the schema could potentially be exchanged directly between parties (though less common for widely used schemas). The key point is that the schema, identified by its SAID, must be retrievable by parties needing to issue or verify credentials based on it. In the next notebook, we'll use our SAIDified schema to set up a Credential Registry and issue our first actual ACDC.
📝 SUMMARY
---
KERI uses Self-Addressing Identifiers (SAIDs) as unique, verifiable identifiers for ACDC schemas, embedded in the $id field. A schema's SAID is a cryptographic digest of its content, guaranteeing integrity (tamper-evidence) and immutability (specific to that version). This process, called "SAIDifying," involves calculating and embedding SAIDs recursively from inner blocks outwards. Practically, tools or scripts (like the example process_schema_file or kli saidify) are used to populate the initially empty $id fields in the schema JSON. Once SAIDified, the schema must be accessible (e.g., hosted on a server) so others can retrieve and verify it using its SAID.
[<- Prev (Schemas)](101_55_Schemas.ipynb) | [Next (ACDC Issuance) ->](101_65_ACDC_Issuance.ipynb) # ACDC Issuance with KLI: Using the IPEX Protocol
🎯 OBJECTIVE
---
Demonstrate the process of issuing an Authentic Chained Data Container (ACDC), also known as a Verifiable Credential (VC), from an Issuer to a Holder using the Issuance and Presentation Exchange (IPEX) protocol.
## Prerequisites: Issuer and Holder Setup Authentic Chained Data Containers (ACDCs) are KERI's implementation of verifiable credentials. They allow entities (controllers) to issue cryptographically verifiable statements (credentials) about subjects (often other controllers) according to predefined structures (schemas). These credentials can then be presented to verifiers to prove claims. This notebook focuses on the issuance part of the workflow: how an Issuer creates an ACDC and securely delivers it to a Holder. We will use the Issuance and Presentation Exchange (IPEX) protocol, which defines a standard way to handle the offering and acceptance of ACDCs between KERI controllers. Before any credential issuance can happen, both the entity that will issue the credential (the Issuer) and the entity that will receive it (the Holder) need to have their own KERI Autonomic Identifiers established. This involves initializing their respective keystores and creating their AIDs. ### Holder AID Setup This should be familiar by now; you initialize a keystore and incept the AID for the holder of the credential.
ℹ️ NOTE: The exec function executes a shell command within an IPython/Jupyter session and returns its output as a string. This is useful for assigning output values to variables for later use.
```python from scripts.utils import exec from scripts.utils import clear_keri clear_keri() holder_keystore_name = "holder_ks" holder_keystore_passcode = exec("kli passcode generate") holder_keystore_salt = exec("kli salt") # Alias for our non-transferable AID holder_aid = "holder_aid" # Initialize the keystore !kli init --name {holder_keystore_name} --passcode {holder_keystore_passcode} --salt {holder_keystore_salt}\ --config-dir ./config \ --config-file keystore_init_config.json !kli incept --name {holder_keystore_name} --alias {holder_aid} --passcode {holder_keystore_passcode} \ --file ./config/aid_inception_config.json ``` Proceeding with deletion of '/usr/local/var/keri/' without confirmation. ✅ Successfully removed: /usr/local/var/keri/ KERI Keystore created at: /usr/local/var/keri/ks/holder_ks KERI Database created at: /usr/local/var/keri/db/holder_ks KERI Credential Store created at: /usr/local/var/keri/reg/holder_ks aeid: BHvBPC-9NFPCVZ62dVYDc-tikZXjhaR1-wY05iyFqYVK Loading 3 OOBIs... http://witness-demo:5642/oobi/BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha/controller?name=Wan&tag=witness succeeded http://witness-demo:5643/oobi/BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM/controller?name=Wes&tag=witness succeeded http://witness-demo:5644/oobi/BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX/controller?name=Wil&tag=witness succeeded Waiting for witness receipts... Prefix EPqFKtQQ8kzLxPD943ytdj6a3JcXV_IDgYGu88PWNli0 Public key 1: DF-m7fQxP0BBo68dcFs9FTB1bSyxjWN7ROOLDKCergQ- ### Issuer AID Setup Perform the same initialization and inception process for the Issuer. The Issuer is the entity that will create and sign the credential. ```python # Issuer setup issuer_keystore_name = "issuer_ks" issuer_keystore_passcode = exec("kli passcode generate") issuer_keystore_salt = exec("kli salt") # Alias for our non-transferable AID issuer_aid = "issuer_aid" # Initialize the keystore !kli init --name {issuer_keystore_name} --passcode {issuer_keystore_passcode} --salt {issuer_keystore_salt}\ --config-dir ./config \ --config-file keystore_init_config.json !kli incept --name {issuer_keystore_name} --passcode {issuer_keystore_passcode} --alias {issuer_aid} \ --file ./config/aid_inception_config.json ``` KERI Keystore created at: /usr/local/var/keri/ks/issuer_ks KERI Database created at: /usr/local/var/keri/db/issuer_ks KERI Credential Store created at: /usr/local/var/keri/reg/issuer_ks aeid: BBisjjBRgSA3zmR5u4BajDVT53zzHuCVyuzwCGk7n6Kr Loading 3 OOBIs... http://witness-demo:5642/oobi/BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha/controller?name=Wan&tag=witness succeeded http://witness-demo:5643/oobi/BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM/controller?name=Wes&tag=witness succeeded http://witness-demo:5644/oobi/BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX/controller?name=Wil&tag=witness succeeded Waiting for witness receipts... Prefix EHlIlnBBlmKA08zLU4RDuYCkVs1k7-Jqdavd52P2HQ5h Public key 1: DDV2pfRjMtXJiHWatJdEeI_CCjV7mhwGz0PK4DOWCS5p ### Establishing Issuer-Holder Connection (OOBI) For the Issuer to send a credential to the Holder, they first need to discover each other's key state (KEL - Key Event Log). This is done using Out-of-Band Introductions (OOBIs) using witness URLs. This works because a controller's witness maintains a copy of the controller's KEL that may be retrieved by other controllers. Each controller generates an OOBI URL pointing to one of its witnesses. They then exchange these OOBIs (typically through a separate channel, hence "out-of-band") and resolve them. Resolving an OOBI allows a controller to securely fetch and verify the KEL of the other controller via the specified witness.   For brevity we skip the challenge/response step which may be used to further authenticate each controller's possession of the private keys associated with their AIDs. ```python holder_oobi_gen = f"kli oobi generate --name {holder_keystore_name} --alias {holder_aid} --passcode {holder_keystore_passcode} --role witness" holder_oobi = exec(holder_oobi_gen) issuer_oobi_gen = f"kli oobi generate --name {issuer_keystore_name} --alias {issuer_aid} --passcode {issuer_keystore_passcode} --role witness" issuer_oobi = exec(issuer_oobi_gen) !kli oobi resolve --name {holder_keystore_name} --passcode {holder_keystore_passcode} --oobi-alias {issuer_aid} \ --oobi {issuer_oobi} !kli oobi resolve --name {issuer_keystore_name} --passcode {issuer_keystore_passcode} --oobi-alias {holder_aid}\ --oobi {holder_oobi} ``` http://witness-demo:5642/oobi/EHlIlnBBlmKA08zLU4RDuYCkVs1k7-Jqdavd52P2HQ5h/witness resolved http://witness-demo:5642/oobi/EPqFKtQQ8kzLxPD943ytdj6a3JcXV_IDgYGu88PWNli0/witness resolved ### Creating the Issuer's Credential Registry To issue ACDCs, the Issuer needs a Credential Registry. Think of this as a dedicated log, managed by the Issuer's AID, specifically for tracking the status (like issuance and revocation) of the credentials it manages. The registry itself has an identifier (a SAID, derived from its inception event) and its history is maintained in a Transaction Event Log (TEL). Anchoring events from the TEL into the Issuer's main KEL ensures the registry's state changes are secured by the Issuer's controlling keys.   Use `kli vc registry incept` to create a new registry named `issuer_registry` controlled by the Issuer's AID (issuer_aid). ```python issuer_registry_name="issuer_registry" !kli vc registry incept --name {issuer_keystore_name} \ --passcode {issuer_keystore_passcode} \ --alias {issuer_aid} \ --registry-name {issuer_registry_name} ``` Waiting for TEL event witness receipts Sending TEL events to witnesses Registry: issuer_registry(EEmDzzrlo010uNzZTBcP7aAIH01Dg4ADVWjGFucPe4Oj) created for Identifier Prefix: EHlIlnBBlmKA08zLU4RDuYCkVs1k7-Jqdavd52P2HQ5h To query the status of a registry, use the command `kli vc registry status`. This shows the registry's SAID, its current sequence number (how many events have occurred in its TEL), and the controlling AID. ```python !kli vc registry status --name {issuer_keystore_name} \ --passcode {issuer_keystore_passcode} \ --registry-name {issuer_registry_name} ``` Registry: EEmDzzrlo010uNzZTBcP7aAIH01Dg4ADVWjGFucPe4Oj Seq No. 0 Controlling Identifier: EHlIlnBBlmKA08zLU4RDuYCkVs1k7-Jqdavd52P2HQ5h Backers: Not supported Events: Interaction Allowed ## Schema preparation As seen before, you need a schema to issue credentials. A schema defines the structure and data types for a specific kind of credential, ensuring consistency and enabling automated validation. For this example, we have prepared a schema to simulate an access pass for a GLEIF Summit event. It defines the expected attributes for such a pass ```json "eventName": { "description": "The event name", "type": "string" }, "accessLevel": { "description": "staff/speaker/attendee", "type": "string", "enum": [ "staff", "speaker", "attendee" ] }, "validDate": { "description": "Valid date yyyy-mm-dd", "type": "string" } ``` To see the full schema, click **[here](config/schemas/event_pass_schema.bak.json)**. ### SAIDifying the Credential Schema You might notice the **[schema file](config/schemas/event_pass_schema.bak.json)** doesn't yet have SAIDs embedded within it. As done before, use the helper script to perform this process, taking the `event_pass_schema.bak.json` file as input and outputting the SAIDified version to `event_pass_schema.json`. Additionally, capture the top-level SAID of the schema using the function `get_schema_said` ```python # Imports and Utility functions from scripts.saidify import process_schema_file, get_schema_said process_schema_file("config/schemas/event_pass_schema.bak.json", "config/schemas/event_pass_schema.json") schema_said = get_schema_said("config/schemas/event_pass_schema.json") print(schema_said) ``` Successfully wrote processed data to config/schemas/event_pass_schema.json EGUPiCVO73M9worPwR3PfThAtC0AJnH5ZgwsXf6TzbVK You can view the complete, SAIDified schema definition **[here](config/schemas/event_pass_schema.json)**. Notice the `$id` fields are now populated with SAIDs. ### Making the Schema Discoverable After the schema has been SAIDified, it needs to be made available so that any party needing it (like the Issuer and Holder) can retrieve and verify it. In KERI, discovery often happens via OOBIs. For this tutorial, we use a simple service called **vLEI-server**, which acts as a basic schema cache. It's essentially an HTTP file server pre-loaded with the SAIDified schema. It exposes an OOBI URL endpoint for each schema it holds, allowing controllers to resolve the schema using its SAID. This has already been prepared, so you can query the schema directly from the vLEI-server using its SAID via a simple HTTP request. ```python !curl -s http://vlei-server:7723/oobi/{schema_said} ``` {"$id":"EGUPiCVO73M9worPwR3PfThAtC0AJnH5ZgwsXf6TzbVK","$schema":"http://json-schema.org/draft-07/schema#","title":"EventPass","description":"Event Pass Schema","type":"object","credentialType":"EventPassCred","version":"1.0.0","properties":{"v":{"description":"Credential Version String","type":"string"},"d":{"description":"Credential SAID","type":"string"},"u":{"description":"One time use nonce","type":"string"},"i":{"description":"Issuer AID","type":"string"},"ri":{"description":"Registry SAID","type":"string"},"s":{"description":"Schema SAID","type":"string"},"a":{"oneOf":[{"description":"Attributes block SAID","type":"string"},{"$id":"ELppbffpWEM-uufl6qpVTcN6LoZS2A69UN4Ddrtr_JqE","description":"Attributes block","type":"object","properties":{"d":{"description":"Attributes data SAID","type":"string"},"i":{"description":"Issuee AID","type":"string"},"dt":{"description":"Issuance date time","type":"string","format":"date-time"},"eventName":{"description":"The event name","type":"string"},"accessLevel":{"description":"staff/speaker/attendee","type":"string","enum":["staff","speaker","attendee"]},"validDate":{"description":"Valid date yyyy-mm-dd","type":"string"}},"additionalProperties":false,"required":["d","i","dt","eventName","accessLevel","validDate"]}]}},"additionalProperties":false,"required":["v","d","i","ri","s","a"]} ### Resolving the Schema OOBI Both the Issuer and the Holder need to know the schema definition to understand the structure of the credential being issued/received. They achieve this by resolving the schema's OOBI URL provided by the `vLEI-server`. ```python schema_oobi_alias = "schema_oobi" schema_oobi = f"http://vlei-server:7723/oobi/{schema_said}" !kli oobi resolve --name {holder_keystore_name} --passcode {holder_keystore_passcode} --oobi-alias {schema_oobi_alias} \ --oobi {schema_oobi} !kli oobi resolve --name {issuer_keystore_name} --passcode {issuer_keystore_passcode} --oobi-alias {schema_oobi_alias}\ --oobi {schema_oobi} ``` http://vlei-server:7723/oobi/EGUPiCVO73M9worPwR3PfThAtC0AJnH5ZgwsXf6TzbVK resolved http://vlei-server:7723/oobi/EGUPiCVO73M9worPwR3PfThAtC0AJnH5ZgwsXf6TzbVK resolved ## Credential Creation Process With the Issuer and Holder identities established, connected via OOBI, the Issuer registry created, and the schema SAIDified and resolved, we are now ready to actually create the credential. ### Step 1: Defining Credential Attributes To create a specific credential instance, you must provide the actual values for the attributes defined in the schema (eventName, accessLevel, validDate). These values are typically provided in a separate data file (e.g., JSON), which is then referenced by the `kli vc create command`. Here's the data for the specific event pass we're issuing: ```python !cat config/credential_data/event_pass_cred_data.json ``` { "eventName":"GLEIF Summit", "accessLevel":"staff", "validDate":"2026-10-01" } ### Step 2: Creating the Credential The `kli vc create` command is used by the Issuer to generate the ACDC. Let's break down the parameters:   - `--name`, `--passcode`, and `--alias`: Identify the Issuer's keystore and the specific AID within that keystore that will act as the credential issuer. - `--registry-name`: Specifies the credential registry the Issuer will use to manage this credential's lifecycle (issuance/revocation).   - `--schema`: Provides the SAID of the ACDC schema (event_pass_schema.json in this case) that defines the structure of this credential.   - `--recipient`: Specifies the AID of the entity the credential is about (the Holder/subject).   - `--data`: Points to the file containing the specific attribute values for this credential instance (@ indicates it's a file path).   - `--time`: Provides an issuance timestamp for the credential. Executing this command creates the credential, generates its SAID, and records an issuance event in the specified registry's TEL, anchoring it to the Issuer's KEL. ```python time = exec("kli time") !kli vc create --name {issuer_keystore_name} --passcode {issuer_keystore_passcode} \ --alias {issuer_aid} \ --registry-name {issuer_registry_name} \ --schema {schema_said} \ --recipient {holder_aid} \ --data "@./config/credential_data/event_pass_cred_data.json" \ --time {time} ``` Waiting for TEL event witness receipts Sending TEL events to witnesses ELHVOxhpwnhi1fFPVaKx0z4Wgq-a6vRhAlkQcti9VM7b has been created. ### Viewing the Issued Credential The kli vc list command allows the Issuer to see the credentials they have issued. The `--issued` flag specifies listing issued credentials, and `--verbose` shows the full credential content. ```python !kli vc list --name {issuer_keystore_name} \ --passcode {issuer_keystore_passcode} \ --issued \ --verbose ``` Current issued credentials for issuer_aid (EHlIlnBBlmKA08zLU4RDuYCkVs1k7-Jqdavd52P2HQ5h): Credential #1: ELHVOxhpwnhi1fFPVaKx0z4Wgq-a6vRhAlkQcti9VM7b Type: EventPass Status: Issued ✔ Issued by EHlIlnBBlmKA08zLU4RDuYCkVs1k7-Jqdavd52P2HQ5h Issued on 2025-09-12T04:08:04.132496+00:00 Full Credential: { "v": "ACDC10JSON0001c4_", "d": "ELHVOxhpwnhi1fFPVaKx0z4Wgq-a6vRhAlkQcti9VM7b", "i": "EHlIlnBBlmKA08zLU4RDuYCkVs1k7-Jqdavd52P2HQ5h", "ri": "EEmDzzrlo010uNzZTBcP7aAIH01Dg4ADVWjGFucPe4Oj", "s": "EGUPiCVO73M9worPwR3PfThAtC0AJnH5ZgwsXf6TzbVK", "a": { "d": "ECeG0MVFv5MPNmGU-WyCsibchyOj4mpObklXmF7-wncC", "i": "EPqFKtQQ8kzLxPD943ytdj6a3JcXV_IDgYGu88PWNli0", "dt": "2025-09-12T04:08:04.132496+00:00", "eventName": "GLEIF Summit", "accessLevel": "staff", "validDate": "2026-10-01" } } Notice the structure of the credential JSON:   - `v`: Version string for the ACDC format and serialization. - `d`: The SAID of this specific credential instance. - `i`: The Issuer's AID. - `ri`: The SAID of the credential registry used. - `s`: The SAID of the schema used. - `a`: The attributes block, containing: - `d`: The SAID of the attributes block itself. - `i`: The Issuee's (Holder's) AID. - `dt`: The issuance date/time. - `eventName`, `accessLevel`, and `validDate`: The specific data for this credential. ### Retrieving the Credential's SAID You need to retrieve the credential's SAID (`d` field) to use it as the identifier in the subsequent IPEX steps. Use `kli vc list` again, but add the `--said` flag to return only the SAID of the matching credential(s). ```python get_credential_said = f"kli vc list --name {issuer_keystore_name}\ --passcode {issuer_keystore_passcode} --alias {issuer_aid}\ --issued --schema {schema_said}\ --said" credential_said=exec(get_credential_said) print(credential_said) ``` ELHVOxhpwnhi1fFPVaKx0z4Wgq-a6vRhAlkQcti9VM7b ## Issuing the Credential to the Holder via IPEX At this point, the ACDC has been created and recorded in the Issuer's registry, but it still needs to be provided to the Holder. To do so, we use the **Issuance and Presentation Exchange (IPEX) protocol**. IPEX defines a message-based workflow for offering, accepting, or rejecting credentials. ### Step 1: Issuer Sends Grant Message The Issuer (acting as the "Discloser" in IPEX terms) initiates the issuance by sending a grant message to the Holder (the "Disclosee"). The `kli ipex grant` command facilitates this.   The parameters are: - `--name`, `--passcode`, and `--alias`: Identify the Issuer's keystore and AID. - `--said`: The SAID of the credential being granted (which we retrieved in the previous step). - `--recipient`: The AID of the Holder who should receive the credential offer. - `--time`: A timestamp for the grant message. This command sends an IPEX grant message containing the credential data to the Holder's KERI mailbox (managed via witnesses). ```python time = exec("kli time") !kli ipex grant \ --name {issuer_keystore_name} \ --passcode {issuer_keystore_passcode} \ --alias {issuer_aid} \ --said {credential_said} \ --recipient {holder_aid} \ --time {time} ``` Sending message EMZJcWSDJA62-XyjVChSXBDXoAcDNV_qWlxxZ2NV1m23 to EPqFKtQQ8kzLxPD943ytdj6a3JcXV_IDgYGu88PWNli0 ... grant message sent **Issuer Views Sent Messages (Optional)** This step isn't strictly required for the workflow but allows the Issuer to view the IPEX messages they have sent using `kli ipex list --sent`. This can be useful for debugging or tracking the state of exchanges. It shows the GRANT message SAID and details about the credential offered. ```python !kli ipex list --name {issuer_keystore_name} \ --passcode {issuer_keystore_passcode} \ --alias {issuer_aid} \ --sent ``` Sent IPEX Messages: GRANT - SAID: EMZJcWSDJA62-XyjVChSXBDXoAcDNV_qWlxxZ2NV1m23 Credential ELHVOxhpwnhi1fFPVaKx0z4Wgq-a6vRhAlkQcti9VM7b: Type: EventPass Status: Issued ✔ Issued by EHlIlnBBlmKA08zLU4RDuYCkVs1k7-Jqdavd52P2HQ5h Issued on 2025-09-12T04:08:04.132496+00:00 Already responded? No ✘ ### Step 2: Holder Receives Grant Message The Holder needs to check their KERI mailbox for incoming messages. The `kli ipex list --poll` command checks for new IPEX messages. Use `--said` again to extract just the SAID of the received grant message, which is needed for the next step (accepting the credential). ```python get_ipex_said=f"kli ipex list --name {holder_keystore_name}\ --passcode {holder_keystore_passcode} --alias {holder_aid}\ --poll\ --said" ipex_said=exec(get_ipex_said) print(ipex_said) ``` EMZJcWSDJA62-XyjVChSXBDXoAcDNV_qWlxxZ2NV1m23 **Holder Views Received Messages (Optional)** Similar to the Issuer checking sent messages, the Holder can use `kli ipex list` (without `--sent`) to view received IPEX messages. This confirms receipt of the GRANT offer from the Issuer. ```python !kli ipex list --name {holder_keystore_name} \ --passcode {holder_keystore_passcode} \ --alias {holder_aid} ``` Received IPEX Messages: GRANT - SAID: EMZJcWSDJA62-XyjVChSXBDXoAcDNV_qWlxxZ2NV1m23 Credential ELHVOxhpwnhi1fFPVaKx0z4Wgq-a6vRhAlkQcti9VM7b: Type: EventPass Status: Issued ✔ Issued by EHlIlnBBlmKA08zLU4RDuYCkVs1k7-Jqdavd52P2HQ5h Issued on 2025-09-12T04:08:04.132496+00:00 Already responded? No ✘ ### Step 3: Holder Admits Credential Now that the Holder has received the `grant` message (identified by `ipex_said`), they can choose to accept the credential using the `kli ipex admit` command.   - `--name`, `--passcode`, and `--alias`: Identify the Holder's keystore and AID. - `--said`: The SAID of the grant message being admitted. - `--time`: A timestamp for the admit message. This sends an `admit` message back to the Issuer, confirming acceptance. The Holder's KERI controller automatically verifies the credential against its schema and the Issuer's KEL upon admitting it, and then stores the credential securely. ```python time = exec("kli time") !kli ipex admit \ --name {holder_keystore_name} \ --passcode {holder_keystore_passcode} \ --alias {holder_aid} \ --said {ipex_said} \ --time {time} ``` Sending admit message to EHlIlnBBlmKA08zLU4RDuYCkVs1k7-Jqdavd52P2HQ5h ... admit message sent **Holder Views Sent Admit Message (Optional)** The Holder can optionally check their sent IPEX messages to confirm the `ADMIT` message was sent. ```python !kli ipex list --name {holder_keystore_name} \ --passcode {holder_keystore_passcode} \ --alias {holder_aid} \ --sent ``` Sent IPEX Messages: ADMIT - SAID: EID3UguZFjg_YVUvDBOgrfmRlFOyVDIgCs7Hri91iREB Admitted message SAID: EMZJcWSDJA62-XyjVChSXBDXoAcDNV_qWlxxZ2NV1m23 Credential ELHVOxhpwnhi1fFPVaKx0z4Wgq-a6vRhAlkQcti9VM7b: Type: EventPass Status: Accepted ✔ ### Step 4: Holder Verifies Possession The issuance process is complete! The Holder now possesses the verifiable credential. They can view it using kli vc list --verbose. The output will be similar to when the Issuer listed the issued credential, confirming the Holder has successfully received and stored the ACDC. ```python !kli vc list --name {holder_keystore_name} \ --passcode {holder_keystore_passcode} \ --verbose ``` Current received credentials for holder_aid (EPqFKtQQ8kzLxPD943ytdj6a3JcXV_IDgYGu88PWNli0): Credential #1: ELHVOxhpwnhi1fFPVaKx0z4Wgq-a6vRhAlkQcti9VM7b Type: EventPass Status: Issued ✔ Issued by EHlIlnBBlmKA08zLU4RDuYCkVs1k7-Jqdavd52P2HQ5h Issued on 2025-09-12T04:08:04.132496+00:00 Full Credential: { "v": "ACDC10JSON0001c4_", "d": "ELHVOxhpwnhi1fFPVaKx0z4Wgq-a6vRhAlkQcti9VM7b", "i": "EHlIlnBBlmKA08zLU4RDuYCkVs1k7-Jqdavd52P2HQ5h", "ri": "EEmDzzrlo010uNzZTBcP7aAIH01Dg4ADVWjGFucPe4Oj", "s": "EGUPiCVO73M9worPwR3PfThAtC0AJnH5ZgwsXf6TzbVK", "a": { "d": "ECeG0MVFv5MPNmGU-WyCsibchyOj4mpObklXmF7-wncC", "i": "EPqFKtQQ8kzLxPD943ytdj6a3JcXV_IDgYGu88PWNli0", "dt": "2025-09-12T04:08:04.132496+00:00", "eventName": "GLEIF Summit", "accessLevel": "staff", "validDate": "2026-10-01" } }
📝 SUMMARY
---
In the KERI and ACDC ecosystem credentials are created and issued as authentic chained data containers (ACDCs) within the Issuance and Presentation Exchange Protocol (IPEX).
Issuance of an ACDC using this protocol involves the following steps:
1. Setup: Issuer and Holder established identities (AIDs) and connected via OOBI resolution.
2. Registry: Issuer created a credential registry (managed via a TEL) to track credential status.
3. Schema: An ACDC schema was defined (using JSON Schema) and made verifiable through SAIDification. It was made discoverable via a simple caching server (vLEI-server) and resolved by both parties using its OOBI.
4. Creation: Issuer created the specific ACDC instance using kli vc create, providing data conforming to the schema and linking it to the registry.
5. IPEX Issuance:
   • Issuer offered the credential using kli ipex grant (sending a GRANT message).
   • Holder received the offer (polling with kli ipex list --poll).
   • Holder accepted the credential using kli ipex admit (sending an ADMIT message).
6. Result: Holder successfully received and stored the verifiable credential (ACDC).
This process ensures that credentials are not only structured and verifiable against a schema but are also securely issued and provided to authenticated KERI identities.
[<- Prev (Saidify schema)](101_60_Saidify_schema.ipynb) | [Next (ACDC Presentation and Revocation) ->](101_70_ACDC_Presentation_and_Revocation.ipynb) # ACDC Presentation and Revocation with KLI: Using the IPEX Protocol
🎯 OBJECTIVE
---
Demonstrate how a Holder presents a previously issued ACDC or Verifiable Credential (VC) to a Verifier using the Issuance and Presentation Exchange (IPEX) protocol.

Understand how IPEX allows credential holders (issuees) to sign that they agree with the terms of a credential.

Conduct a credential revocation and present a revoked credential as an issuer so the holder may learn that a credential they hold has been revoked. Learn that observer infrastructure may be used for pull-style monitoring of credential revocation state.
## Credential Presentation Overview In the previous notebook, you saw how an Issuer creates and sends an ACDC to a Holder. Now, we'll focus on the next steps in the typical verifiable credential lifecycle: presentation and admittance. After creating the credential the Issuer must present it to the Holder. In IPEX this presentation is called an IPEX Grant message. After receiving the IPEX Grant message the Holder can then accept the credential by performing an IPEX Admit message. In the prior training this Grant and Admit process were explained. In this training, following the reception of a credential, the Holder will present it to another party (the Verifier) to prove certain claims or gain access to something. You will again use the IPEX protocol for this exchange, but this time initiated by the Holder. Finally, you will see how the original Issuer can revoke the credential. ### Recap: Issuing the Prerequisite Credential To present a credential, you first need one! The following code block is a condensed recap of the ACDC Issuance workflow covered in the previous notebook. It quickly sets up an Issuer and a Holder, creates a Credential Registry, defines and resolves a schema, issues an `EventPass` credential from the Issuer to the Holder using IPEX, and ensures the Holder admits it.
ℹ️ NOTE:
---
For a detailed explanation of these issuance steps, please refer to the previous notebook.
```python from scripts.utils import exec from scripts.saidify import process_schema_file, get_schema_said from scripts.utils import pr_title, pr_message, pr_continue, clear_keri clear_keri() # Holder keystore init and AID inception holder_keystore_name = "holder_presentation_ks" holder_keystore_passcode = exec("kli passcode generate") holder_keystore_salt = exec("kli salt") holder_aid = "holder_aid" !kli init --name {holder_keystore_name} --passcode {holder_keystore_passcode} --salt {holder_keystore_salt}\ --config-dir ./config \ --config-file keystore_init_config.json !kli incept --name {holder_keystore_name} --alias {holder_aid} --passcode {holder_keystore_passcode} \ --file ./config/aid_inception_config.json # Issuer keystore init and AID inception issuer_keystore_name = "issuer_presentation_ks" issuer_keystore_passcode = exec("kli passcode generate") issuer_keystore_salt = exec("kli salt") issuer_aid = "issuer_aid" !kli init --name {issuer_keystore_name} --passcode {issuer_keystore_passcode} --salt {issuer_keystore_salt}\ --config-dir ./config \ --config-file keystore_init_config.json !kli incept --name {issuer_keystore_name} --passcode {issuer_keystore_passcode} --alias {issuer_aid}\ --file ./config/aid_inception_config.json # Issuer registry inception issuer_registry_name="issuer_registry" !kli vc registry incept --name {issuer_keystore_name} \ --passcode {issuer_keystore_passcode} \ --registry-name {issuer_registry_name} \ --alias {issuer_aid} # Issuer and Holder oobi holder_oobi_gen = f"kli oobi generate --name {holder_keystore_name} --alias {holder_aid}\ --passcode {holder_keystore_passcode} --role witness" holder_oobi = exec(holder_oobi_gen) issuer_oobi_gen = f"kli oobi generate --name {issuer_keystore_name} --alias {issuer_aid}\ --passcode {issuer_keystore_passcode} --role witness" issuer_oobi = exec(issuer_oobi_gen) !kli oobi resolve --name {holder_keystore_name} --passcode {holder_keystore_passcode}\ --oobi-alias {issuer_aid} --oobi {issuer_oobi} !kli oobi resolve --name {issuer_keystore_name} --passcode {issuer_keystore_passcode}\ --oobi-alias {holder_aid} --oobi {holder_oobi} # Issuer and Holder resolve schema oobis schema_oobi_alias = "schema_oobi" schema_said = get_schema_said("config/schemas/event_pass_schema.json") schema_oobi = f"http://vlei-server:7723/oobi/{schema_said}" !kli oobi resolve --name {holder_keystore_name} --passcode {holder_keystore_passcode}\ --oobi-alias {schema_oobi_alias} --oobi {schema_oobi} !kli oobi resolve --name {issuer_keystore_name} --passcode {issuer_keystore_passcode}\ --oobi-alias {schema_oobi_alias} --oobi {schema_oobi} # Issuer create VC time = exec("kli time") !kli vc create --name {issuer_keystore_name} --passcode {issuer_keystore_passcode} \ --alias {issuer_aid} \ --registry-name {issuer_registry_name} \ --schema {schema_said} \ --recipient {holder_aid} \ --data "@./config/credential_data/event_pass_cred_data.json" \ --time {time} # Get credential said get_credential_said = f"kli vc list --name {issuer_keystore_name}\ --passcode {issuer_keystore_passcode} --alias {issuer_aid}\ --issued --said --schema {schema_said}" credential_said=exec(get_credential_said) #Issuer grant credential time = exec("kli time") !kli ipex grant \ --name {issuer_keystore_name} --passcode {issuer_keystore_passcode} \ --alias {issuer_aid} \ --said {credential_said} \ --recipient {holder_aid} \ --time {time} # Holder poll and admit credential get_ipex_said=f"kli ipex list --name {holder_keystore_name} --passcode {holder_keystore_passcode}\ --alias {holder_aid} --poll --said" ipex_said=exec(get_ipex_said) time = exec("kli time") !kli ipex admit \ --name {holder_keystore_name} \ --passcode {holder_keystore_passcode} \ --alias {holder_aid} \ --said {ipex_said} \ --time {time} pr_continue() ``` Proceeding with deletion of '/usr/local/var/keri/' without confirmation. ✅ Successfully removed: /usr/local/var/keri/ KERI Keystore created at: /usr/local/var/keri/ks/holder_presentation_ks KERI Database created at: /usr/local/var/keri/db/holder_presentation_ks KERI Credential Store created at: /usr/local/var/keri/reg/holder_presentation_ks aeid: BCZkp5jCZSrAGst3Ih8NUlRXfPKIOgRm9ONrtVQ21xzf Loading 3 OOBIs... http://witness-demo:5642/oobi/BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha/controller?name=Wan&tag=witness succeeded http://witness-demo:5643/oobi/BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM/controller?name=Wes&tag=witness succeeded http://witness-demo:5644/oobi/BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX/controller?name=Wil&tag=witness succeeded Waiting for witness receipts... Prefix EDmofynK4DYITOe2ZN7BOSWigjqonV0MJurARWS_GqbG Public key 1: DI1Wi9wD1vvFea1AucpkPiqPLYb2zQqnGksSJAf09eGE KERI Keystore created at: /usr/local/var/keri/ks/issuer_presentation_ks KERI Database created at: /usr/local/var/keri/db/issuer_presentation_ks KERI Credential Store created at: /usr/local/var/keri/reg/issuer_presentation_ks aeid: BHCyVyfwFhoNgQ1MCt1XjRuOUA1hAB2QNtsGyDwf-Zfn Loading 3 OOBIs... http://witness-demo:5642/oobi/BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha/controller?name=Wan&tag=witness succeeded http://witness-demo:5643/oobi/BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM/controller?name=Wes&tag=witness succeeded http://witness-demo:5644/oobi/BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX/controller?name=Wil&tag=witness succeeded Waiting for witness receipts... Prefix EH50FjEtKMgmuqmDK6ZePMlBuj486dONDgEQMOZHKPlp Public key 1: DLE56BwLSekxGRapPG0gKiosIn6YCOqe6ha7xr2TrEfu Waiting for TEL event witness receipts Sending TEL events to witnesses Registry: issuer_registry(EOye1znk5_zjIbFOD2K69vFyeILszmlaHg-rMmkfQs17) created for Identifier Prefix: EH50FjEtKMgmuqmDK6ZePMlBuj486dONDgEQMOZHKPlp http://witness-demo:5642/oobi/EH50FjEtKMgmuqmDK6ZePMlBuj486dONDgEQMOZHKPlp/witness resolved http://witness-demo:5642/oobi/EDmofynK4DYITOe2ZN7BOSWigjqonV0MJurARWS_GqbG/witness resolved http://vlei-server:7723/oobi/EGUPiCVO73M9worPwR3PfThAtC0AJnH5ZgwsXf6TzbVK resolved http://vlei-server:7723/oobi/EGUPiCVO73M9worPwR3PfThAtC0AJnH5ZgwsXf6TzbVK resolved Waiting for TEL event witness receipts Sending TEL events to witnesses EGV-i9sG9H28DXpLN2PGxWq0tfqJjvMRcvM8HQsDWAvv has been created. Sending message EGzklyr7aJhhq9Fz0H_PKOZyfYf6LZAv5v6xtYNQ1C9G to EDmofynK4DYITOe2ZN7BOSWigjqonV0MJurARWS_GqbG ... grant message sent Sending admit message to EH50FjEtKMgmuqmDK6ZePMlBuj486dONDgEQMOZHKPlp ... admit message sent You can continue ✅ ## The IPEX Presentation Flow Now that the Holder (`holder_aid`) possesses the `EventPass` credential, you must present it to a Verifier (`verifier_aid`) to prove they have access. First, confirm the Holder has the credential: ```python !kli vc list --name {holder_keystore_name} \ --passcode {holder_keystore_passcode} \ --verbose ``` Current received credentials for holder_aid (EDmofynK4DYITOe2ZN7BOSWigjqonV0MJurARWS_GqbG): Credential #1: EGV-i9sG9H28DXpLN2PGxWq0tfqJjvMRcvM8HQsDWAvv Type: EventPass Status: Issued ✔ Issued by EH50FjEtKMgmuqmDK6ZePMlBuj486dONDgEQMOZHKPlp Issued on 2025-09-12T04:08:49.611720+00:00 Full Credential: { "v": "ACDC10JSON0001c4_", "d": "EGV-i9sG9H28DXpLN2PGxWq0tfqJjvMRcvM8HQsDWAvv", "i": "EH50FjEtKMgmuqmDK6ZePMlBuj486dONDgEQMOZHKPlp", "ri": "EOye1znk5_zjIbFOD2K69vFyeILszmlaHg-rMmkfQs17", "s": "EGUPiCVO73M9worPwR3PfThAtC0AJnH5ZgwsXf6TzbVK", "a": { "d": "ENczl5MMVY5onNct_N70lQ1KFMj-D5cS2Cof0P91A92n", "i": "EDmofynK4DYITOe2ZN7BOSWigjqonV0MJurARWS_GqbG", "dt": "2025-09-12T04:08:49.611720+00:00", "eventName": "GLEIF Summit", "accessLevel": "staff", "validDate": "2026-10-01" } } ### Verifier AID Setup Just like the Issuer and Holder, the Verifier needs its own AID to participate in the protocol securely. Initialize its keystore and incept its AID. ```python verifier_keystore_name="verifier_ks" verifier_keystore_passcode = exec("kli passcode generate") verifier_keystore_salt = exec("kli salt") # Alias for our non-transferable AID verifier_aid = "verifier_aid" # Initialize the keystore !kli init --name {verifier_keystore_name} --passcode {verifier_keystore_passcode} --salt {verifier_keystore_salt}\ --config-dir ./config \ --config-file keystore_init_config.json !kli incept --name {verifier_keystore_name} --alias {verifier_aid} --passcode {verifier_keystore_passcode} \ --file ./config/aid_inception_config.json ``` KERI Keystore created at: /usr/local/var/keri/ks/verifier_ks KERI Database created at: /usr/local/var/keri/db/verifier_ks KERI Credential Store created at: /usr/local/var/keri/reg/verifier_ks aeid: BNMnc4WKQ_mpXRhOwUjVHPiHnNJq-xm2oMHfE_U_I_Lf Loading 3 OOBIs... http://witness-demo:5642/oobi/BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha/controller?name=Wan&tag=witness succeeded http://witness-demo:5643/oobi/BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM/controller?name=Wes&tag=witness succeeded http://witness-demo:5644/oobi/BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX/controller?name=Wil&tag=witness succeeded Waiting for witness receipts... Prefix EAGnYBs-ystvZGmDO3rayU2iKSkKmfYIs0uwxFAm8gmy Public key 1: DBeE9xOz1nrn4wEOjD2dY0mZ3qNACvw75iljIJ16wkbb ### Establishing Holder-Verifier Connection (OOBI) Similar to the Issuer/Holder exchange, the Holder and Verifier must exchange and resolve OOBIs to establish a secure communication channel and verify each other's key states (KELs). ```python holder_oobi_gen = f"kli oobi generate --name {holder_keystore_name} --alias {holder_aid}\ --passcode {holder_keystore_passcode} --role witness" holder_oobi = exec(holder_oobi_gen) verifier_oobi_gen = f"kli oobi generate --name {verifier_keystore_name} --alias {verifier_aid}\ --passcode {verifier_keystore_passcode} --role witness" verifier_oobi = exec(verifier_oobi_gen) !kli oobi resolve --name {holder_keystore_name} --passcode {holder_keystore_passcode}\ --oobi-alias {verifier_aid} --oobi {verifier_oobi} !kli oobi resolve --name {verifier_keystore_name} --passcode {verifier_keystore_passcode}\ --oobi-alias {holder_aid} --oobi {holder_oobi} ``` http://witness-demo:5642/oobi/EAGnYBs-ystvZGmDO3rayU2iKSkKmfYIs0uwxFAm8gmy/witness resolved http://witness-demo:5642/oobi/EDmofynK4DYITOe2ZN7BOSWigjqonV0MJurARWS_GqbG/witness resolved ### Verifier Resolves Schema OOBI The Verifier also needs to resolve the OOBI for the ACDC's schema (`event_pass_schema`). This allows the Verifier to retrieve the schema definition and validate that the presented credential conforms to the expected structure and data types. Without the schema, the Verifier wouldn't know how to interpret or validate the credential's content. ```python !kli oobi resolve --name {verifier_keystore_name} --passcode {verifier_keystore_passcode}\ --oobi-alias {schema_oobi_alias} --oobi {schema_oobi} ``` http://vlei-server:7723/oobi/EGUPiCVO73M9worPwR3PfThAtC0AJnH5ZgwsXf6TzbVK resolved ### Step 1: Holder Presents Credential (Grant) Now, the Holder initiates the IPEX exchange to present the credential to the Verifier. The Holder acts as the "Discloser" in this context. The command used is `kli ipex grant`, just like in issuance, but the IPEX roles here are different so the Holder is the discloser and the Verifier is the disclosee. - `--name`, `--passcode`, `--alias`: Identify the Holder's keystore and AID. - `--said`: The SAID of the credential being presented. - `--recipient`: The AID of the Verifier who should receive the presentation. - `--time`: A timestamp for the grant message. This sends an IPEX Grant message, effectively offering the credential presentation to the Verifier.
ℹ️ NOTE: on --time
---
Including the time --time argument is only necessary when performing multisignature operations. It is shown below for illustrative purposes only. This argument is necessary for multisignature operations because each participating controller must produce the exact same event, in this case an IPEX Grant message, as all the other members of a multisig group. Since a timestamp is one of the attributes in an IPEX Grant message then in order to produce the exact same event, and thereby the same event digest, the same value for a timestamp must be used by each controller when constructing the event. At the command line this is provided with the `--time` argument to the `kli ipex grant` command. You will notice the output value of the `kli time` command is used in various places in these Jupyter notebooks. The necessity of the `--time` command is the same for each context; it is only applicable to multi-signature operations.
```python time = exec("kli time") !kli ipex grant \ --name {holder_keystore_name} \ --passcode {holder_keystore_passcode} \ --alias {holder_aid} \ --said {credential_said} \ --recipient {verifier_aid} \ --time {time} ``` Sending message EOnPhZZr-9D5E9lyr9dpSu9TonBePJfbhTuFdd4d_F8Q to EAGnYBs-ystvZGmDO3rayU2iKSkKmfYIs0uwxFAm8gmy ... grant message sent Receiving the Grant message triggers the Verifier's KERI controller to perform several checks automatically: - Schema Validation: Checks whether the credential structure and data types match the resolved schema. - Issuer Authentication: Verifies the credential signature against the Issuer's KEL (previously retrieved via OOBI) and, importantly, checks the credential's status (e.g., not revoked) against the Issuer's registry (TEL). If all checks pass, the Verifier may admit the ACDC, store the validated credential information, and send an IPEX Admit message back to the Holder. ### Step 2: Verifier Receives Presentation The Verifier needs to check its KERI mailbox(es) for the incoming grant message containing the credential presentation. Use `kli ipex list --poll` to check the mailbox(es) and extract the SAID of the IPEX Grant message. ```python get_ipex_said=f"kli ipex list --name {verifier_keystore_name} --passcode {verifier_keystore_passcode}\ --alias {verifier_aid} --poll --said" ipex_said=exec(get_ipex_said) print(ipex_said) pr_continue() ``` EOnPhZZr-9D5E9lyr9dpSu9TonBePJfbhTuFdd4d_F8Q You can continue ✅ **Verifier displays credential (Optional)** Before formally admitting the credential, the Verifier can inspect the received presentation using `kli ipex list --verbose`. This shows the credential details and the status of the IPEX exchange. ```python !kli ipex list \ --name {verifier_keystore_name} \ --passcode {verifier_keystore_passcode} \ --alias {verifier_aid} \ --verbose ``` Received IPEX Messages: GRANT - SAID: EOnPhZZr-9D5E9lyr9dpSu9TonBePJfbhTuFdd4d_F8Q Credential EGV-i9sG9H28DXpLN2PGxWq0tfqJjvMRcvM8HQsDWAvv: Type: EventPass Status: Issued ✔ Issued by EH50FjEtKMgmuqmDK6ZePMlBuj486dONDgEQMOZHKPlp Issued on 2025-09-12T04:08:49.611720+00:00 Already responded? No ✘ Full Credential: { "v": "ACDC10JSON0001c4_", "d": "EGV-i9sG9H28DXpLN2PGxWq0tfqJjvMRcvM8HQsDWAvv", "i": "EH50FjEtKMgmuqmDK6ZePMlBuj486dONDgEQMOZHKPlp", "ri": "EOye1znk5_zjIbFOD2K69vFyeILszmlaHg-rMmkfQs17", "s": "EGUPiCVO73M9worPwR3PfThAtC0AJnH5ZgwsXf6TzbVK", "a": { "d": "ENczl5MMVY5onNct_N70lQ1KFMj-D5cS2Cof0P91A92n", "i": "EDmofynK4DYITOe2ZN7BOSWigjqonV0MJurARWS_GqbG", "dt": "2025-09-12T04:08:49.611720+00:00", "eventName": "GLEIF Summit", "accessLevel": "staff", "validDate": "2026-10-01" } } The status of the credential is shown by `Already responded? No ✘` meaning that an IPEX Admit from the Verifier to the Holder has not yet been sent. ### Step 3: Verifier Admits and Validates Presentation (Agreeing to Terms) An admit is not strictly necessary between the verifier and the holder, though sending an admit is one way the Verifier signals to the holder that the verifier agrees to the terms of the credential presentation. The terms in the credential are specified in the rules section. The Verifier uses the `kli ipex admit` command to accept the presentation. ```python time = exec("kli time") !kli ipex admit \ --name {verifier_keystore_name} \ --passcode {verifier_keystore_passcode} \ --alias {verifier_aid} \ --said {ipex_said} \ --time {time} ``` Sending admit message to EDmofynK4DYITOe2ZN7BOSWigjqonV0MJurARWS_GqbG ... admit message sent **Verifier Confirms Admission** Finally, the Verifier can check the status of the received IPEX message again. The Already responded? field should now show Yes ✔ and indicate the response was Admit, confirming the successful presentation and validation. ```python !kli ipex list \ --name {verifier_keystore_name} \ --passcode {verifier_keystore_passcode} \ --alias {verifier_aid} \ --verbose ``` Received IPEX Messages: GRANT - SAID: EOnPhZZr-9D5E9lyr9dpSu9TonBePJfbhTuFdd4d_F8Q Credential EGV-i9sG9H28DXpLN2PGxWq0tfqJjvMRcvM8HQsDWAvv: Type: EventPass Status: Issued ✔ Issued by EH50FjEtKMgmuqmDK6ZePMlBuj486dONDgEQMOZHKPlp Issued on 2025-09-12T04:08:49.611720+00:00 Already responded? Yes ✔ Response: Admit (EJEDrSDzp8ZustZb2DWdVVTivei8caUc65k2NTobtbK8) Full Credential: { "v": "ACDC10JSON0001c4_", "d": "EGV-i9sG9H28DXpLN2PGxWq0tfqJjvMRcvM8HQsDWAvv", "i": "EH50FjEtKMgmuqmDK6ZePMlBuj486dONDgEQMOZHKPlp", "ri": "EOye1znk5_zjIbFOD2K69vFyeILszmlaHg-rMmkfQs17", "s": "EGUPiCVO73M9worPwR3PfThAtC0AJnH5ZgwsXf6TzbVK", "a": { "d": "ENczl5MMVY5onNct_N70lQ1KFMj-D5cS2Cof0P91A92n", "i": "EDmofynK4DYITOe2ZN7BOSWigjqonV0MJurARWS_GqbG", "dt": "2025-09-12T04:08:49.611720+00:00", "eventName": "GLEIF Summit", "accessLevel": "staff", "validDate": "2026-10-01" } } ## Credential Revocation by Issuer Credentials may need to be invalidated before their natural expiry (if any). This process is called revocation. In KERI/ACDC, revocation is performed by the original Issuer of the credential. The Issuer records a revocation event in the credential registry's Transaction Event Log (TEL), and that event is anchored to the Issuer's main KEL. The `kli vc revoke` command is used by the Issuer: - `--name`, `--passcode`, `--alias`: Identify the Issuer's keystore and AID. - `--registry-name`: Specifies the registry where the credential's status is managed. - `--said`: The SAID of the specific credential instance to be revoked. - `--time`: Timestamp for the revocation event. ```python !kli vc revoke --name {issuer_keystore_name} --passcode {issuer_keystore_passcode} \ --alias {issuer_aid} \ --registry-name {issuer_registry_name} \ --said {credential_said} \ --time {time} ``` Waiting for TEL event witness receipts Sending TEL events to witnesses Now, if the Issuer lists their issued credentials again, the status will reflect the revocation: ```python !kli vc list --name {issuer_keystore_name} --passcode {issuer_keystore_passcode} \ --alias {issuer_aid} \ --issued ``` Current issued credentials for issuer_aid (EH50FjEtKMgmuqmDK6ZePMlBuj486dONDgEQMOZHKPlp): Credential #1: EGV-i9sG9H28DXpLN2PGxWq0tfqJjvMRcvM8HQsDWAvv Type: EventPass Status: Revoked ✘ Issued by EH50FjEtKMgmuqmDK6ZePMlBuj486dONDgEQMOZHKPlp Issued on 2025-09-12T04:09:27.999812+00:00 ### Sharing the revoked credential status with the Holder. Revoking a credential is an important event that should be shared with verifiers. One way to share a revocation with a verifier is to share the revocation of a credential with the Holder. After the Holder receives that revoked credential status then it can re-present the revoked credential to a verifier so that the verifier may know the credential is revoked. To accomplish this sharing of revocation state the issuer may perform another IPEX Grant of the credential following revocation. Then the Holder must again perform an IPEX Admit in order to learn of this revocation state.
ℹ️ NOTE: Observers for Learning of Revocation State
---
Use of an Observer node to learn of an ACDC credential state is another way for a verifier to learn of the revocation state of a credential. While standalone observers are under development, a witness of a controller may be used to query for credential state using the following request format:

`HTTP GET` to a witness host on the `/query` endpoint with URL parameters like so: - `/query?typ=tel&reg=EHrbPfpRLU9wpFXTzGY-LIo2FjMiljjEnt238eWHb7yZ&vcid=EO5y0jMXS5XKTYBKjCUPmNKPr1FWcWhtKwB2Go2ozvr0` A full query to a witness would look like so: - `https://wit1.testnet.gleif.org:5641/query?typ=tel®=EHrbPfpRLU9wpFXTzGY-LIo2FjMiljjEnt238eWHb7yZ&vcid=EO5y0jMXS5XKTYBKjCUPmNKPr1FWcWhtKwB2Go2ozvr0`
### Presenting a revoked credential Now the holder can present the revoked credential to the verifier and the verifier can understand that the credential is revoke. #### Step 1: Issuer Sends revocation status with IPEX An issuer may directly inform a holder using another IPEX Grant about the revocation status of any credential issued from itself.
ℹ️ NOTE: Observers for querying credential status
---
Waiting for an issuer to send credential revocation status is not the only way a holder can learn about whether or not a credential has been revoked. Observers are another way a verifier or a holder can learn of the credential status, issued or revoked, from an issuer. Currently, as of June 16, 2025, observers are in an early phase in their development and are deployed as a feature on an issuer's witness. Eventually observers will be standalone components.
```python # Issuer grants the now revoked credential time = exec("kli time") !kli ipex grant \ --name {issuer_keystore_name} --passcode {issuer_keystore_passcode} \ --alias {issuer_aid} \ --said {credential_said} \ --recipient {holder_aid} \ --time {time} ``` Sending message EJGct9b8z9nBEYJy6geDzeJpJL1zDBkpgQtfa17kFQBo to EDmofynK4DYITOe2ZN7BOSWigjqonV0MJurARWS_GqbG ... grant message sent #### Step 2: Holder Admits IPEX Grant of revoked credential Now the holder admits the IPEX Grant from the issuer of the recently revoked credential. ```python # Holder polls and admits the revoked credential # The pipe to "tail -n 1" makes sure to get the last IPEX Grant which will be the grant sharing the revoked credential get_ipex_said=f"kli ipex list --name {holder_keystore_name} --passcode {holder_keystore_passcode}\ --alias {holder_aid} --poll --said | tail -n 1 | tr -d '' " ipex_said=exec(get_ipex_said) print(f"Found grant {ipex_said} for revocation") time = exec("kli time") !kli ipex admit \ --name {holder_keystore_name} \ --passcode {holder_keystore_passcode} \ --alias {holder_aid} \ --said {ipex_said} \ --time {time} pr_continue() ``` Found grant EJGct9b8z9nBEYJy6geDzeJpJL1zDBkpgQtfa17kFQBo for revocation Sending admit message to EH50FjEtKMgmuqmDK6ZePMlBuj486dONDgEQMOZHKPlp ... admit message sent You can continue ✅ The holder now sees the credential status as "Revoked" in their credential list shown by `kli vc list.` ```python !kli vc list --name {holder_keystore_name} --passcode {holder_keystore_passcode} \ --alias {holder_aid} ``` Current received credentials for holder_aid (EDmofynK4DYITOe2ZN7BOSWigjqonV0MJurARWS_GqbG): Credential #1: EGV-i9sG9H28DXpLN2PGxWq0tfqJjvMRcvM8HQsDWAvv Type: EventPass Status: Revoked ✘ Issued by EH50FjEtKMgmuqmDK6ZePMlBuj486dONDgEQMOZHKPlp Issued on 2025-09-12T04:09:27.999812+00:00 Now that this credential is revoked it can similarly be presented to the verifier from either the issuer or the holder so that the verifier can learn of the revocation state of the credential. This would be a push-style workflow. Arguably a pull-style approach is better for verifiers where they query the issuer, or some other infrastructure, to learn of the revocation state of credentials, similar to checking certificate revocation lists ([CRLs](https://en.wikipedia.org/wiki/Certificate_revocation_list)) in the x509 TLS certificate model. Using **observer** infrastructure is the best way to accomplish pull-style querying for credential state. As of the writing of this training the only functional observer implementation is combined with witnesses as describe above in the note to the [Sharing the revoked credential status with the Holder](#Sharing-the-revoked-credential-status-with-the-Holder.) section.
📝 SUMMARY
---
This notebook demonstrated the ACDC presentation and revocation flows:
1. Prerequisites: We started with a Holder possessing an issued credential from an Issuer (established via the recap section).
2. Verifier Setup: A Verifier established its KERI identity (AID).
3. Connectivity: The Holder and Verifier exchanged and resolved OOBIs. The Verifier also resolved the credential's schema OOBI to enable validation.
4. Presentation (IPEX):
   • Holder initiated the presentation using kli ipex grant, sending the credential to the Verifier.
   • Verifier polled its mailbox (kli ipex list --poll) to receive the presentation.
   • Verifier accepted and validated the presentation using kli ipex admit. Validation included schema checks, issuer authentication (KEL), and registry status checks (TEL).
5. Revocation:
   • The original Issuer revoked the credential using kli vc revoke, updating the status in the credential registry's TEL.
   • The Issuer then presented via IPEX Grant the revoked credential to the Holder.
   • The Holder then received the revoked credential via IPEX Admit.
Observers were mentioned as pull-style infrastructure for verifiers, or anyone else, to learn of credential revocation state.

This completes the basic lifecycle demonstration: issuance (previous notebook), presentation, and revocation, all handled securely using KERI identities and the IPEX protocol.
[<- Prev (ACDC Issuance)](101_65_ACDC_Issuance.ipynb) | [Next (ACDC Edges and Rules) ->](101_75_ACDC_Edges_and_Rules.ipynb) # Advanced ACDC Features: Edges, Edge Operators, and Rules
🎯 OBJECTIVE
---
Introduce the concept of Edges in ACDCs, explain the Edge operators (I2I, NI2I, DI2I) that define relationships between chained ACDCs, illustrate their use with conceptual scenarios, and briefly introduce Rules as a component for embedding legal language and conditions within the ACDC.
## Understanding Edges and Rules Authentic Chained Data Containers (ACDCs) are not always standalone credentials. One of their features is the ability to be cryptographically linked to other ACDCs forming verifiable chains of information. These links, or chains, are defined in the `e` (edges) section of an ACDC's payload. ### ACDC Edges Section The term "edge" is used because a chain of ACDCs is a graph data structure, specifically a directed acyclic graph, a DAG. In a graph there are nodes and edges and parent nodes are pointed to by child nodes. A child is any node that points to another node. A parent is a node that is pointed to by at least one other node. ACDCs in a chain are the nodes and the edges are references included within an ACDC that point to another ACDC. The diagram below shows the following set of credentials and their edges: - ACDC A is issued by identifier One to Two and has no edges. - ACDC B is issued by identifier Two to Three and has an edge pointing to the A credential. - ACDC C is issued by identifier Three to Four and has an edge pointing to the B credential.  As you can see edges allow the chaining of credentials to previously issued credentials which allows a verifier to traverse the entire chain of credentials and perform cryptographic verifications and business logic validations on each link in the chain as well as the entire chain at once. This sort of credential stacking allows advanced issuance and verification workflows that can work across trust boundaries and across legal jurisdictions. Credential chaining in this way is one of the **most powerful** features of the KERI and ACDC protocol stack. Building on this power, edge operators enable different kinds of credential chains, or subchains to be created for a variety of purposes. ### Edge Operators As shown above, edges allow an ACDC to point to one or more ACDCs establishing a verifiable relationship between them. Edges define the kind of relationship between a child and a parent ACDC. This relationship is expressed as an **Edge Operators** which dictates the rules between the issuer and issuee of the connected ACDCs. Understanding these operators is crucial for designing ACDC ecosystems that model real-world authority, delegation, and contextual relationships. In this notebook we will focus on three unary edge operators and when to use each: * **I2I (Issuer-To-Issuee)** - the default; issuer of child ACDC is issuee of parent ACDC. * **NI2I (Not-Issuer-To-Issuee)** - useful for untargeted ACDCs; issuer has no relationship to parent credential issuee. * **DI2I (Delegated-Issuer-To-Issuee)** - issuer of child ACDC may be issuee or KEL delegate of issuee of parent ACDC. We will explore what each operator signifies and provide scenarios to illustrate their practical application. Edge operators provide the logic for validating the link between two ACDCs. They answer questions like: "Does the issuer of this ACDC need to be the subject of the ACDC it's pointing to?" or "Can the issuer be someone delegated by the subject of the linked ACDC?" ### ACDC Rules Section Beyond these structural links, ACDCs also feature a dedicated `r` (rules) section. This section allows for the embedding of machine-readable logic, conditions, or even legal prose directly within the credential. While edges define how ACDCs are connected, rules can define additional constraints or behaviors associated with the ACDC itself or its relationships. The rules section is currently somewhat simple and mostly used for specification of legal prose declaring the terms of use for a credential. The rest of this training explores the use of edge operators. ## I2I Operator: Issuer-To-Issuee The Issuer to Issuee (I2I) operator is the **implicit default** for any credential created by the reference implementation, KERIpy, and does not need to be specified explicitly during ACDC creation. As shown in the diagram below, this operator means that the *issuer* of a *child* credential MUST be referenced as the *issuee* of the *parent* credential. This is a **strict** constraint.  The core idea behind an I2I edge is to represent a direct chain of authority. The issuer of the current ACDC (the "near" ACDC containing the edge) is asserting its claims based on its status as the issuee of the ACDC it's pointing to (the "far" ACDC). I2I signifies: "My authority to issue this current ACDC may come from or otherwise involve the fact that I am the subject of the ACDC I am pointing to." ### I2I Scenario Examples 1. **Endorsement for Building Access:** * **Scenario:** A company (ACME) issues a "Manager role" ACDC to an Employee. The Employee (now acting as an issuer by virtue of their managerial role) then issues an "Access" ACDC for a specific building to a sub-contractor they hired. The "Access" ACDC would have an I2I edge pointing back to the employee's "Manager role" ACDC. | **Issuer** | **Issuee** | **Credential** | **I2I Edge** | |------------|----------------|----------------|--------------| | ACME | Employee | Manager role | N/A | | Employee | Sub-contractor | Access | Manager role | * **Diagram representation:** ```mermaid graph LR subgraph "Credential Chain" A[Access ACDC
Issuer: Employee
Issuee: Sub-contractor] B[Manager Role ACDC
Issuer: ACME
Issuee: Employee] A -->|I2I Edge| B end ``` * **Significance:** The I2I edge ensures the Manager issuing access is verifiably the same member to whom ACME conferred managerial status. In this case the door access management device acting as the **verifier** would check to ensure that the Access ACDC was issued with an I2I edge and that the *issuer* of the Access ACDC was indeed the *issuee* of the Manager role ACDC. 2. **Membership Level Endorsement for Event Access:** * **Scenario:** An Organization issues a "Gold Member" ACDC to an member. This member (Gold Member) then wants to bring a guest to an exclusive event. The organization's policies (which are embedded in the `r` section of the "Gold Member" ACDC) allow Gold Members to issue "Guest Pass" ACDCs. The "Guest Pass" issued by the Gold Member would have an I2I edge pointing to their "Gold Member" ACDC. | **Issuer** | **Isuee** | **Credential** | **I2I Edge** | |--------------|-----------|----------------|--------------| | Organization | Member | Gold Member | N/A | | Member | Guest | Guest Pass | Gold Member | * **Diagram representation:** ```mermaid graph LR subgraph "Credential Chain" A[Gold Member ACDC
Issuer: Organization
Issuee: Member] B[Guest Pass ACDC
Issuer: Member
Issuee: Guest] B -->|I2I Edge| A end ``` * **Significance:** The validity of the guest pass relies on the issuer being a verified Gold Member, as established by the I2I link, and governed by additional rules specified in the r section (e.g., limit on number of guest passes). In this case the door access point verifier would verify that the edge type was I2I and that the Gold Member was both the *issuer* of the Guest Pass ACDC and the *issuee* of the Gold Member ACDC. ### Use Cases for I2I 1. **Delegation of Authority with Credentials:** When an entity that was the subject (issuee) of a credential (e.g., "Manager Role") now needs to issue a subsequent credential by leveraging that conferred authority (e.g., "Project Approval" issued by the manager). 2. **Endorsement:** If one credential's authority directly enables the issuance of another by the same entity acting in a new capacity. 3. **Hierarchical Relationships:** When representing a clear hierarchy where an entity's position (as an issuee of a credential defining that position) allows them to issue credentials further down the chain. 4. **Sequential Processes:** In workflows where an entity receives a credential (making them an issuee) and then, as a next step in the process, issues another credential related to that item. Supply chain or multi-step workflows are areas where this would apply. 5. **Default Expectation for Targeted ACDCs:** If the far node (the ACDC being pointed to) is a "Targeted ACDC" (i.e., has an issuee), the I2I operator is the default assumption unless otherwise specified. This implies a natural flow where the issuee of one ACDC becomes the issuer of the next related ACDC. ## NI2I Operator: Not-Issuer-To-Issuee The NI2I operator is a **permissive** edge operator that allows any and all identifiers to chain a child ACDC onto a parent ACDC regardless of whether the issuer of the child ACDC is related to the parent ACDC in any way. The diagram below shows that Identifier Three can chain child ACDC B to parent ACDC A even though Three is not the issuee of parent ACDC A. Identifier Two is the recipient of both parent ACDC A and child ACDC B.  The purpose of the NI2I edge is to reference, associate, or link to another ACDC for context, support, or related information, where there isn't a direct delegation of authority or a requirement for the issuer of the current ACDC to be the subject of the referenced ACDC. NI2I means that this ACDC I am pointing to provides relevant context, support, or related information for my current ACDC, but my authority to issue this current ACDC does not stem from my being the subject of that linked ACDC. This sort of relationship is more decoupled than I2I and is more applicable to scenarios where the issuer of the parent credential is not necessarily related to or affiliated with the issuer of the child credential or does not want a strict relationship between the parent and child credentials. ### NI2I Scenario Examples 1. **Linking to an External Training Course Completion Certificate:** * **Scenario:** A Company issues an "Skill Certified" ACDC to an employee after they complete an internal assessment. The employee also completed an external, third-party training course relevant to this skill. The "Skill Certified" ACDC could have an NI2I edge pointing to the "Course Completion" ACDC issued by the external Training Provider. | **Issuer** | **Issuee** | **Credential** | **NI2I Edge** | |-------------------|-----------|-------------------|-------------------| | Training Provider | Employee | Course Completion | N/A | | Company | Employee | Skill Certified | Course Completion | * **Diagram representation:** ```mermaid graph LR subgraph "Credential Reference" A[Course Completion ACDC
Issuer: Training Provider
Issuee: Employee] B[Skill Certified ACDC
Issuer: Company
Issuee: Employee] B -.->|NI2I Edge
references for context| A end ``` * **Significance:** The company acknowledges the external training as supporting evidence. The `r` (rules) section of the "Skill Certified" ACDC could specify how this external certification contributes to the overall skill validation (e.g., "External certification X fulfills requirement Y"). 2. **Proof of Insurance for a Rental Agreement:** * **Scenario:** A Car Rental Agency issues a "Rental Agreement" ACDC to a Customer. The customer is required to have valid car insurance. The "Rental Agreement" ACDC could have an NI2I edge pointing to the Customer's "Proof of Insurance" ACDC, which was issued by an Insurance Company. | **Issuer** | **Issuee** | **Credential** | **NI2I Edge** | |-------------------|-----------|--------------------|--------------------| | Insurance Company | Customer | Proof of Insurance | N/A | | Rental Agency | Customer | Rental Agreement | Proof of Insurance | * **Diagram representation:** ```mermaid graph LR subgraph "Credential Reference" A[Proof of Insurance ACDC
Issuer: Insurance Company
Issuee: Customer] B[Rental Agreement ACDC
Issuer: Rental Agency
Issuee: Customer] B -.->|NI2I Edge
requires as evidence| A end ``` * **Significance:** The rental agreement relies on the existence of an insurance policy. The `r` section of the "Rental Agreement" ACDC would likely contain critical rules defining the terms of the rental, insurance coverage requirements (e.g., minimum liability), and consequences of non-compliance, which are legally binding. ### Use Cases for NI2I 1. **Referencing External Information:** When an ACDC needs to point to an ACDC that was issued by a third party and not specifically to the issuer of the current ACDC. The `r` (rules) section of the referencing ACDC might contain specific clauses on how that external information applies. 2. **Providing Supporting Evidence from Third Parties:** Linking to credentials issued by other independent parties that support a claim in the current ACDC. 3. **Associating Related but Independent Credentials:** When linking credentials that are related but don't follow a direct chain of delegated authority from the same entity. 4. **Linking to Untargeted ACDCs:** If the ACDC being pointed to is an "Untargeted ACDC" (i.e., does not have a specific issuee, representing a thing, a concept, or a general statement), then NI2I is appropriate. The issuer of the current ACDC isn't the "issuee" of a general concept. 5. **Relaxing the I2I Constraint:** When you explicitly want to state that the issuer of the current ACDC is not necessarily the issuee of the linked ACDC, even if the linked ACDC is targeted. ## DI2I Operator: Delegated-Issuer-To-Issuee The idea behind a DI2I edge is to allow delegates of the child ACDC issuer's parent AID to issue the child ACDC. This allows for additional security, flexibility, and scaling of ACDC issuance for the recipient of a targeted credential since the AID controller of the recipient can choose to issue further chained ACDC from delegates. Issuing credentials from delegates allows for a number of benefits including the single responsibility pattern, increased security due to less exposure of the parent AID's root signing keys, and scalability in the sense that many delegates can be authorized to issue ACDCs to avoid cluttering the parent AID's KEL. In DI2I the issuer of the child ACDC is either the root AID or a delegated AID of the root AID that is specified as the issuee of the parent ACDC. The same **strict** rule from I2I applies to the DI2I operator with additional flexibility coming from the fact that a delegate of the issuee of the parent ACDC may issue the child ACDC. DI2I signifies: My authority to issue this current ACDC comes from the fact that I am EITHER the subject of the ACDC I am pointing to OR I am a formally recognized delegate of that subject. ### DI2I Scenario Example 1. **Supply Chain: Quality Control Release by Delegated QC Supervisor** * **Scenario:** A Manufacturing Conglomerate issues a "Plant Operations Authority" ACDC to the General Manager (GM) of Plant A. This grants the GM overall responsibility for Plant A's output. * The GM of Plant A delegates the authority for final quality control (QC) release of specific product lines (e.g., "Widget Model X") to the QC Supervisor, via KERI AID delegation. * QC Supervisor's team completes QC checks on a batch of Widget Model X, and the QC Supervisor issues a "Batch Quality Approved" ACDC. | **Issuer** | **Issuee** | **Credential** | **DI2I Edge** | |----------------------------|-----------|----------------------------|----------------------------| | Manufacturing Conglomerate | GM | Plant Operations Authority | N/A | | QC Supervisor | Batch | Batch Quality Approved | Plant Operations Authority | * **Diagram representation:** ```mermaid graph TD subgraph "Credential Chain (ACDCs)" A["Plant Operations Authority ACDC
Issuer: Manufacturing Conglomerate
Issuee: GM"] B["Batch Quality Approved ACDC
Issuer:QC Supervisor
Issuee: Batch Recipient"] B -- "DI2I Edge
(Points to Authority ACDC)" --> A end subgraph "Identifier Relationship" GM_AID["General Manager's AID
(GM_PlantA_AID)"] QC_AID["QC Supervisor's AID
(QC_Supervisor_AID)"] GM_AID -- "KERI Delegation Event" --> QC_AID end style GM_AID fill:#cde4ff,stroke:#333 style QC_AID fill:#cde4ff,stroke:#333 ``` * **Significance (Why DI2I?):** QC Supervisor's authority is a verifiable delegation from the GM. The `r` (rules) section of the "Batch Quality Approved" ACDC might further specify the exact QC standards that must be met for the approval to be valid, linking the delegated action to concrete operational requirements. ### Use Cases for DI2I 1. **Delegation:** When authority is passed down through an intermediary. The entity issuing the current credential isn't the direct subject of the credential conferring original authority but is operating under a valid delegation from that subject. 2. **Flexible Hierarchical Authority:** In complex organizations, the person signing off on something (issuing an ACDC) might not be the person or identifier who holds the primary credential for that domain but is acting on their behalf through a formal delegation chain verified via KERI's AID delegation mechanisms. 3. **When the Issuer is Part of a Group Authorized by the Issuee:** The issuer is one of several individuals or entities who have been delegated authority by the issuee of the referenced ACDC. 4. **Requires a Targeted Far Node:** Like I2I, the ACDC being pointed to (the "far node") by a DI2I edge MUST be a "Targeted ACDC" (i.e., it must have an issuee). 5. **Expands on I2I:** It is a *superset* of I2I. If an I2I relationship is valid, a DI2I relationship would also be valid. However, DI2I also allows for valid issuers who are delegates of the far node's issuee
📝 SUMMARY
---
ACDC Edges (e section) link ACDCs, with Edge Operators defining relationship rules. The r (rules) section adds another layer for embedding machine-readable logic or legal prose.
• I2I (Issuer-To-Issuee): Use when the current ACDC's issuer's authority stems directly from being the subject (issuee) of the linked ACDC. Signifies direct authority. Example: A manager (issuee of "Manager" ACDC) issues project access.
• NI2I (Not-Issuer-To-Issuee): Use for referencing contextual or supporting ACDCs where the current issuer's authority doesn't derive from being the subject of the linked ACDC. Example: An "Employee Skill" ACDC linking to an external "Training Certificate" ACDC.
• DI2I (Delegated-Issuer-To-Issuee): Use when the current ACDC's issuer is either the subject of the linked ACDC or a formally recognized delegate of that subject. Allows for flexible, multi-step delegation. Example: A QC Supervisor (delegate of Plant GM) issues a "Batch Approved" ACDC pointing to the GM's "Plant Authority" ACDC.
[<- Prev (ACDC Presentation and Revocation)](101_70_ACDC_Presentation_and_Revocation.ipynb) | [Next (ACDC Chained Credentials I2I) ->](101_80_ACDC_Chained_Credentials_I2I.ipynb) # ACDC Issuance with KLI: Issuer-To-Issuee
🎯 OBJECTIVE

---

Demonstrate how to issue chained Authentic Chained Data Containers (ACDCs) using an Issuer-To-Issuee (I2I) edge relationship with the KERI Command Line Interface (KLI).

It also illustrates how to embed a simple rule within an ACDC. We will implement the "Endorsement for Building Access" scenario.

## Scenario Recap: Endorsement for Building Access Remember, the I2I operator enforces successive parent-child relationships across a chain of credential holders where the parent issuer of the current credential must be the child of the prior credential, if it has a parent. This is a strict constraint. Who enforces this strict constraint? Verifiers do, and usually within a set of rules for a credential ecosystem similar to how the vLEI Ecosystem Governance Framework (EGF) specifies the kind of credentials and their relationships to one another. This notebook focuses on the practical KLI commands for implementing an `I2I` chained credential scenario. For a detailed theoretical explanation of ACDC Edges, Edge Operators, and Rules, please refer to the "[Advanced ACDC Features: Edges, Edge Operators, and Rules](101_75_ACDC_Edges_and_Rules.ipynb)" notebook. To summarize this scenario: - **ACME Corp** issues a "Role Credential" to an Employee. - The **Employee**, by virtue of their "Role Credential", issues an "Access Credential" to a **Sub-contractor**. - The **Access Credential** contains an `I2I` edge linking back to the Employee's "Role Credential", signifying that the Employee's authority to grant access is derived from their managerial role. - The **Access Credential** will also include a simple textual rule regarding its usage policy. ## Initial Setup: Keystores, AIDs, Registries, and OOBIs As usual, it is necessary to set up our participants: - Acme Corporation (`acme_aid`): The initial, or root, authority in this scenario, responsible for issuing the top level Role Credential. - Employee (`employee_aid`): This participant will first receive the Role Credential from Acme and subsequently issue the Access Credential. - Sub-contractor (`subcontractor_aid`): The recipient of the Access Credential. For each participant: - Initialize their respective keystores. - Incept their Autonomic Identifiers (AIDs). These AIDs will be configured as transferable and will utilize the default witness setup from `keystore_init_config.json`. - Establish OOBI connections. This involves generating OOBIs for each AID and resolving them to ensure all necessary participants (Acme-Employee, Employee-Sub-contractor) can securely discover each other. For ACME and the Employee: - Incept a credential registry ```python # Imports and Utility functions from scripts.utils import exec, clear_keri, pr_title, pr_message, pr_continue from scripts.saidify import get_schema_said import json, os clear_keri() # ACME Keystore and AID acme_keystore_name = "acme_ks" acme_salt = exec("kli salt") acme_aid_alias = "acme" acme_registry_name = "acme_mgr_registry" # Employee Keystore and AID employee_keystore_name = "employee_ks" employee_salt = exec("kli salt") employee_aid_alias = "employee" employee_registry_name = "employee_access_registry" # Sub-contractor Keystore and AID subcontractor_keystore_name = "subcontractor_ks" subcontractor_salt = exec("kli salt") subcontractor_aid_alias = "subcontractor" pr_title("Initializing keystores") !kli init --name {acme_keystore_name} \ --nopasscode \ --salt {acme_salt} \ --config-dir ./config \ --config-file keystore_init_config.json !kli init --name {employee_keystore_name} \ --nopasscode \ --salt {employee_salt} \ --config-dir ./config \ --config-file keystore_init_config.json !kli init --name {subcontractor_keystore_name} \ --nopasscode \ --salt {subcontractor_salt} \ --config-dir ./config \ --config-file keystore_init_config.json pr_title("Initializing AIDs") !kli incept --name {acme_keystore_name} \ --alias {acme_aid_alias} \ --file ./config/aid_inception_config.json # Uses witnesses and transferable settings !kli incept --name {employee_keystore_name} \ --alias {employee_aid_alias} \ --file ./config/aid_inception_config.json !kli incept --name {subcontractor_keystore_name} \ --alias {subcontractor_aid_alias} \ --file ./config/aid_inception_config.json pr_title("Initializing Credential Registries") !kli vc registry incept --name {acme_keystore_name} \ --alias {acme_aid_alias} \ --registry-name {acme_registry_name} !kli vc registry incept --name {employee_keystore_name} \ --alias {employee_aid_alias} \ --registry-name {employee_registry_name} acme_aid_prefix = exec(f"kli aid --name {acme_keystore_name} --alias {acme_aid_alias}") employee_aid_prefix = exec(f"kli aid --name {employee_keystore_name} --alias {employee_aid_alias}") subcontractor_aid_prefix = exec(f"kli aid --name {subcontractor_keystore_name} --alias {subcontractor_aid_alias}") pr_message(f"ACME AID: {acme_aid_prefix}") pr_message(f"Employee AID: {employee_aid_prefix}") pr_message(f"Sub-contractor AID: {subcontractor_aid_prefix}") pr_title("Generating and resolving OOBIs") # ACME and Employee OOBI Exchange acme_oobi = exec(f"kli oobi generate --name {acme_keystore_name} --alias {acme_aid_alias} --role witness") employee_oobi = exec(f"kli oobi generate --name {employee_keystore_name} --alias {employee_aid_alias} --role witness") !kli oobi resolve --name {acme_keystore_name} \ --oobi-alias {employee_aid_alias} \ --oobi {employee_oobi} !kli oobi resolve --name {employee_keystore_name} \ --oobi-alias {acme_aid_alias} \ --oobi {acme_oobi} # Employee and Sub-contractor OOBI Exchange subcontractor_oobi = exec(f"kli oobi generate --name {subcontractor_keystore_name} --alias {subcontractor_aid_alias} --role witness") !kli oobi resolve --name {employee_keystore_name} \ --oobi-alias {subcontractor_aid_alias} \ --oobi {subcontractor_oobi} !kli oobi resolve --name {subcontractor_keystore_name} \ --oobi-alias {employee_aid_alias} \ --oobi {employee_oobi} pr_message("OOBI connections established.") pr_continue() ``` Proceeding with deletion of '/usr/local/var/keri/' without confirmation. ✅ Successfully removed: /usr/local/var/keri/ Initializing keystores KERI Keystore created at: /usr/local/var/keri/ks/acme_ks KERI Database created at: /usr/local/var/keri/db/acme_ks KERI Credential Store created at: /usr/local/var/keri/reg/acme_ks Loading 3 OOBIs... http://witness-demo:5642/oobi/BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha/controller?name=Wan&tag=witness succeeded http://witness-demo:5643/oobi/BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM/controller?name=Wes&tag=witness succeeded http://witness-demo:5644/oobi/BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX/controller?name=Wil&tag=witness succeeded KERI Keystore created at: /usr/local/var/keri/ks/employee_ks KERI Database created at: /usr/local/var/keri/db/employee_ks KERI Credential Store created at: /usr/local/var/keri/reg/employee_ks Loading 3 OOBIs... http://witness-demo:5642/oobi/BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha/controller?name=Wan&tag=witness succeeded http://witness-demo:5643/oobi/BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM/controller?name=Wes&tag=witness succeeded http://witness-demo:5644/oobi/BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX/controller?name=Wil&tag=witness succeeded KERI Keystore created at: /usr/local/var/keri/ks/subcontractor_ks KERI Database created at: /usr/local/var/keri/db/subcontractor_ks KERI Credential Store created at: /usr/local/var/keri/reg/subcontractor_ks Loading 3 OOBIs... http://witness-demo:5642/oobi/BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha/controller?name=Wan&tag=witness succeeded http://witness-demo:5643/oobi/BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM/controller?name=Wes&tag=witness succeeded http://witness-demo:5644/oobi/BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX/controller?name=Wil&tag=witness succeeded Initializing AIDs Waiting for witness receipts... Prefix EPRQCgop2CyHCC8tabtl9iJOw1ryr2eXofO6IF7NQtQ- Public key 1: DH8BuO089xEDuARHaXAq4V9Uqv2w7Pz4wBnb4AM9ojSa Waiting for witness receipts... Prefix EGKtnumYK9aJ0aKtX6WS8TPcVt2W8tYrlTbFwvX9T-IB Public key 1: DC3EVHqOWepm_r3wN33_IOlrNKsAuza6o0HLjMJdpdYn Waiting for witness receipts... Prefix ECfW_ag06odaG2HgGqggnP697j17ZU7nM3dRb4ixpc9B Public key 1: DA9-YlRY7pXgaaKlhkppFTAZ88r4v68ooNc8s-FuW5hc Initializing Credential Registries Waiting for TEL event witness receipts Sending TEL events to witnesses Registry: acme_mgr_registry(EONNB-EvoWMm7aXTQpFDsN7hGCk-ZvRQEzdd0AZxox2r) created for Identifier Prefix: EPRQCgop2CyHCC8tabtl9iJOw1ryr2eXofO6IF7NQtQ- Waiting for TEL event witness receipts Sending TEL events to witnesses Registry: employee_access_registry(ECBgjw1OO2ZVr4U0_513HpnyRNtXmCBQ-UIY-ttC0n1Y) created for Identifier Prefix: EGKtnumYK9aJ0aKtX6WS8TPcVt2W8tYrlTbFwvX9T-IB ACME AID: EPRQCgop2CyHCC8tabtl9iJOw1ryr2eXofO6IF7NQtQ- Employee AID: EGKtnumYK9aJ0aKtX6WS8TPcVt2W8tYrlTbFwvX9T-IB Sub-contractor AID: ECfW_ag06odaG2HgGqggnP697j17ZU7nM3dRb4ixpc9B Generating and resolving OOBIs http://witness-demo:5642/oobi/EGKtnumYK9aJ0aKtX6WS8TPcVt2W8tYrlTbFwvX9T-IB/witness resolved http://witness-demo:5642/oobi/EPRQCgop2CyHCC8tabtl9iJOw1ryr2eXofO6IF7NQtQ-/witness resolved http://witness-demo:5642/oobi/ECfW_ag06odaG2HgGqggnP697j17ZU7nM3dRb4ixpc9B/witness resolved http://witness-demo:5642/oobi/EGKtnumYK9aJ0aKtX6WS8TPcVt2W8tYrlTbFwvX9T-IB/witness resolved OOBI connections established. You can continue ✅ ## Schema Definitions We need two ACDC schemas as shown below. The non-metadata attributes are also shown below: - Role Schema (`role_schema.json`): For the credential ACME issues to the Employee. - Attributes - `roleTitle` - `department` - Access Schema (`access_schema.json`): For the credential the Employee issues to the Sub-contractor. This schema will include definitions for an `e` (edges) section to specify the I2I link and an `r` (rules) section. - Attributes - `buildingId` - `accessLevel` - Edges - `manager_endorsement` (points to Role Schema ACDC)
ℹ️ NOTE
---
For this notebook,the schemas have been SAIDified and made available on a schema server (a simple webserver hosting schema files as JSON). The SAIDification process was covered in the "SAIDifying ACDC Schemas" notebook. ### Role Schema This schema defines the structure of the "Role Credential." It has a structure that is rather similar to the other schemas presented so far during the training: - Filename: `role_schema.json` (content shown SAIDified) ```python role_schema_path = "config/schemas/role_schema.json" pr_title(f"Schema: {role_schema_path}") role_schema_said = get_schema_said(role_schema_path) pr_message(f"Schema SAID: {role_schema_said}") pr_message(f"Retrieving Role Schema from Server:") !curl -s http://vlei-server:7723/oobi/{role_schema_said} | jq pr_continue() ``` Schema: config/schemas/role_schema.json Schema SAID: ENWatfUaeryBqvGnG7VdILVcqk84_eoxmiaJYguJXaRw Retrieving Role Schema from Server: { "$id": "ENWatfUaeryBqvGnG7VdILVcqk84_eoxmiaJYguJXaRw", "$schema": "http://json-schema.org/draft-07/schema#", "title": "RoleCredential", "description": "Credential signifying a role within an organization.", "type": "object", "credentialType": "RoleCredential", "version": "1.0.0", "properties": { "v": { "description": "Credential Version String", "type": "string" }, "d": { "description": "Credential SAID", "type": "string" }, "u": { "description": "One time use nonce", "type": "string" }, "i": { "description": "Issuer AID", "type": "string" }, "ri": { "description": "Registry SAID", "type": "string" }, "s": { "description": "Schema SAID", "type": "string" }, "a": { "oneOf": [ { "description": "Attributes block SAID", "type": "string" }, { "$id": "EFmgKWjhXaH2MYUmlNy5-t8Y6SHZ0InHriOkyAnI4777", "description": "Attributes block", "type": "object", "properties": { "d": { "description": "Attributes data SAID", "type": "string" }, "i": { "description": "Issuee AID (Employee's AID)", "type": "string" }, "dt": { "description": "Issuance date time", "type": "string", "format": "date-time" }, "roleTitle": { "description": "The title of the role.", "type": "string" }, "department": { "description": "The department the employee belongs to.", "type": "string" } }, "additionalProperties": false, "required": [ "d", "i", "dt", "roleTitle", "department" ] } ] } }, "additionalProperties": false, "required": [ "v", "d", "i", "ri", "s", "a" ] } You can continue ✅ ### Access Schema This schema defines the "Access Credential". It includes an `e` (edges) section for the `I2I` link to the Role Credential and an `r` (rules) section for a usage policy. Filename: `access_schema.json` (content shown SAIDified) ```python access_schema_path = "config/schemas/access_schema.json" pr_title(f"Schema: {access_schema_path}") access_schema_said = get_schema_said(access_schema_path) pr_message(f"Schema SAID: {access_schema_said}") pr_message(f"Retrieving Access Schema from Server:") !curl -s http://vlei-server:7723/oobi/{access_schema_said} | jq pr_continue() ``` Schema: config/schemas/access_schema.json Schema SAID: EF2zX3g5YDyHMSjgsK4OayZMFmLRMxcAJfW363JhBOfD Retrieving Access Schema from Server: { "$id": "EF2zX3g5YDyHMSjgsK4OayZMFmLRMxcAJfW363JhBOfD", "$schema": "http://json-schema.org/draft-07/schema#", "title": "AccessCredential", "description": "Credential granting access to a specific building or area, endorsed by a manager.", "type": "object", "credentialType": "AccessCredential", "version": "1.0.0", "properties": { "v": { "description": "Credential Version String", "type": "string" }, "d": { "description": "Credential SAID", "type": "string" }, "u": { "description": "One time use nonce", "type": "string" }, "i": { "description": "Issuer AID (Employee's AID)", "type": "string" }, "ri": { "description": "Registry SAID", "type": "string" }, "s": { "description": "Schema SAID", "type": "string" }, "a": { "oneOf": [ { "description": "Attributes block SAID", "type": "string" }, { "$id": "EOxa7LAD2BoA9tk9n0CW4zH7nF91DP1g_Pjz1wC_FuNw", "description": "Attributes block", "type": "object", "properties": { "d": { "description": "Attributes data SAID", "type": "string" }, "i": { "description": "Issuee AID (Sub-contractor's AID)", "type": "string" }, "dt": { "description": "Issuance date time", "type": "string", "format": "date-time" }, "buildingId": { "description": "Identifier for the building access is granted to.", "type": "string" }, "accessLevel": { "description": "Level of access granted.", "type": "string" } }, "additionalProperties": false, "required": [ "d", "i", "dt", "buildingId", "accessLevel" ] } ] }, "e": { "oneOf": [ { "description": "Edges block SAID", "type": "string" }, { "$id": "EI8RvTM23u-pQDK-KpDUBWOKbiOW8fpnzktVVBCLy55N", "description": "Edges block", "type": "object", "properties": { "d": { "description": "Edges block SAID", "type": "string" }, "manager_endorsement": { "description": "Link to the Manager Credential that endorses this access", "type": "object", "properties": { "n": { "description": "Issuer credential SAID", "type": "string" }, "s": { "description": "SAID of required schema of the credential pointed to by this node", "type": "string", "const": "ENWatfUaeryBqvGnG7VdILVcqk84_eoxmiaJYguJXaRw" }, "o": { "description": "Operator indicating this node is the issuer", "type": "string", "const": "I2I" } }, "additionalProperties": false, "required": [ "n", "s", "o" ] } }, "additionalProperties": false, "required": [ "d", "manager_endorsement" ] } ] }, "r": { "oneOf": [ { "description": "Rules block SAID", "type": "string" }, { "$id": "EKDmqq14KgthMAV23sCbzgdFFjT-v9x01toUsyfyi2uU", "description": "Rules governing the use of this access credential.", "type": "object", "properties": { "d": { "description": "Rules block SAID", "type": "string" }, "usageDisclaimer": { "description": "Usage Disclaimer", "type": "object", "properties": { "l": { "description": "Associated legal language", "type": "string", "const": "This mock credential grants no actual access. For illustrative use only." } } } }, "additionalProperties": false, "required": [ "d", "usageDisclaimer" ] } ] } }, "additionalProperties": false, "required": [ "v", "d", "i", "ri", "s", "a", "e", "r" ] } You can continue ✅ ## Resolving Schema OOBIs All parties need to resolve the OOBIs for these schemas from the schema server to be able to either issue, receive, present, or receive presentations of credentials using these schemas. ```python pr_title("Resolving schema OOBIs") role_schema_oobi = f"http://vlei-server:7723/oobi/{role_schema_said}" access_schema_oobi = f"http://vlei-server:7723/oobi/{access_schema_said}" # ACME Corp !kli oobi resolve --name {acme_keystore_name} \ --oobi-alias "role_schema" --oobi {role_schema_oobi} !kli oobi resolve --name {acme_keystore_name} \ --oobi-alias "access_schema" --oobi {access_schema_oobi} # Employee !kli oobi resolve --name {employee_keystore_name} \ --oobi-alias "role_schema" --oobi {role_schema_oobi} !kli oobi resolve --name {employee_keystore_name} \ --oobi-alias "access_schema" --oobi {access_schema_oobi} # Sub-contractor !kli oobi resolve --name {subcontractor_keystore_name} \ --oobi-alias "role_schema" --oobi {role_schema_oobi} !kli oobi resolve --name {subcontractor_keystore_name} \ --oobi-alias "access_schema" --oobi {access_schema_oobi} pr_message("Schema OOBIs resolved.") pr_continue() ``` Resolving schema OOBIs http://vlei-server:7723/oobi/ENWatfUaeryBqvGnG7VdILVcqk84_eoxmiaJYguJXaRw resolved http://vlei-server:7723/oobi/EF2zX3g5YDyHMSjgsK4OayZMFmLRMxcAJfW363JhBOfD resolved http://vlei-server:7723/oobi/ENWatfUaeryBqvGnG7VdILVcqk84_eoxmiaJYguJXaRw resolved http://vlei-server:7723/oobi/EF2zX3g5YDyHMSjgsK4OayZMFmLRMxcAJfW363JhBOfD resolved http://vlei-server:7723/oobi/ENWatfUaeryBqvGnG7VdILVcqk84_eoxmiaJYguJXaRw resolved http://vlei-server:7723/oobi/EF2zX3g5YDyHMSjgsK4OayZMFmLRMxcAJfW363JhBOfD resolved Schema OOBIs resolved. You can continue ✅ ## Issuing credentials Now that the setup is complete and the schemas are available, its necessary to create the credential chain. ### Step 1: Role Credential Issuance The Keystores, AIDs, and Credential Registry for ACME Corporation were created during the initial setup. The next step is to create the credential that grants the "Engineering Manager" role to the employee. **ACME Creates Role Credential Data** Create a JSON file `role_cred_data.json` with the attributes for this specific credential ```python pr_title("Creating role credential data") !echo '{ \ "roleTitle": "Engineering Manager", \ "department": "Technology Innovations" \ }' > config/credential_data/role_cred_data.json !cat config/credential_data/role_cred_data.json | jq pr_continue() ``` Creating role credential data { "roleTitle": "Engineering Manager", "department": "Technology Innovations" } You can continue ✅ **ACME Issues Role Credential to Employee** Now that the credential data is in the file the next step is to create the credential with `!kli vc create` ```python pr_title("Creating Role credential") issue_time_acme = exec("kli time") !kli vc create --name {acme_keystore_name} \ --alias {acme_aid_alias} \ --registry-name {acme_registry_name} \ --schema {role_schema_said} \ --recipient {employee_aid_prefix} \ --data "@./config/credential_data/role_cred_data.json" \ --time {issue_time_acme} role_credential_said = exec(f"kli vc list --name {acme_keystore_name} --alias {acme_aid_alias} --issued --said --schema {role_schema_said}") pr_message(f"Role Credential SAID: {role_credential_said}") pr_continue() ``` Creating Role credential Waiting for TEL event witness receipts Sending TEL events to witnesses EEy7jb0V3U8MucFutlRulbQ9eIYWNDrm7Jsbuzg144aZ has been created. Role Credential SAID: EEy7jb0V3U8MucFutlRulbQ9eIYWNDrm7Jsbuzg144aZ You can continue ✅ **IPEX Transfer: ACME Grants, Engineering Manager Employee Admits Role Credential** Next, perform the IPEX transfer as done in previous ACDC issuance examples. Afterwards, the employee will have the role credential. ```python pr_title("Transferring credential (ipex grant)") time = exec("kli time") !kli ipex grant --name {acme_keystore_name} \ --alias {acme_aid_alias} \ --said {role_credential_said} \ --recipient {employee_aid_prefix} \ --time {time} pr_title("Admitting credential (ipex admit)") # Employee polls for the grant and admits it employee_grant_msg_said = exec(f"kli ipex list --name {employee_keystore_name} --alias {employee_aid_alias} --poll --said") time = exec("kli time") !kli ipex admit --name {employee_keystore_name} \ --alias {employee_aid_alias} \ --said {employee_grant_msg_said} \ --time {time} # Employee lists the received credential pr_message("\nEngineering Manager Employee received Role Credential:") !kli vc list --name {employee_keystore_name} \ --alias {employee_aid_alias} \ --verbose pr_continue() ``` Transferring credential (ipex grant) Sending message ECQY9YW7oFmRqOi2AJ1Mw69xtuBLTQc4-W37jbvKStgQ to EGKtnumYK9aJ0aKtX6WS8TPcVt2W8tYrlTbFwvX9T-IB ... grant message sent Admitting credential (ipex admit) Sending admit message to EPRQCgop2CyHCC8tabtl9iJOw1ryr2eXofO6IF7NQtQ- ... admit message sent Engineering Manager Employee received Role Credential: Current received credentials for employee (EGKtnumYK9aJ0aKtX6WS8TPcVt2W8tYrlTbFwvX9T-IB): Credential #1: EEy7jb0V3U8MucFutlRulbQ9eIYWNDrm7Jsbuzg144aZ Type: RoleCredential Status: Issued ✔ Issued by EPRQCgop2CyHCC8tabtl9iJOw1ryr2eXofO6IF7NQtQ- Issued on 2025-09-12T04:10:33.313202+00:00 Full Credential: { "v": "ACDC10JSON0001c2_", "d": "EEy7jb0V3U8MucFutlRulbQ9eIYWNDrm7Jsbuzg144aZ", "i": "EPRQCgop2CyHCC8tabtl9iJOw1ryr2eXofO6IF7NQtQ-", "ri": "EONNB-EvoWMm7aXTQpFDsN7hGCk-ZvRQEzdd0AZxox2r", "s": "ENWatfUaeryBqvGnG7VdILVcqk84_eoxmiaJYguJXaRw", "a": { "d": "EJZ5Ab5kkrz-hGU7-e5K7mV_LCpEFn1e1t7aNttCZwWu", "i": "EGKtnumYK9aJ0aKtX6WS8TPcVt2W8tYrlTbFwvX9T-IB", "dt": "2025-09-12T04:10:33.313202+00:00", "roleTitle": "Engineering Manager", "department": "Technology Innovations" } } You can continue ✅ ### Step 2: Access Credential Data properties - edge, rules, and attributes The Employee, now holding the "Role Credential", issues the "Access Credential" to the Sub-contractor. This new credential will link to the Role Credential via an `I2I` edge and include a "Usage Disclaimer" rule. For this it is necessary to create JSON files for the attributes (`access_cred_data.json`), the edge (`access_cred_edge.json`), and the rule (`access_cred_rule.json`). The attributes, edges, and rules properties are displayed below. #### Attributes Data The attributes of the Role Credential include generic mock data to represent an access claim such as `buildingId` and `accessLevel` with sample data provided below. ```python pr_message("Acces Credential Attributes") access_cred_data_file_path = "config/credential_data/access_cred_data.json" access_data = { "buildingId": "HQ-EastWing", "accessLevel": "Level 2 - Common Areas & Labs" } with open(access_cred_data_file_path, 'w') as f: json.dump(access_data, f, indent=4) !cat {access_cred_data_file_path} | jq ``` Acces Credential Attributes { "buildingId": "HQ-EastWing", "accessLevel": "Level 2 - Common Areas & Labs" } #### Edge Data and SAID Calculation When creating the Edge Data, the `manager_endorsement` edge is defined to link to the Role Credential ACDC by using the SAID of the Role Credential said, stored in the `role_credential_said` variable. The schema SAID `s` for this edge is the schema identifier, or SAID, of the Role Credential schema and is set to `role_schema_said`. The operator `o` is set to `I2I`. To make this edge block verifiable, the `!kli saidify --file` command is used. When this command is executed, KERI processes the JSON content of the specified file and calculates a Self-Addressing Identifier (SAID) for its entire content. Crucially, the command then modifies the input file in place: - It adds (or updates, if already present) a top-level field named `d` within the JSON structure of the file. - The value of this `d` field is set to the newly calculated SAID. ```python pr_message("Access Credential Edges") access_cred_edge_file_path = "config/credential_data/access_cred_edge.json" access_edge = { "d": "", "manager_endorsement": { "n": role_credential_said, "s": role_schema_said, "o": "I2I" } } with open(access_cred_edge_file_path, 'w') as f: json.dump(access_edge, f, indent=4) !kli saidify --file {access_cred_edge_file_path} !cat {access_cred_edge_file_path} | jq ``` Access Credential Edges { "d": "EKkr7dXYEw4HFBpppP36I4hNmR6F_0XOHwduQSMGYTRF", "manager_endorsement": { "n": "EEy7jb0V3U8MucFutlRulbQ9eIYWNDrm7Jsbuzg144aZ", "s": "ENWatfUaeryBqvGnG7VdILVcqk84_eoxmiaJYguJXaRw", "o": "I2I" } } #### Rule Data The rule section `usageDisclaimer` contains a simple legal disclaimer. Take notice that this data property is also SAIDified. ```python pr_message("Access Credential Rules") access_cred_rule_file_path = "config/credential_data/access_cred_rule.json" access_rule = { "d": "", "usageDisclaimer": { "l": "This mock credential grants no actual access. For illustrative use only." } } with open(access_cred_rule_file_path, 'w') as f: json.dump(access_rule, f, indent=4) !kli saidify --file {access_cred_rule_file_path} !cat {access_cred_rule_file_path} | jq ``` Access Credential Rules { "d": "EGVMk928-Fz4DK2NSvZgtG0JJrMlrpxvuxBKPvFxfPSQ", "usageDisclaimer": { "l": "This mock credential grants no actual access. For illustrative use only." } } ### Step 3: Employee Creates Access Credential for Sub-contractor Now, the Employee uses `kli vc create` with the attributes, SAIDified edges, and SAIDified rules files to issue the Access Credential. Notice the additional parameters `--edges` and `rules` to supply the data properties to the command. ```python time = exec("kli time") !kli vc create --name {employee_keystore_name} \ --alias {employee_aid_alias} \ --registry-name {employee_registry_name} \ --schema {access_schema_said} \ --recipient {subcontractor_aid_alias} \ --data "@./config/credential_data/access_cred_data.json" \ --edges "@./config/credential_data/access_cred_edge.json" \ --rules "@./config/credential_data/access_cred_rule.json" \ --time {time} access_credential_said = exec(f"kli vc list --name {employee_keystore_name} --alias {employee_aid_alias} --issued --said --schema {access_schema_said}") pr_message(f"Access Credential SAID: {access_credential_said}") pr_continue() ``` Waiting for TEL event witness receipts Sending TEL events to witnesses EA0-zXenxtqAZa5rjjCmxjAqhOVqFo-8WgqBmkvHUWEk has been created. Access Credential SAID: EA0-zXenxtqAZa5rjjCmxjAqhOVqFo-8WgqBmkvHUWEk You can continue ✅ ### Step 4: Employee Grants, Sub-contractor Admits Access Credential The commands below show using IPEX to both grant the Access Credential from the manager employee and to admit the Access Credential as the sub-contractor. Finally the sub-contractor's credentials are listed with `kli vc list` to show that the Access Credential has been received. ```python pr_title("Transferring Access Credential from Employee to Sub-contractor") time = exec("kli time") !kli ipex grant --name {employee_keystore_name} \ --alias {employee_aid_alias} \ --said {access_credential_said} \ --recipient {subcontractor_aid_prefix} \ --time {time} pr_title("Sub-contractor admitting Access Credential") # Sub-contractor polls for the grant and admits it subcontractor_grant_msg_said = exec(f"kli ipex list --name {subcontractor_keystore_name} \ --alias {subcontractor_aid_alias} --poll --said") time = exec("kli time") !kli ipex admit --name {subcontractor_keystore_name} \ --alias {subcontractor_aid_alias} \ --said {subcontractor_grant_msg_said} \ --time {time} # Sub-contractor lists the received credential pr_message("\nSub-contractor's received Access Credential:") !kli vc list --name {subcontractor_keystore_name} \ --alias {subcontractor_aid_alias} \ --verbose pr_continue() ``` Transferring Access Credential from Employee to Sub-contractor Sending message EJ6irfCsL-VdfLeX2g2QlqfB8cljJJjAFiF65C0o7kin to ECfW_ag06odaG2HgGqggnP697j17ZU7nM3dRb4ixpc9B ... grant message sent Sub-contractor admitting Access Credential Sending admit message to EGKtnumYK9aJ0aKtX6WS8TPcVt2W8tYrlTbFwvX9T-IB ... admit message sent Sub-contractor's received Access Credential: Current received credentials for subcontractor (ECfW_ag06odaG2HgGqggnP697j17ZU7nM3dRb4ixpc9B): Credential #1: EA0-zXenxtqAZa5rjjCmxjAqhOVqFo-8WgqBmkvHUWEk Type: AccessCredential Status: Issued ✔ Issued by EGKtnumYK9aJ0aKtX6WS8TPcVt2W8tYrlTbFwvX9T-IB Issued on 2025-09-12T04:10:52.883270+00:00 Full Credential: { "v": "ACDC10JSON000320_", "d": "EA0-zXenxtqAZa5rjjCmxjAqhOVqFo-8WgqBmkvHUWEk", "i": "EGKtnumYK9aJ0aKtX6WS8TPcVt2W8tYrlTbFwvX9T-IB", "ri": "ECBgjw1OO2ZVr4U0_513HpnyRNtXmCBQ-UIY-ttC0n1Y", "s": "EF2zX3g5YDyHMSjgsK4OayZMFmLRMxcAJfW363JhBOfD", "a": { "d": "EEnD2_uJHltlMdRJ_XZYE9YtutyPIwdYWlErX9JUeMol", "i": "ECfW_ag06odaG2HgGqggnP697j17ZU7nM3dRb4ixpc9B", "dt": "2025-09-12T04:10:52.883270+00:00", "buildingId": "HQ-EastWing", "accessLevel": "Level 2 - Common Areas & Labs" }, "e": { "d": "EKkr7dXYEw4HFBpppP36I4hNmR6F_0XOHwduQSMGYTRF", "manager_endorsement": { "n": "EEy7jb0V3U8MucFutlRulbQ9eIYWNDrm7Jsbuzg144aZ", "s": "ENWatfUaeryBqvGnG7VdILVcqk84_eoxmiaJYguJXaRw", "o": "I2I" } }, "r": { "d": "EGVMk928-Fz4DK2NSvZgtG0JJrMlrpxvuxBKPvFxfPSQ", "usageDisclaimer": { "l": "This mock credential grants no actual access. For illustrative use only." } } } You can continue ✅ The output for the Sub-contractor's received AccessCredential clearly shows: - The attributes (`a` section) for building access. - The edge (`e` section) with manager_endorsement linking to the RoleCredential's SAID (`n`) and using the `I2I` operator (`o`). - The rule (`r` section) with the `usageDisclaimer`.
📝 SUMMARY
---
This notebook demonstrated the creation of a chained ACDC relationship using an Issuer-To-Issuee (I2I) edge and the inclusion of a rule:
1. Initial Setup: Keystores, AIDs (ACME, Employee, Sub-contractor), and credential registries (for ACME and Employee) were initialized. OOBI connections were established between relevant parties.
2. Schema Preparation: Two schemas, role_schema.json (for ACME to Employee) and access_schema.json (for Employee to Sub-contractor), were defined. The access_schema.json included definitions for an e (edges) section and an r (rules) section. Both schemas were assumed to be SAIDified and resolvable via a schema server.
3. Role Credential Issuance (ACME to Employee):
   • ACME created data for the Role Credential.
   • ACME issued the Role Credential to the Employee's AID using kli vc create.
   • The Role Credential was transferred to the Employee via IPEX (kli ipex grant from ACME, kli ipex admit by Employee).
4. Access Credential Issuance (Employee to Sub-contractor):
   • The Employee created data for the Access Credential attributes.
   • A separate JSON file for the edge was created. This edge (manager_endorsement) pointed to the SAID of the Role Credential received by the Employee (role_credential_said), specified the Role Credential's schema SAID, and used the "o": "I2I" operator. This edge file was SAIDified using kli saidify --file, which populates its d field.
   • A separate JSON file for the rule (usageDisclaimer) was created and SAIDified using kli saidify --file.
   • The Employee issued the Access Credential to the Sub-contractor's AID using kli vc create, referencing the attributes data file, the SAIDified edge file (--edges), and the SAIDified rule file (--rules).
   • The Access Credential was transferred to the Sub-contractor via IPEX.
5. Verification: The Sub-contractor's received Access Credential clearly displayed the attributes, the I2I edge linking to the Employee's Role Credential, and the embedded rule.
This process illustrates how KERI and ACDC can model real-world endorsement scenarios where the authority to issue a credential is derived from another verifiable credential held by the issuer and how additional conditions can be embedded using rules.
[<- Prev (ACDC Edges and Rules)](101_75_ACDC_Edges_and_Rules.ipynb) | [Next (ACDC Chained Credentials NI2I) ->](101_85_ACDC_Chained_Credentials_NI2I.ipynb) # ACDC Issuance with KLI: Not-Issuer-To-Issuee 🎯 OBJECTIVE
---
Demonstrate how to issue an ACDC that utilizes a Not-Issuer-To-Issuee (NI2I) edge, illustrating how to reference another parent credential for context without implying the issuer of the child is the issuee of the linked parent ACDC. This notebook will also show how a rule can be embedded in the credential. We will implement the **"Linking to an External Training Course"** scenario.
ℹ️⚠️ BUG ALERT

---

Currently the NI2I operator does not work due to a bug. For more details on this and other issues, please see the Known Issues Section. The material will be updated once the bug is resolved. For now you can skip this notebook.

## Scenario Recap: Linking to an External Training Course This notebook focuses on the practical KLI commands for implementing an `NI2I` chained credentials. For a detailed theoretical explanation of ACDC Edges, Edge Operators, and Rules, please refer to the **[Advanced ACDC Features: Edges, Edge Operators, and Rules](101_75_ACDC_Edges_and_Rules.ipynb)** notebook. To summarize the scenario: - A Company issues a **"Skill Certified"** ACDC to an employee, after the employee completes an internal assessment. - To add verifiable, supporting context to this certification, the "Skill Certified" ACDC can contain an `NI2I` (Not-Issuer-To-Issuee) edge. This edge would point to a "Course Completion" ACDC that the employee had previously received from an external, third-party Training Provider. - This `NI2I` link signifies that while the external training is acknowledged as relevant evidence, the Company's authority to issue its own skill certification is independent and does not derive from the Training Provider's credential. - The "Employee Skill Certified" ACDC will also include a simple rule in its `r` section. ## Initial Setup: Keystores, AIDs, Registries, and OOBIs We begin by setting up the three participants in our scenario: - Training Provider (`training_provider_aid`): The entity issuing the course credential. - Company (`company_aid`): The entity issuing the skill credential that references the course credential. - Employee (`employee_aid`): The entity who is the subject (issuee) of both credentials. For each participant, we will: - Initialize a KERI keystore. - Incept an AID, using a default witness configuration. - Establish OOBI connections between the necessary parties (Training Provider ➡️ Employee, and Company ➡️ Employee) to enable secure communication. - For the two issuers (Training Provider and Company), we will also incept a credential registry to manage the lifecycle of the credentials they issue. ```python # Imports and Utility functions from scripts.utils import exec, clear_keri, pr_title, pr_message, pr_continue from scripts.saidify import get_schema_said import json, os clear_keri() # Training Provider Keystore and AID training_provider_keystore_name = "training_provider_ks" training_provider_salt = exec("kli salt") training_provider_aid_alias = "training_provider" training_provider_registry_name = "training_provider_reg" # Company Keystore and AID company_keystore_name = "company_ks" company_salt = exec("kli salt") company_aid_alias = "company" company_registry_name = "company_skill_reg" # Employee Keystore and AID employee_keystore_name = "employee_ks" employee_salt = exec("kli salt") employee_aid_alias = "employee" pr_title("Initializing keystores") !kli init --name {training_provider_keystore_name} \ --nopasscode \ --salt {training_provider_salt} \ --config-dir ./config \ --config-file keystore_init_config.json !kli init --name {company_keystore_name} \ --nopasscode \ --salt {company_salt} \ --config-dir ./config \ --config-file keystore_init_config.json !kli init --name {employee_keystore_name} \ --nopasscode \ --salt {employee_salt} \ --config-dir ./config \ --config-file keystore_init_config.json pr_title("Initializing AIDs") !kli incept --name {training_provider_keystore_name} \ --alias {training_provider_aid_alias} \ --file ./config/aid_inception_config.json !kli incept --name {company_keystore_name} \ --alias {company_aid_alias} \ --file ./config/aid_inception_config.json !kli incept --name {employee_keystore_name} \ --alias {employee_aid_alias} \ --file ./config/aid_inception_config.json pr_title("Initializing Credential Registries") !kli vc registry incept --name {training_provider_keystore_name} \ --alias {training_provider_aid_alias} \ --registry-name {training_provider_registry_name} !kli vc registry incept --name {company_keystore_name} \ --alias {company_aid_alias} \ --registry-name {company_registry_name} training_provider_aid_prefix = exec(f"kli aid --name {training_provider_keystore_name} --alias {training_provider_aid_alias}") company_aid_prefix = exec(f"kli aid --name {company_keystore_name} --alias {company_aid_alias}") employee_aid_prefix = exec(f"kli aid --name {employee_keystore_name} --alias {employee_aid_alias}") pr_message(f"Training Provider AID: {training_provider_aid_prefix}") pr_message(f"Company AID: {company_aid_prefix}") pr_message(f"Employee AID: {employee_aid_prefix}") pr_title("Generating and resolving OOBIs") # Training Provider and Employee OOBI Exchange training_provider_oobi = exec(f"kli oobi generate --name {training_provider_keystore_name} --alias {training_provider_aid_alias} --role witness") employee_oobi = exec(f"kli oobi generate --name {employee_keystore_name} --alias {employee_aid_alias} --role witness") company_oobi = exec(f"kli oobi generate --name {company_keystore_name} --alias {company_aid_alias} --role witness") !kli oobi resolve --name {training_provider_keystore_name} \ --oobi-alias {employee_aid_alias} \ --oobi {employee_oobi} !kli oobi resolve --name {employee_keystore_name} \ --oobi-alias {training_provider_aid_alias} \ --oobi {training_provider_oobi} # Company and Employee OOBI Exchange !kli oobi resolve --name {company_keystore_name} \ --oobi-alias {employee_aid_alias} \ --oobi {employee_oobi} !kli oobi resolve --name {employee_keystore_name} \ --oobi-alias {company_aid_alias} \ --oobi {company_oobi} # Company and Training Provider ----------------------------------- !kli oobi resolve --name {company_keystore_name} \ --oobi-alias {training_provider_aid_alias} \ --oobi {training_provider_oobi} !kli oobi resolve --name {training_provider_keystore_name} \ --oobi-alias {company_aid_alias} \ --oobi {company_oobi} pr_message("OOBI connections established.") pr_continue() ``` ## Schema Definitions For this scenario, we require two distinct ACDC schemas: - **Course Completion Schema** (' course_completion_schema.json' ): Defines the credential issued by the Training Provider. - **Employee Skill Schema** (' employee_skill_schema.json'): Defines the credential issued by the Company, which will include the `NI2I` edge and a rule.
ℹ️ NOTE
---
For this notebook, the schemas have been pre-SAIDified and are available on our mock schema server. The process of SAIDifying schemas was detailed in a previous notebook.
### Course Completion Schema This schema defines a basic credential for certifying the completion of a training course. It's a standard, non-chained credential. Filename: `course_completion_schema.json` ```python course_schema_path = "config/schemas/course_completion_schema.json" pr_title(f"Schema: {course_schema_path}") course_schema_said = get_schema_said(course_schema_path) pr_message(f"Schema SAID: {course_schema_said}") pr_message(f"Retrieving Schema from Server:") !curl -s http://vlei-server:7723/oobi/{course_schema_said} | jq pr_continue() ``` ### Employee Skill Schema This schema defines the credential issued by the Company to the Employee. It includes an `e` (edges) section with an `NI2I` operator to reference the "Course Completion" credential and an `r` (rules) section for a verification policy. Filename: `employee_skill_schema.json` ```python skill_schema_path = "config/schemas/skill_certified_schema.json" pr_title(f"Schema: {skill_schema_path}") skill_schema_said = get_schema_said(skill_schema_path) pr_message(f"Schema SAID: {skill_schema_said}") pr_message(f"Retrieving Schema from Server:") !curl -s http://vlei-server:7723/oobi/{skill_schema_said} | jq pr_continue() ``` ## Resolving Schema OOBIs All three participants must resolve the OOBIs for both schemas to ensure they can understand and validate the credentials. ```python pr_title("Resolving schema OOBIs") course_schema_oobi = f"http://vlei-server:7723/oobi/{course_schema_said}" skill_schema_oobi = f"http://vlei-server:7723/oobi/{skill_schema_said}" # Participants resolving Course Completion Schema !kli oobi resolve --name {training_provider_keystore_name} \ --oobi-alias "course_schema" \ --oobi {course_schema_oobi} !kli oobi resolve --name {company_keystore_name} \ --oobi-alias "course_schema" \ --oobi {course_schema_oobi} !kli oobi resolve --name {employee_keystore_name} \ --oobi-alias "course_schema" \ --oobi {course_schema_oobi} # Participants resolving Employee Skill Schema !kli oobi resolve --name {training_provider_keystore_name} \ --oobi-alias "skill_schema" \ --oobi {skill_schema_oobi} !kli oobi resolve --name {company_keystore_name} \ --oobi-alias "skill_schema" \ --oobi {skill_schema_oobi} !kli oobi resolve --name {employee_keystore_name} \ --oobi-alias "skill_schema" \ --oobi {skill_schema_oobi} pr_message("Schema OOBIs resolved.") pr_continue() ``` ## Issuing credentials Now that the setup is complete and the schemas are available, it's necessary to create the credential chain starting with the Course Completion credential and later the Employee Skill credential. ### Step 1: Course Completion Credential Issuance (Training Provider to Employee) First, the Training Provider issues the "Course Completion" credential to the Employee. This establishes the base credential that will be referenced later. **Create Course Completion Credential Data** Create a JSON file with the specific attributes for the course completion. ```python pr_title("Creating Course Completion credential data") !echo '{ \ "courseName": "Advanced Cryptographic Systems", \ "courseLevel": "Expert", \ "completionDate": "2024-09-15" \ }' > config/credential_data/course_cred_data.json !cat config/credential_data/course_cred_data.json | jq pr_continue() ``` ### Training Provider Issues Credential The Training Provider uses `kli vc create` to issue the credential. ```python pr_title("Creating Course Completion credential") issue_time_training = exec("kli time") !kli vc create --name {training_provider_keystore_name} \ --alias {training_provider_aid_alias} \ --registry-name {training_provider_registry_name} \ --schema {course_schema_said} \ --recipient {employee_aid_prefix} \ --data "@./config/credential_data/course_cred_data.json" \ --time {issue_time_training} course_credential_said = exec(f"kli vc list --name {training_provider_keystore_name} --alias {training_provider_aid_alias} --issued --said --schema {course_schema_said}") pr_message(f"Course Credential SAID: {course_credential_said}") pr_continue() ``` **IPEX Transfer: Training Provider Grants, Employee Admits** The credential is then transferred to the Employee using the standard IPEX grant/admit flow. ```python pr_title("Transferring Course Completion credential (IPEX)") time = exec("kli time") !kli ipex grant --name {training_provider_keystore_name} \ --alias {training_provider_aid_alias} \ --said {course_credential_said} \ --recipient {employee_aid_prefix} \ --time {time} # Employee polls for the grant and admits it print("Polling mailboxes for IPEX Grant messages to admit...") employee_grant_msg_said = exec(f"kli ipex list --name {employee_keystore_name} --alias {employee_aid_alias} --poll --said") time = exec("kli time") !kli ipex admit --name {employee_keystore_name} \ --alias {employee_aid_alias} \ --said {employee_grant_msg_said} \ --time {time} pr_message("\nEmployee's received Course Completion Credential:") !kli vc list --name {employee_keystore_name} \ --alias {employee_aid_alias} \ --verbose pr_continue() ``` ### Step 2: Employee Skill Credential Issuance (Company to Employee) Now, the Company issues the "Employee Skill Certified" credential, which will link to the one the Employee just received. Create Data Properties for Skill Credential We need to create three separate JSON files for the attributes, the NI2I edge, and the rule. **Attributes Data** Generic mock data to represent an access claim. ```python pr_message("Employee Skill Credential Attributes") skill_cred_data_file_path = "config/credential_data/skill_cred_data.json" skill_data = { "skillName": "Secure System Design", "skillLevel": "Proficient", "assessmentDate": "2025-01-20" } with open(skill_cred_data_file_path, 'w') as f: json.dump(skill_data, f, indent=4) !cat {skill_cred_data_file_path} | jq ``` **Edge Data (NI2I) and SAIDification** The edge data is created, linking to the `course_credential_said` obtained in the previous step. The operator `o` is explicitly set to `NI2I`. This file is then SAIDified using `kli saidify` to populate its `d` field. ```python pr_message("Employee Skill Credential Edges (NI2I)") skill_cred_edge_file_path = "config/credential_data/skill_cred_edge.json" skill_edge = { "d": "", "supporting_evidence": { "n": course_credential_said, "s": course_schema_said, "o": "NI2I" } } with open(skill_cred_edge_file_path, 'w') as f: json.dump(skill_edge, f, indent=4) !kli saidify --file {skill_cred_edge_file_path} !cat {skill_cred_edge_file_path} | jq ``` **Rule Data and SAIDification** The rule data is created and SAIDified. ```python pr_message("Employee Skill Credential Rules") skill_cred_rule_file_path = "config/credential_data/skill_cred_rule.json" skill_rule = { "d": "", "verification_policy": { "l": "Verification of this skill certification requires checking the validity of supporting evidence." } } with open(skill_cred_rule_file_path, 'w') as f: json.dump(skill_rule, f, indent=4) !kli saidify --file {skill_cred_rule_file_path} !cat {skill_cred_rule_file_path} | jq ``` #### Company Issues Skill Credential The Company now creates the chained credential using kli vc create, supplying the attributes, edges, and rules files. ```python time = exec("kli time") !kli vc create --name {company_keystore_name} \ --alias {company_aid_alias} \ --registry-name {company_registry_name} \ --schema {skill_schema_said} \ --recipient {employee_aid_prefix} \ --data "@./config/credential_data/skill_cred_data.json" \ --edges "@./config/credential_data/skill_cred_edge.json" \ --rules "@./config/credential_data/skill_cred_rule.json" \ --time {time} skill_credential_said = exec(f"kli vc list --name {company_keystore_name} --alias {company_aid_alias} --issued --said --schema {skill_schema_said}") pr_message(f"Employee Skill Credential SAID: {skill_credential_said}") pr_continue() ``` ### Step 3: Company Grants, Employee Admits Skill Credential The final step is to transfer the newly created chained credential to the Employee. ```python pr_title("Transferring Employee Skill Credential from Company to Employee") time = exec("kli time") !kli ipex grant --name {company_keystore_name} \ --alias {company_aid_alias} \ --said {skill_credential_said} \ --recipient {employee_aid_prefix} \ --time {time} pr_title("Employee admitting Skill Credential") # Employee polls for the grant and admits it employee_skill_grant_msg_said = exec(f"kli ipex list --name {employee_keystore_name} --alias {employee_aid_alias} --poll --said") time = exec("kli time") !kli ipex admit --name {employee_keystore_name} \ --alias {employee_aid_alias} \ --said {employee_skill_grant_msg_said} \ --time {time} pr_message("\nEmployee's received Employee Skill Credential:") !kli vc list --name {employee_keystore_name} --alias {employee_aid_alias} --said {skill_credential_said} --verbose pr_continue() ``` When you view the final "Employee Skill Credential" held by the Employee, you will see: - The attributes (`a` section) for the certified skill. - The edge (`e` section) with `supporting_evidence` linking to the Course Completion ACDC's SAID (n) and using the `NI2I` operator (`o`). - The rule (`r` section) with the `verification_policy`. This confirms the successful creation and issuance of a chained credential using an NI2I edge to provide external, verifiable context.
📝 SUMMARY
---
This notebook demonstrated the creation of a chained ACDC relationship using a Not-Issuer-To-Issuee (NI2I) edge and the inclusion of a rule.
1. Setup: Three participants (Training Provider, Company, Employee) were initialized with keystores, AIDs, and credential registries for the issuers. OOBI connections were established between them.
2. Schema Preparation: Two schemas, one for "Course Completion" and another for "Skill Certified" (which included definitions for e and r sections), were resolved by all parties from a schema server.
3. Base Credential Issuance (Training Provider to Employee):
   • The Training Provider issued a "Course Completion" ACDC to the Employee.
   • This credential was transferred via IPEX and admitted by the Employee. The SAID of this credential was saved for the next step.
4. Chained Credential Issuance (Company to Employee):
   • The Company prepared the data for the "Employee Skill" ACDC.
   • An edge file was created, linking to the previously issued "Course Completion" ACDC's SAID and explicitly using the "o": "NI2I" operator. This file was SAIDified.
   • A rule file was created with a custom policy and was also SAIDified.
   • The Company issued the "Employee Skill" ACDC using kli vc create, supplying the attributes, edges, and rules files.
   • This second credential was transferred to the Employee via IPEX.
5. Verification: The final ACDC held by the Employee contained the skill attributes, the NI2I edge pointing to the course certificate as supporting evidence, and the embedded verification policy rule, successfully demonstrating the NI2I use case.
```python # from scripts.saidify import process_schema_file # # Run the saidify script # process_schema_file("./config/schemas/course_completion_schema.bak.json", "./config/schemas/course_completion_schema.json", True) # process_schema_file("./config/schemas/skill_certified_schema.bak.json", "./config/schemas/skill_certified_schema.json", True) ``` [<- Prev (ACDC Chained Credentials I2I)](101_80_ACDC_Chained_Credentials_I2I.ipynb) | [Next (KERIA Signify) ->](102_05_KERIA_Signify.ipynb) # Introducing KERIA and Signify: Architecture and Concepts
🎯 OBJECTIVE
---
Introduces the foundational concepts of KERIA and Signify TS, focusing on:
• The KERIA/Signify client-agent architecture.
• Key KERIA endpoint interfaces.
• The concept of Endpoint Role records (End Roles).
• The relationship between Client AIDs and Agent AIDs.
• What SignifyTS and SignifyPy are.
## Edge Signing Client - Agent Architecture KERI is a protocol for secure, self-certifying identifiers. **KERIA** is an implementation of the multi-tenant server portion of the Signify agent protocol for KERI agents and is designed to run as a service (e.g., in the cloud or self-hosted) that manages AIDs on behalf of a controller. **Signify TS** is a TypeScript library implementing the edge signing client protocol. It acts as an edge signing client, enabling applications to interact with a KERIA agent. **Signify Py** is a Python library implementing the edge client protocol of the Signify and KERIA protocol. What does edge signing mean? It means that all of the cryptographic keypairs only ever exist at the edge, in memory, within the application that uses a Signify library. Keys existing at the edge provides security and confidence that only the person possessing the passcode, or cryptographic seed, is the one performing signing. The phrase "edge" is used to indicate that the Signify libraries are used in person-facing applications. The idea behind this client-agent architecture is to enable "signing at the edge". Your sensitive private keys, used for signing key events and other data, remain on the client-side (managed by a Signify client library). The KERIA agent, running remotely, handles tasks like: * Storing key indexes (retrieved by the Signify Client on boot up) * Creating KERI AIDs delegated from the edge AID * Managing Key Event Logs (KELs) for edge AIDs * Creating, storing, issuing, revoking, presenting, and receiving ACDCs * Acting as a cloud mailbox to send and receive KERI and ACDC messages from * Interacting with witnesses * Exchanging messages with other KERI agents The KERIA agent itself never has access to your private keys. All critical signing operations happen on the client, and the signed events are then sent to the KERIA agent for processing and dissemination. This architecture separates key management and signing authority (client-side) from the operational aspects of maintaining AIDs' KELs and ACDCs and their availability (agent-side). ### KERIA Deployment and Configuration In a typical deployment, KERIA starts up and loads its configuration, including a list of default witnesses (or OOBI URLs) and ACDC schemas, from a JSON configuration file (e.g., **[keria configuration file](config/keria/keria-docker.json)**). This allows the agent to be pre-configured with a set of witnesses and connections to any other KERI AID that any AIDs created on that KERIA server are preconfigured to see. ## Agent Service Endpoints A KERIA service instance exposes distinct HTTP endpoints to handle different types of interactions: 1. **Boot Interface** (`boot port`, e.g., 3903 by default): * **Purpose**: Used for the initial setup and provisioning of a KERIA agent worker for a Signify client. This is where the client and agent establish their initial secure relationship. * **Interaction**: The Signify client sends its client AID's inception event to this endpoint to request the creation of a delegated agent AID. * **Accessibility**: Often restricted to internal infrastructure or disabled if agents are pre-configured (static worker mode). 2. **Admin Interface** (`admin port`, e.g., 3901 by default): * **Purpose**: This is the primary REST API for the Signify client to command and control its KERIA agent. * **Interaction**: Used for operations like creating new AIDs, rotating keys, issuing credentials, resolving OOBIs, etc. All requests to this interface must be authenticated (e.g., signed by the Client AID). * **Accessibility**: Typically exposed externally to allow the client to manage its AIDs. 3. **KERI Protocol Interface** (`http port`, e.g., 3902 by default): * **Purpose**: Handles standard KERI protocol messages (e.g., KELs, receipts, challenges) exchanged with other KERI agents and witnesses in the wider KERI network. * **Interaction**: Facilitates multi-sig coordination, credential revocation, KEL exchange, etc., using CESR (Composable Event Streaming Representation) over HTTP. * **Accessibility**: Exposed externally to enable interaction with the global KERI ecosystem. This separation of interfaces enhances security and deployment flexibility. ## Understanding Endpoint Role Records An **endpoint role record**, or "end role" for short, in KERI is an authorization that one AID grants to itself or another AID to act in a particular role representing a specific capacity to act on its behalf. Think of it as assigning a specific job to itself or another identifier. For instance, when a Signify client connects to a KERIA agent, the **Client AID** (controlled by the user or application) delegates authority to an **Agent AID** (managed by the KERIA service). The Client AID essentially authorizes its Agent AID to perform certain KERI operations in its name, like anchoring its KEL with witnesses or responding to discovery requests. Declaring an end role typically involves creating a KERI event, often an interaction event (`ixn`) or an establishment event (`icp` or `rot`) with specific configuration (`c` field) or an `end` role event, that specifies: * The AID granting the authorization (the delegator or authorizer). * The AID receiving the authorization (the delegate or authorized party). * The specific role being granted (e.g., `agent`, `witness`, `watcher`, `controller`, `mailbox`). This signed authorization will either be recorded in the KEL of the authorizing AID to make the role assignment verifiable by anyone who can access and validate that KEL or it will be stored locally for transmission when the key event log is requested through OOBI exchange or when it is sent directly from a given AID. ### Example of endpoint role in action The end role records are necessary to enable specific permissions within the internal KERI communication system. For example, an agent AID having been assigned the role of `agent` for a given delegator, the Signify controller AID, allows messages for the controlling AID to be sent through the authorized agent AID. ## Client and Agent AIDs Explained When you use Signify TS to connect to a KERIA agent, two primary AIDs are involved: 1. **Client AID**: * This is an AID that *you* (or your application) control directly via the Signify TS client. * It is a single signature AID. * You hold its private keys. * It's typically a transferable AID, allowing for key rotation. * It acts as the **delegator** to the Agent AID. * The rotation key index for this client AID is stored encrypted in the KERIA agent that the client pairs with. 2. **Agent AID**: * This AID is created and managed by the KERIA service *on your behalf* when the request to the `/boot` endpoint is made with the Client AID's inception event. * Its inception event specifies the Client AID as its delegator (`di` field in the inception event). This means the Agent AID's authority to act is derived from, and anchored to, your Client AID. * It's also typically a transferable AID. * The KERIA service uses this Agent AID to perform actions for your Client AID, such as acting as a communication proxy to interact with witnesses or other agents, without needing direct access to your Client AID's private keys. The Signify client generates the Client AID and sends its inception event to the KERIA agent's Boot Interface (on `/boot`). The KERIA service then creates the delegated Agent AID and returns its inception event to the client. Finally, the Signify client approves this delegation by sending an interaction event back to the KERIA agent's Admin Interface. This delegation model is fundamental to KERIA's security: your primary controlling keys (for the Client AID) remain "at the edge," while the KERIA agent operates with a delegated authority (via the Agent AID) that is always traceable back to your Client AID. ## SignifyTS and SignifyPy - Signify Client Libraries There are currently two Signify protocol client library implementations, one in Typescript and one in Python. [SignifyTS](https://github.com/WebOfTrust/signify-ts) is the Typescript implementation whereas [SignifyPy](https://github.com/WebOfTrust/signifypy) is the Python implementation. The most up-to-date implementation is SignifyTS and is recommended to be used. SignifyPy would be usable with a modest amount of upgrade effort. A Rust client, [scir](https://github.com/WebOfTrust/scir) was started yet is currently mostly unfinished and should not be used. ### SignifyTS, or Signify TS SignifyTS, also referred to as "signify-ts", is the Typescript implementation of the Signify client protocol and may be found at https://github.com/WebOfTrust/signify-ts. ### SignifyPy, or Signify Py SignifyPy, also known as "sigpy", is the Python implementation of the Signify client protocol and was the original implementation of Signify and was used to drive initial creation of the KERIA server side of the Signify protocol. It may be found at https://github.com/WebOfTrust/signifypy.
📝 SUMMARY

---

The KERIA/Signify architecture enables "signing at the edge," where a Signify client (like Signify TS) manages private keys and signing operations locally, while a remote KERIA agent handles ACDC storage, witness interactions, and KERI protocol communications. KERIA exposes three main HTTP endpoints:

• Boot Interface: For initial client-agent provisioning and creation of a delegated Agent AID.
• Admin Interface: A REST API for the client to command and control its agent (e.g., create AIDs, rotate keys).
• KERI Protocol Interface: For standard KERI message exchange with other agents and witnesses.

Endpoint role records, end roles, in KERI define verifiable authorizations for one AID to act in a specific capacity for another (e.g., an Agent AID acting in the 'agent' role for a Client AID).

The connection process involves a Client AID (controlled by the user via Signify) delegating authority to an Agent AID (managed by KERIA).

SignifyTS and SignifyPy comprise the two implementations of the Signify client protocol that are usable with the recommendation being to use SignifyTS.

[<- Prev (ACDC Chained Credentials NI2I)](101_85_ACDC_Chained_Credentials_NI2I.ipynb) | [Next (KERIA Signify Basic Operations) ->](102_10_KERIA_Signify_Basic_Operations.ipynb) # Signify TS Basics: Client Setup and AID Management
🎯 OBJECTIVE
---
Introduce basic operations using the typescript implementation of Signify, Signify TS: creating a client, initializing (booting) an agent, connecting to an agent, and creating an Autonomic Identifier (AID).

1. Initialize the library with await ready().
2. Create a SignifyClient instance, providing the agent's Admin and Boot URLs, a unique 21-character bran (passcode/salt for key derivation), and a security Tier.
3. For the first-time connection with a new bran, call await client.boot() to provision the Client AID and request the creation of a delegated Agent AID from KERIA.
4. Call await client.connect() to and retrieve the state of the Client and Agent AIDs and, on first invocation, complete any delegation approvals. The Client AID delegates authority to the Agent AID, whose inception event (type dip) will list the Client AID as its delegator.
5. For subsequent connections using the same bran, skip client.boot() and directly use client.connect().