owned this note
owned this note
Published
Linked with GitHub
# KERI Agent Events
### Resolve witness OOBI
Request:
```
Method: GET
URL: http://127.0.0.1:5642/oobi/BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha/controller
Headers:
Accept-Encoding: identity
```
Response: 200 OK
```
Headers:
Keri-Aid: BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha
Content-Type: application/json+cesr
Body:
{
"v":"KERI10JSON0000fd_",
"t":"icp",
"d":"EIkO4CUmYXukX4auGU9yaFoQaIicfVZkazQ0A3IO5biT",
"i":"BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha",
"s":"0",
"kt":"1",
"k":["BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha"],
"nt":"0",
"n":[],
"bt":"0",
"b":[],
"c":[],
"a":[]
}
-VAn-AABAAAMlb78gUo1_gPDwxbXyERk2sW8B0mtiNuACutAygnY78PHYUjbPj1fSY1jyid8fl4-TXgLXPnDmeoUs1UO-H0A-EAB0AAAAAAAAAAAAAAAAAAAAAAA1AAG2023-03-11T15c07c30d373004p00c00
```
Comments:
The agent resolves the OOBI by fetching the content on the OOBI URL. A fresh witness responds with its not-transferable inception event with the signature attached. Note that witness identifier is `Ed25519N` that means non-transferable, also next keys `n=[]`. The agent can validate the signature with the public key in `k`.
The attached signature can be decoded with Petteri's [cesr-decoder](https://psteniusubi.github.io/cesr-decoder/)
If the witness is already engaged with an agent, it responds with signed reply messages like this:
```
{
"v":"KERI10JSON0000fa_",
"t":"rpy",
"d":"EPmdCbzUWGwXjEgCurknKvaUu1fcWcSeViaMb1iMZQyT",
"dt":"2023-03-13T22:14:03.148773+00:00",
"r":"/loc/scheme",
"a":
{
"eid":"BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha",
"scheme":"http",
"url":"http://127.0.0.1:5642/"
}
}
-VAi-CABBBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha0BDG6OfRGemLDqWgn2TGWJaRjBL296mgQvYi0i7w6T9Q4P7_1ZyTV20KZyPtGfPakuVfbIDDD4pD66_W9GI6vpAH
{
"v":"KERI10JSON0000f8_",
"t":"rpy",
"d":"EBcVo6jC6JLcRg_fha28gcnxAZdB2j6LesjmVIfQ-jkW",
"dt":"2023-03-13T22:14:03.149176+00:00",
"r":"/loc/scheme",
"a":
{
"eid":"BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha",
"scheme":"tcp",
"url":"tcp://127.0.0.1:5632/"
}
}
-VAi-CABBBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha0BB27EwfQNd0eXvTGZEoSEcF9-5qDnH6cMuS1HQwGNs8YmgRHwC1TmMRXizaDIhy4pxZs1uhls6QvaJyUDdfFJEF
{
"v":"KERI10JSON000116_",
"t":"rpy",
"d":"EOXcYtHEmAvxG_IQyqtgY7LgzORofoMQbL21h_sx-6nj",
"dt":"2023-03-13T22:14:03.149430+00:00",
"r":"/end/role/add",
"a":
{
"cid":"BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha",
"role":"controller",
"eid":"BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha"
}
}
-VAi-CABBBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha0BDIX9_W78Vs-w6RWhW3c9A_Q1Pe8VxBlpk2hPTCyzVPwKzSkgPgFZI7eBKeMWDizgk_4AhIeyL8nZjqYSD185IJ
```
The first two reply messages have route `r` as `/loc/scheme` and authorize the witness own URL for both http and tcp schemes.
The third message has `/end/role/add` route with a `controller` role that authorizes its AID as the endpoint AID (`eid`) controller (??)
Another example is an OOBI that resolves an AID from one of it's witnesses such as
`http://127.0.0.1:5642/oobi/EHOuGiHMxJShXHgSb6k_9pqxmRb8H-LT0R2hQouHp8pW/witness/BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha`
The response would be:
```
{
"v":"KERI10JSON0000fa_",
"t":"rpy",
"d":"EGWvQOL-xIZru-BCAvx69IjzZRD8VeQ6THSpyzrsAniW",
"dt":"2023-03-14T22:51:37.536003+00:00",
"r":"/loc/scheme",
"a":{
"eid":"BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha",
"scheme":"http",
"url":"http://127.0.0.1:5642/"
}
}
-VAi-CABBBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha0BDRpe7xcfDPGIb6RLhBXfEBN25KR0dIsFTCfdwokBTXRVZlFBlB6Q_H1id6n56gxIN7P9WPpr6JHoWdlJQwhFwN
{
"v":"KERI10JSON0000f8_",
"t":"rpy",
"d":"EAX3jKwqStO-mMFqxnQy_C3_fZB5miImYXlWY6t4Mzcx",
"dt":"2023-03-14T22:51:37.536651+00:00",
"r":"/loc/scheme",
"a":{
"eid":"BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha",
"scheme":"tcp",
"url":"tcp://127.0.0.1:5632/"
}
}
-VAi-CABBBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha0BDvAGhvTUBZRA_hXYQjhd94nWsZwedovUADw2X44xAlqCKpwJG9k1aXLMBhwpPa61-SibWXk14J_0vb0z3oevEF
{
"v":"KERI10JSON0001b7_",
"t":"icp",
"d":"EHOuGiHMxJShXHgSb6k_9pqxmRb8H-LT0R2hQouHp8pW",
"i":"EHOuGiHMxJShXHgSb6k_9pqxmRb8H-LT0R2hQouHp8pW",
"s":"0",
"kt":"1",
"k":["DJCVOtOyP7o_v6gxPrbVHObD_X0NHjc2zhwEJtGnXDlw"],
"nt":"1",
"n":["ECzrNYsnysWcajWzylefFH034TwwfjQVGO06mwfrsUWN"],
"bt":"3",
"b":[
"BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha",
"BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM",
"BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX"
],
"c":[],
"a":[]
}
-VBq-AABAADEydz1JaHAIG-KATag0wGMcsUbzBJOV13mZN82DOzKN2w0pLvKIhL6bWYiKFneky-ganyY33Aa377ElqNnalMK-BADAADMTM-okssnvhPvcUvoUEYhCadJ68Lcpzvg4nFr9dCNdto7kcFHNxvQ6-0ZSetzjAtdPyzjT6fxAydXd9FiR5IKABBLjwkx_7d5QTWNsIRGm9CJST1S0oRfg86Qjv636z_PueljFcgb5_VsK9yshMN3dR6zfRLdlvpKerEreD9eUCQMACBvMxF_bym9gqIw-9WgWTJurVdGFjSB1rUVlRbSFVdtYl7srvuID3wBMXFKgtWQybn9L_IxiwAu8VqG5i6U0cwG-EAB0AAAAAAAAAAAAAAAAAAAAAAA1AAG2023-03-14T22c49c09d097993p00c00
```
where the last message is the inception event `icp` of the AID witnessed where the witness was designated, and the attached signatures of the AID, all of its witnesses and the first seen reply.
Reference: [OOBI protocol](https://weboftrust.github.io/ietf-oobi/draft-ssmith-oobi.html)
### Inception events (icp)
Request:
```
Method: POST
URL: http://127.0.0.1:5642/
Headers:
Accept-Encoding: identity
Content-Type: application/json+cesr
Cesr-Attachment: -AABAABkNUS8JbgmyeuNctdkwP_V8EAPopFVnJlHOl5JtDFdBq61XrvVkjZ9nI6nXlNCTVqZp2sCOU1gGKK3ifMIEWYA..
Body:
{
"v":"KERI10JSON0001b7_",
"t":"icp",
"d":"ECnv2wyPiqHZpQs0hBAdezfv5STL2_2kn4zdvlsLIZLZ",
"i":"ECnv2wyPiqHZpQs0hBAdezfv5STL2_2kn4zdvlsLIZLZ",
"s":"0",
"kt":"1",
"k":["DMFNxtGkQpIFcbN7CaGMcYZ5p8gYZEFct61rLCrMlWI9"],
"nt":"1",
"n":["EAjpIYShtFcPKi_BA1nXOOydLpLeyyWLXXd3pSmitl15"],
"bt":"2",
"b":[
"BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha",
"BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM",
"BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX"
],
"c":[],
"a":[]
}
```
Response: 204 No Content
Comments:
The agent transmits the inception event to the witness that acknoledge it with a 204 response.
Note the `Cesr-Attachment` has the agent signatures (?can not decode: `CESR decode failed: Error: getTextFrame code={"table":"CesrSchemaCodeTable(SmallCounter)","value":"-AAB","selector":"-A","type":"-A","digits":"AB","typeName":"ControllerIdxSigs","count":1}`)
### Reply event (rpy)
Request:
```
Method: POST
URL: http://127.0.0.1:5642/
Headers:
Accept-Encoding: identity
Content-Type: application/json+cesr
Cesr-Attachment: -VAi-CABBLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM0BCfL3_HgkgSqvhWiV9KX-W5Vr-g2PYSgzTV-zVg-cEY-UVunblu4U8xSIDvJ1jre7F_fKvzHvo5DtYRkqVC2jYE
Body:
{
"v":"KERI10JSON0000f8_",
"t":"rpy",
"d":"ECIyaixyavVnZxzi4XpXkgjcI7oIu1_dk84M6vZYgqKO",
"dt":"2023-03-11T15:55:45.038866+00:00",
"r":"/loc/scheme",
"a":
{
"eid":"BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM",
"scheme":"tcp",
"url":"tcp://127.0.0.1:5633/"
}
}
```
Response: 204 No Content
Comments:
Seems that those messages are generated to populate witnesses oobis. I'm still trying to understand the code. Two messages are sent per witness with the oobi of each witness (and signature attached in header).
In his case, the `a` field is for witneas "wil"
`eid` is AID of "wil"
`url` is endopoint of "wil" with the TCP port (not the http port). No communication found on that port.
The header `Cesr-Attachment` has the signature of the witness "wil". Can be decoded with Petteri’s [cesr-decoder](https://psteniusubi.github.io/cesr-decoder/)
### Query mailbox event (qry)
Request:
```
Method: POST
URL: http://127.0.0.1:5642/
Headers:
Accept-Encoding: identity
Content-Type: application/json+cesr
Connection: close
Cesr-Attachment: -VAj-HABECnv2wyPiqHZpQs0hBAdezfv5STL2_2kn4zdvlsLIZLZ-AABAACI_IazDkxHyDDXEenwXCkdHCUti_T9NXUYT0iRwboCd0Ii9xwjcGIvdbcgQgWCc4OsxBH78jZvYysJW7BJRrUE
Body:
{
"v":"KERI10JSON000162_",
"t":"qry",
"d":"EN3bKzUKO0Gvl0DLcaBnurh4fE6OnyucbhkFhOeE7CV7",
"dt":"2023-03-11T15:56:20.288847+00:00",
"r":"mbx",
"rr":"",
"q":
{
"pre":"ECnv2wyPiqHZpQs0hBAdezfv5STL2_2kn4zdvlsLIZLZ",
"topics":{
"/receipt":0,
"/replay":0,
"/reply":0
},
"i":"ECnv2wyPiqHZpQs0hBAdezfv5STL2_2kn4zdvlsLIZLZ",
"src":"BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha"
}
}
```
Response: 200 OK + continuation (server sent events)
```
Headers:
Content-Type: text/event-stream
Connectin: close
Body: (chunked)
id: 0
event: /receipt
retry: 5000
data:
{
"v":"KERI10JSON000091_",
"t":"rct",
"d":"ECnv2wyPiqHZpQs0hBAdezfv5STL2_2kn4zdvlsLIZLZ",
"i":"ECnv2wyPiqHZpQs0hBAdezfv5STL2_2kn4zdvlsLIZLZ",
"s":"0"
}
-CABBBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha0BCUJsCj9PDWCZp_oW-8t3QvaKG89Q810gyJ-WWUWJkjuPEz7wjnoz-np41PaiDlysKYqyBF9cu5Efev3RxS8wYP
```
Comments:
The agent query the witness mailbox for given `topics`. Signature of the message is in header `Cesr-Attachment`
The witness reply messages as SSE (Server Sent Event). In this case, the receipt for the `icp` event is sent.
What the `0` means in `"/receipt":0`? Is the `/` needed? (compare with query for `topic: challenge`)
Another response example for `/credential` topic:
```
id: 0
event: /credential
retry: 5000
data: {
"v": "KERI10JSON000113_",
"t": "vcp",
"d": "ELw_zhgTtyCXPeTrvXu7o-2uWnNXj9O5vZBdazFR6Jy2",
"i": "ELw_zhgTtyCXPeTrvXu7o-2uWnNXj9O5vZBdazFR6Jy2",
"ii": "EHOuGiHMxJShXHgSb6k_9pqxmRb8H-LT0R2hQouHp8pW",
"s": "0",
"c": [
"NB"
],
"bt": "0",
"b": [],
"n": "ANpIxpMejRmVNvOIOBNyCL2RSS-bdGW2Xp0OUvYcQivn"
}
-VAS-GAB0AAAAAAAAAAAAAAAAAAAAAABED5MZs5Tys3SNFzalHDGgnhnLHqsisTUxefJNC0UCQAq
id: 1
event: /credential
retry: 5000
data: {
"v": "KERI10JSON0000ed_",
"t": "iss",
"d": "ENuT-4Q0CvuWjqzsVGTMpA8TZWTc_KFYuUHCKt7R1D-K",
"i": "EMRss_ldmuZKyV4Vr-4MjrjPznNy4I0GgsNvsJVjg1KG",
"s": "0",
"ri": "ELw_zhgTtyCXPeTrvXu7o-2uWnNXj9O5vZBdazFR6Jy2",
"dt": "2023-03-15T01:05:06.012976+00:00"
}
-VAS-GAB0AAAAAAAAAAAAAAAAAAAAAACEGHhiagt3XKf4xTN6aXIfcNKB_e2gRFRUHi9e5s6yJKo
```
### Receipt event (rct)
Request:
```
Method: POST
URL: http://127.0.0.1:5642/
Headers:
Accept-Encoding: identity
Content-Type: application/json+cesr
Cesr-Attachment: -BACABAlR2AN41HPRebu6mDarGJYk0hCbquos2X6FoXsLLS_qoGHHUJFgEhB0_wNYzOjHsF5HiEUjcCW_nzPvFX_cjsEACAnUjOqUtohn2kYPPeSi_2FLArFF13hgSSHdPu7DG-iuoE9o7G8zmCOfo9XpeuEMb2VydGm713mkI2hJgXpqrMD
Body:
{
"v":"KERI10JSON000091_",
"t":"rct",
"d":"ECnv2wyPiqHZpQs0hBAdezfv5STL2_2kn4zdvlsLIZLZ",
"i":"ECnv2wyPiqHZpQs0hBAdezfv5STL2_2kn4zdvlsLIZLZ",
"s":"0"
}
```
Response 200 OK
```
Headers:
Content-Type: application/json
```
Comments:
The body of this message is the receipt received from the witness in the mailbox query. The CESR attachment seems to have two witness signatures (from the other two witnesses), so the intent of the message may be to pupulate receipt from the other witnesses.
### Forward Exchange event (challenge)
Request:
```
Method: POST
URL: http://127.0.0.1:5642/
Headers:
Accept-Encoding: identity
Content-Type: application/json+cesr
Connection: close
Cesr-Attachment: -HABEASywhO9nIo0uYs5Sobn-wJ-Un5WeKjDu6wuvRJ8xQTp-AABAABqxQTuIRkLlv2a-3UdmQh21IL7Qtr0_iF0NIJur_Fdgp89OSXq7fvQBs6RovpA1k_UDv33Tq5v-91IaKKJN_oP-LAl5AABAA-a-HABEASywhO9nIo0uYs5Sobn-wJ-Un5WeKjDu6wuvRJ8xQTp-AABAAASy2SwdP-86IatH_nYxSDysRyW_dn4RWckjAntdrX13gJ2pcFqmAzxr2nxNuWHRR-ve0rifFo8SaDhXwBe2T8P
Body:
{
"v":"KERI10JSON00021d_",
"t":"exn",
"d":"EIIaMxfuu22lb2w6Z4L0DOS4gw-1kWjpVjaS-Hatxk42",
"dt":"2023-03-11T20:44:32.943588+00:00",
"r":"/fwd",
"q":
{
"pre":"EK6A2xNiwzLUEGqZcmwIXl1KPSh9JrJiDLgnhart_Kqu",
"topic":"challenge"
},
"a":
{
"v":"KERI10JSON000140_",
"t":"exn",
"d":"EDaW7h-Rb29ZyrC-9ubWEa-4DWvh1p4K1UnEiKH8mFNZ",
"dt":"2023-03-11T20:44:32.905664+00:00",
"r":"/challenge/response",
"a":
{
"i":"EASywhO9nIo0uYs5Sobn-wJ-Un5WeKjDu6wuvRJ8xQTp",
"words": ["apology","armed","erode","shell","gossip","snow","okay","chaos","public","shift","pause","daughter"]
}
}
}
```
Response: 204 No content
Comments:
This is a peer to peer echange message wrapping passing a forward (`/fwd`) that wraps a `/challenge/response` message to be stored in the mailbox of the witness for the final destination.
### Forward Exchange event (credential)
Request:
```
Method: POST
URL: http://127.0.0.1:5642/
Headers:
Accept-Encoding: identity
Content-Type: application/json+cesr
Connection: close
Cesr-Attachment: -HABEHOuGiHMxJShXHgSb6k_9pqxmRb8H-LT0R2hQouHp8pW-AABAAD3L27lj-4HBEzD-MzI7prqlZxKcdH2WVKy0uisPKS5PwmVaM-jebYolJqFEozuPYNtzuWYQ49W02s1_7q-V44F-LAV5AABAA-a-VAS-GAB0AAAAAAAAAAAAAAAAAAAAAABED5MZs5Tys3SNFzalHDGgnhnLHqsisTUxefJNC0UCQAq
{
"v": "KERI10JSON0001f1_",
"t": "exn",
"d": "EO-4kjImKqxzm1eaQ5O1RFiKV0gDk47EfEHui-6Nl1vv",
"dt": "2023-03-15T01:05:08.026702+00:00",
"r": "/fwd",
"q": {
"pre": "EHMnCf8_nIemuPx-cUHaDQq8zSnQIFAurdEpwHpNbnvX",
"topic": "credential"
},
"a": {
"v": "KERI10JSON000113_",
"t": "vcp",
"d": "ELw_zhgTtyCXPeTrvXu7o-2uWnNXj9O5vZBdazFR6Jy2",
"i": "ELw_zhgTtyCXPeTrvXu7o-2uWnNXj9O5vZBdazFR6Jy2",
"ii": "EHOuGiHMxJShXHgSb6k_9pqxmRb8H-LT0R2hQouHp8pW",
"s": "0",
"c": [
"NB"
],
"bt": "0",
"b": [],
"n": "ANpIxpMejRmVNvOIOBNyCL2RSS-bdGW2Xp0OUvYcQivn"
}
}
```
Response: 204 No content
### Interaction event (vc registy)
Request:
```
Method: POST
URL: http://127.0.0.1:5642/
Headers:
Accept-Encoding: identity
Content-Type: application/json+cesr
Cesr-Attachment: -AABAAAzNlwOuyFnQp7NXyyGNf8EcwlmGsBekxQeUVTLRsxwTK9aYtPrStgMa5L10hvaA882Q80MQAN9YL6OAJ6_6FEN
Body:
{
"v": "KERI10JSON00013a_",
"t": "ixn",
"d": "ED5MZs5Tys3SNFzalHDGgnhnLHqsisTUxefJNC0UCQAq",
"i": "EHOuGiHMxJShXHgSb6k_9pqxmRb8H-LT0R2hQouHp8pW",
"s": "1",
"p": "EHOuGiHMxJShXHgSb6k_9pqxmRb8H-LT0R2hQouHp8pW",
"a": [
{
"i": "ELw_zhgTtyCXPeTrvXu7o-2uWnNXj9O5vZBdazFR6Jy2",
"s": "0",
"d": "ELw_zhgTtyCXPeTrvXu7o-2uWnNXj9O5vZBdazFR6Jy2"
}
]
}
```
Response: 204 No content continuation
### VC issue event (iss)
Request:
```
Method: POST
URL: http://127.0.0.1:5642/
Headers:
Accept-Encoding: identity
Content-Type: application/json+cesr
Cesr-Attachment: -VAS-GAB0AAAAAAAAAAAAAAAAAAAAAACEGHhiagt3XKf4xTN6aXIfcNKB_e2gRFRUHi9e5s6yJKo
Body:
{
"v": "KERI10JSON0000ed_",
"t": "iss",
"d": "ENuT-4Q0CvuWjqzsVGTMpA8TZWTc_KFYuUHCKt7R1D-K",
"i": "EMRss_ldmuZKyV4Vr-4MjrjPznNy4I0GgsNvsJVjg1KG",
"s": "0",
"ri": "ELw_zhgTtyCXPeTrvXu7o-2uWnNXj9O5vZBdazFR6Jy2",
"dt": "2023-03-15T01:05:06.012976+00:00"
}
```
Response: 204 No content continuation
---
### Event Types:
* icp = incept, inception
* rot = rotate, rotation
* ixn = interact, interaction
* dip = delcept, delegated inception
* drt = deltate, delegated rotation
* rct = receipt
* ksn = state, key state notice
* qry = query
* rpy = reply
* exn = exchange
* exp = expose, sealed data exposition
* vcp = vdr incept, verifiable data registry inception
* vrt = vdr rotate, verifiable data registry rotation
* iss = vc issue, verifiable credential issuance
* rev = vc revoke, verifiable credential revocation
* bis = backed vc issue, registry-backed transaction event log credential issuance
* brv = backed vc revoke, registry-backed transaction event log credential revocation
### Mailbox topics
* challenge
* receipt
* replay
* reply
* replay
* multisig
* delegate
* credential
* oobi
* notification
### HTTP headers
* Content-Type: application/json+cesr
* Connection: close
* Keri-Aid
* Cesr-Attachment
Petteri's [cesr-decoder](https://psteniusubi.github.io/cesr-decoder/)