Relationships

Relationships, formerly known as the address book - but that had limited functionality -, refer to the connections registered between different entities, such as addresses to Virtual Asset Service Providers (VASPs), originators to VASPs, and more. These relationships help manage and track associations within the network.

The SafeConnect Relationships API can be used for managing relationships between DIDs. Relationships can be used to express a connection between an agent and another agent or party (e.g. originator, beneficiary).

Relationships are always in one of the following states:

Some existing use cases for relationships are:

• Prove that the intended beneficiary to a transaction controls a blockchain wallet address to ensure the transaction reaches its intended beneficiary
• Prove that a known party controls a blockchain wallet address for KYC and Sanctions Screening purposes
• Prove that an Agent controls a blockchain wallet address to ensure the exchange of PII to the correct agent in the context of a Travel Rule compliant transaction

What operations can I perform on Relationships?

As a compliance officer, you can perform the following operations:

• Register a Relationship: Create a new relationship between two or more entities
• Patch a Relationship: Update the status, e.g. to ‘Confirmed’ by you.
  • Provide Proof to a Relationship - especially targeting wallet ownership proof.
• Deregister a Relationship: Remove an existing relationship.

What responses to expect when (de)registering a relationship:

• 409 Conflict: This error occurs if you try to register a relationship that already exists.
• 400 Bad Request: This error occurs if you try to register an invalid CAIP10 address.
• 403 Forbidden: This error occurs if you attempt to register a relationship without the create:relationship permission.
• 403 Forbidden: This error occurs if you attempt to deregister a relationship without the delete:relationship permission.
• 404 Not Found: This error occurs if you try to deregister a relationship that is not registered.

How relationships are managed during a transfer

When a transfer is created:

• The platform saves all relationships from that transfer in your Relationships table. For example, relationships like Originator to VASP, originator address to VASP, beneficiary to Beneficiary VASP, etc.
• If the transfer contains relationships you own, they are marked as Confirmed.
• If the transfer contains relationships you assume, they are marked as Unconfirmed.

What happens when a transfer’s relationship is confirmed?

When a transfer’s relationship is confirmed or proven by an agent, the status of the relationship is updated to Confirmed. Any relationship that contains either a source address or a settlement address, and is confirmed, gets also saved into our Hashed Address Service. This enables customers to keep their addresses in sync in the hashed address service and making them discoverable by their counterparties.

Is Discoverability not an Opt-IN?

That is correct. We don’t see any reason why, with the correct security measures around it, we should not make addresses discoverable. Note that we will only upload the hash of an address and never an address in plain. The Network only works if entities can find each other.

Each time a Transfer Agent confirms address ownership, we will enrol that address in the hashed address service. You can also create confirmed relationships at any moment. These events will also be saved to the hashed address service.

How do I upload my address book?

Currently only via the Relationships endpoints. We have not yet a CSV upload feature like in V1.

What if my custodian registered and my VASP confirms the address, does it overwrite the Hashed Address Service?

Imagine this flow: A network intermediary registered an address and added a VASP as owner. Now a transfer to that address, including a Confirmation request, is send to the VASP. They confirm the address. Without additional checks we would now save this VASP-Address relation in the Hashed address service. And as we always fetch the last saved relation, we would for any next transfer not discover the Network anymore.

Well, we have solved this by checking if an address that gets registered in the Hashed address service, and the registering webDID is already registered as owner or custodian, we do not re-register.

---

The endpoints to use, out of transfer context, are:

List relationships

You can use the GET relationship endpoint to get a single relationship or a list of relationships.

Calling a single GET: {{url}}/entity/:entityDID/relationship?from=did:pkh:eip155:1:0x12345122323234&to=did:web:vasps.id:se

returns:

{
    "relationships": [
        {
            "@id": "c8d9ee1c-4339-40a2-95c2-88b17f26c2fe",
            "from": "did:pkh:eip155:1:0x12345122323234",
            "to": "did:web:vasps.id:se",
            "status": "CONFIRMED"
        }
    ]
}

the accepted query parameters are from and to. To clarify, the agent or party that is 'acting on behalf of' is always in the from field. Another example, from a VASP to an ultimate beneficiary:

{
            "@id": "0a8b6b77-ab89-455a-84e3-cae4c8a61d0d",
            "from": "did:web:vasps.id:az",
            "to": "did:email:[email protected]",
            "status": "UNCONFIRMED"
        },

Create relationships

Use POST: {{url}}/entity/:entityDID/relationshipwith body like:

{
    "from": "did:pkh:bip122:bc1pgf6m46mr8c55veujxg3qvqxfektwmmpfrt5mhwtvwrzeacmm7xaqdndaab",
    "to": "did:web:vasps.id:se"
}

Confirm a relationship

Use PATCH: {{url}}/entity/:entityDID/relationship?from=&to=&custodianto confirm a relationship. This is relevant in cases where another entity assumes you own a relationship but you have yet to confirm. Of course, only confirms if correct. In all other cases, reject the transfer.

The from and to query parameters are self-explanatory here, use them as in the create/POST call.

Delete relationships

Use DELETE: {{url}}/entity/:entityDID/relationship?id=&for=