Skip to content

Commit 1cf8913

Browse files
MonolithicMonkMonolithicMonk
authored
Create ReuseConnection.md (openwallet-foundation#3534)
* Create ReuseConnection.md Document how developers can leverage acapy's reuse connection feature Signed-off-by: Yuki I <[email protected]> * Update example events object to be consistent Signed-off-by: Yuki I <[email protected]> --------- Signed-off-by: Yuki I <[email protected]> Signed-off-by: Yuki I <[email protected]>
1 parent 9997135 commit 1cf8913

File tree

1 file changed

+130
-0
lines changed

1 file changed

+130
-0
lines changed

‎docs/features/ReuseConnection.md

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# Reusing Connections Between Agents
2+
3+
Leverage ACA‑Py's Out‑of‑Band (OOB) protocol to reuse existing connections instead of creating new ones for every interaction.
4+
5+
---
6+
7+
## Quick Start
8+
9+
*For developers who want code now*
10+
11+
### 1. Generate a Reusable Invitation
12+
13+
Use the following API call to create an invitation that supports connection reuse. Note that the invitation must include a resolvable DID (e.g., `did:peer:2`) in its `services` field. This is achieved by setting the `use_did_method` parameter.
14+
15+
```bash
16+
curl -X POST 'http://your-agent-admin:8031/out-of-band/create-invitation?auto_accept=true&multi_use=true' \
17+
-H 'accept: application/json' \
18+
-H 'Content-Type: application/json' \
19+
-H 'Authorization: Bearer YOUR_API_KEY' \
20+
-d '{
21+
"handshake_protocols": ["https://didcomm.org/didexchange/1.1"],
22+
"protocol_version": "1.1",
23+
"use_did_method": "did:peer:2"
24+
}'
25+
```
26+
27+
### 2. Verify the Response
28+
29+
Ensure that the response contains a `services` array with a resolvable DID:
30+
31+
```json
32+
{
33+
"state": "initial",
34+
"trace": false,
35+
"invi_msg_id": "ffaf017e-3980-45b7-ad43-a90a609d6eaf",
36+
"oob_id": "ed7cc3f6-62cd-4b53-9285-534c198a8476",
37+
"invitation": {
38+
"@type": "https://didcomm.org/out-of-band/1.1/invitation",
39+
"@id": "ffaf017e-3980-45b7-ad43-a90a609d6eaf",
40+
"label": "First invitation to Barry",
41+
"imageUrl": "https://example-image.com",
42+
"handshake_protocols": [
43+
"https://didcomm.org/didexchange/1.1"
44+
],
45+
"services": [
46+
"did:peer:2.Vz6MkqRYqQiSgvZQdnBytw86Qbs2ZWUkGv22od935YF4s8M7"
47+
]
48+
},
49+
"invitation_url": "https://example-admin.com?oob=example-1-invite-encoded-url"
50+
}
51+
```
52+
53+
### 3. Reuse the Connection
54+
55+
When an invitee scans subsequent invitations that contain the **same DID**, ACA‑Py automatically sends a `reuse` message instead of creating a new connection.
56+
57+
---
58+
59+
## Key Concepts
60+
61+
### What Enables Connection Reuse?
62+
63+
1. **Resolvable DID**
64+
- The invitation’s `services` array **must** include a resolvable DID (e.g., `did:peer:2` or `did:peer:4`), as specified by the `use_did_method` parameter.
65+
- *Do not use inline or non‑resolvable DIDs (e.g., `did:key`).*
66+
67+
2. **Consistent DID Across Invitations**
68+
- The inviter (e.g., the issuer) must reuse the same resolvable DID in subsequent invitations where reuse is desired. This consistency is enforced by setting `use_did_method` to `did:peer:2` (or `did:peer:4`) in the API call.
69+
70+
3. **Protocol Version**
71+
- Use `didexchange/1.1` (avoid the legacy `1.0`).
72+
73+
#### Critical API Parameters
74+
75+
| Parameter | Description |
76+
|----------------------|------------------------------------------------------------------|
77+
| `use_did_method` | Set to `did:peer:2` or `did:peer:4` (required for reuse). |
78+
| `multi_use` | Optional but recommended for enabling multi‑use invitations. |
79+
| `handshake_protocols`| Must include `https://didcomm.org/didexchange/1.1`. |
80+
81+
---
82+
83+
## Handling Reuse Events
84+
85+
When a connection is reused, ACA-Py automatically emits an event notification. This event contains the `connection_id` of the reused connection, allowing applications to track reuse activity programmatically.
86+
87+
### Example Event Notification
88+
89+
```json
90+
{
91+
"thread_id": "096cf986-9211-450c-9cbb-a6d701c4d9ca",
92+
"connection_id": "28818825-98a3-44c7-b1cc-d429c1583a1d",
93+
"comment": "Connection 28818825-98a3-44c7-b1cc-d429c1583a1d is being reused for invitation 6f6af313-3735-4ac1-b972-aafebd3731bc"
94+
}
95+
```
96+
97+
### Listening for Reuse Events
98+
99+
Applications can subscribe to these events via the WebSocket or webhooks event stream provided by ACA-Py. To listen for reuse events:
100+
101+
1. Connect to the ACA-Py WebSocket server or setup a webhook endpoint.
102+
2. Filter events with `type=connection_reuse`.
103+
3. Handle the event in your application logic.
104+
105+
---
106+
107+
## Troubleshooting
108+
109+
| **Symptom** | **Likely Cause** | **Solution** |
110+
|--------------------------------------------|--------------------------------------------|---------------------------------------------------------------------------------------|
111+
| New connection created instead of reused | Invitation uses a non‑resolvable DID, `use_did_method` not set | Set `use_did_method=did:peer:2` (or `did:peer:4`) in the `/out-of-band/create-invitation` call. |
112+
| `reuse` message not sent | Invitee agent doesn’t support OOB v1.1 | Ensure both agents are using `didexchange/1.1`. |
113+
| DID resolution failed | The resolver does not support the chosen DID | Configure a DID resolver that supports the selected peer DID method. |
114+
115+
---
116+
117+
## Demo vs. Production
118+
119+
| **Scenario** | **Approach** |
120+
|--------------|------------------------------------------------------------------------------|
121+
| **Demo** | Use CLI flags such as `--reuse-connections`. |
122+
| **Production**| Rely on API parameters (`use_did_method`, `multi_use`) for reuse events. |
123+
124+
---
125+
126+
**Contributor Note:**
127+
Tested with BC Wallet & Hologram apps. Reuse functionality has been confirmed to work with `did:peer:2` (see [Issue #3532](https://github.com/hyperledger/aries-cloudagent-python/issues/3532)).
128+
129+
For more information on Qualified DIDs (e.g., `did:peer:2`, `did:peer:4`), visit the [Qualified DIDs Documentation](https://aca-py.org/latest/features/QualifiedDIDs/).
130+

0 commit comments

Comments
 (0)