SmartLink Manager
SmartLinks provide a way to leverage holochain Links to facilitate associative query resolution of a holon collection while reducing the need to retrieve the linked holons. The concept and design of SmartLinks was inspired by the TrustAtom concept pioneered within the TrustGraph project. SmartLinks allow the MAP to support bi-directional navigation of any relationship. They also lay the foundation for the MAP Query Engine to support filtered, ordered and paginated result sets.
The SmartLinks Component of the MAP Holons Data Manager is responsible for:
- Creating and deleting SmartLinks in response to requests from Holon Storage Functions
- Encoding/decoding information in the tag field of a holochain
Link, to support prefix filtering by get_links() and SmartLink filtering, sorting and pagination of the retrieved links in a way that minimizes the need to retrieve the associated Holon.
SmartLinks encode/decode information in the holochain Link structure to take advantage of the filtering capability provided by holochain's get_links() function.
Creating a holochain Link for a SmartLink requires populating values for the following parameters:
base_address: AnyLinkableHash,
target_address: AnyLinkableHash,
link_type: LinkType,
tag: LinkTag
The link_type parameter is always set to SmartLink.
The method for assigning values to the other parameters is elaborated in the following sections.
Each SmartLink represents a linkage between a single source holon and a single target holon. The base_address parameter is always set to the HolonId of the source holon.
The target_address parameter is always set to the HolonId of the target holon. Note that this HolonId can only be resolved in the HolonSpace that owns the target holon. If the target holon is owned by the same HolonSpace as the source holon (i.e., is owned by the Local HolonSpace), then assigning its HolonId to the target_address parameter is all that is required.
However, if the target holon is owned by an external HolonSpace, we also need to identify the HolonSpace that can resolve the target holon's HolonId. In these cases, SmartLink encodes the HolonId of the OutboundSpaceProxy for the external HolonSpace in the holochain LinkTag parameter as described in the next section.
The following table shows how SmartLink information is encoded within the Holochain LinkTag. Note that LinkTags are limited to 1K bytes in length.
| Field | Field Type | Length
| | | (bytes) | Comments |
|------------------------|-------------------|---------|------------------------------------------------|
|------------------------|-------------------|---------|------------------------------------------------|
| header_bytes | Unicode character | 2 | ₷ [0xE2][0x82][0xB7] identifies this as a
| | | | SmartLink tag
|------------------------|-------------------|---------|------------------------------------------------|
| relationship_descriptor| ActionHash | 53 | identifier for (a specific version) of the
| | | | RelationshipDescriptor that provides metadata
| | | | about this relationship.
|------------------------|-------------------|---------|------------------------------------------------|
| <End Prolog Separator> | NullByte + ⊣ | 2 | [0x00] [0xE2][0x8A][0xA3]
|------------------------|-------------------|---------|------------------------------------------------|
| reference_type | | 2 | indicates whether the target holon is:
| | | | Local Ⓛ [0xE2] [0x93] [0x81] or
| | | | External Ⓧ [0xE2] [0x93] [0x8D]
| | | |
|------------------------|-------------------|---------|------------------------------------------------|
| proxy_id | ActionHash | 53 | identifier for the OutboundSpaceProxy in the
| (only used for External| | | local HolonSpace that proxies for the external
| References) | | | HolonSpace containing the target holon.
|------------------------|-------------------|---------|------------------------------------------------|
| property_values | String | 700 | Name/Value pairs (serialized into a String)
| | | | for each of the smart_property_values provided
| | | | for this SmartLink.
| | | | Each `PropertyName` string is preceded by
| | | | a Ⓝ [0xE2][0x93][0x83] and is terminated by
| | | | a Null [0x00].
| | | | Each PropertyValue is preceded by a
| | | | a Ⓥ [0xE2][0x93][0x8B] and is terminated by
| | | | a Null [0x00].
| | | |
|------------------------|-------------------|---------|------------------------------------------------|
| unused | n/a | 212 | reserved for future use
|------------------------|-------------------|---------|------------------------------------------------|
Note that the grammar divides the tag content into three sections:
- prolog (everything in the tag up through the '⊣' character). T
- reference_type_section consisting of the reference type indicator (local or external) and, for external references only, the proxy_id
- body (the property values encoded AFTER the reference_type section)
The prolog is used for hdk get_links() prefix filtering to obtain a vector of SmartLinks consisting of only those links associated with the specified base_holon, for the specified access_path of the specified relationship.
The body provides values for properties of the target holon that can be used to perform additional filtering, sorting and paginating on the links returned by the HDK without having to retrieve the target holon itself.
As noted above, each SmartLink represents a linkage between a single source holon and a single target holon. This means that, given a source holon, I can use SmartLinks to find all of the holons that are related to that source holon. For example, given a Person source holon, I could find all of the Movies that the Person ACTED_IN. But how would I query for all of the Person holons? Holochain uses special links referred to as Anchors for this purpose, but the MAP supports this capability a bit differently. Specifically, a HolonSpace has SmartLinks to all of the holons in that space. So the HolonSpace itself, can be used as the source holon to retrieve all of the holons in that HolonSpace. Holons support an access path, that includes the type_name of the holon (from its HolonDescriptor). Thus, to retrieve, say, all of the Person holons within a HolonSpace, follow the holons relationship from the HolonSpace holon where type_name = "Person".
For details on how SmartLinks are created and deleted, see the Holon Storage Functions component. For details on how SmartLinks are used, see the Query Engine