Module hb_path.erl ¶

This module provides utilities for manipulating the paths of a message: Its request path (referred to in messages as just the Path), and its HashPath.

Description¶

A HashPath is a rolling Merkle list of the messages that have been applied in order to generate a given message. Because applied messages can themselves be the result of message applications with the AO-Core protocol, the HashPath can be thought of as the tree of messages that represent the history of a given message. The initial message on a HashPath is referred to by its ID and serves as its user-generated 'root'.

Specifically, the HashPath can be generated by hashing the previous HashPath and the current message. This means that each message in the HashPath is dependent on all previous messages.

       Msg1.HashPath = Msg1.ID
       Msg3.HashPath = Msg1.Hash(Msg1.HashPath, Msg2.ID)
       Msg3.{...} = AO-Core.apply(Msg1, Msg2)
       ...

A message's ID itself includes its HashPath, leading to the mixing of a Msg2's merkle list into the resulting Msg3's HashPath. This allows a single message to represent a history tree of all of the messages that were applied to generate it -- rather than just a linear history.

A message may also specify its own algorithm for generating its HashPath, which allows for custom logic to be used for representing the history of a message. When Msg2's are applied to a Msg1, the resulting Msg3's HashPath will be generated according to Msg1's algorithm choice.

Function Index¶

do_to_binary/1*
from_message/3	Extract the request path or hashpath from a message.
hashpath/2	Add an ID of a Msg2 to the HashPath of another message.
hashpath/3
hashpath/4
hashpath_alg/2	Get the hashpath function for a message from its HashPath-Alg.
hashpath_direct_msg2_test/0*
hashpath_test/0*
hd/2	Extract the first key from a `Message2`'s `Path` field.
hd_test/0*
matches/2	Check if two keys match.
multiple_hashpaths_test/0*
normalize/1	Normalize a path to a binary, removing the leading slash if present.
pop_from_message_test/0*
pop_from_path_list_test/0*
pop_request/2	Pop the next element from a request path or path list.
priv_remaining/2	Return the `Remaining-Path` of a message, from its hidden `AO-Core` key.
priv_store_remaining/2	Store the remaining path of a message in its hidden `AO-Core` key.
priv_store_remaining/3
push_request/2	Add a message to the head (next to execute) of a request path.
push_request/3
queue_request/2	Queue a message at the back of a request path.
queue_request/3
regex_matches/2	Check if two keys match using regex.
regex_matches_test/0*
term_to_path_parts/1	Convert a term into an executable path.
term_to_path_parts/2
term_to_path_parts_test/0*
tl/2	Return the message without its first path element.
tl_test/0*
to_binary/1	Convert a path of any form to a binary.
to_binary_test/0*
validate_path_transitions/2*
verify_hashpath/2	Verify the HashPath of a message, given a list of messages that represent its history.
verify_hashpath_test/0*

Function Details¶

do_to_binary/1 *¶

do_to_binary(Path) -> any()

from_message/3¶

from_message(Type, Link, Opts) -> any()

Extract the request path or hashpath from a message. We do not use AO-Core for this resolution because this function is called from inside AO-Core itself. This imparts a requirement: the message's device must store a viable hashpath and path in its Erlang map at all times, unless the message is directly from a user (in which case paths and hashpaths will not have been assigned yet).

hashpath/2¶

hashpath(Bin, Opts) -> any()

Add an ID of a Msg2 to the HashPath of another message.

hashpath/3¶

hashpath(Msg1, Msg2, Opts) -> any()

hashpath/4¶

hashpath(Msg1, Msg2, HashpathAlg, Opts) -> any()

hashpath_alg/2¶

hashpath_alg(Msg, Opts) -> any()

Get the hashpath function for a message from its HashPath-Alg. If no hashpath algorithm is specified, the protocol defaults to sha-256-chain.

hashpath_direct_msg2_test/0 *¶

hashpath_direct_msg2_test() -> any()

hashpath_test/0 *¶

hashpath_test() -> any()

hd/2¶

hd(Msg2, Opts) -> any()

Extract the first key from a Message2's Path field. Note: This function uses the dev_message:get/2 function, rather than a generic call as the path should always be an explicit key in the message.

hd_test/0 *¶

hd_test() -> any()

matches/2¶

matches(Key1, Key2) -> any()

Check if two keys match.

multiple_hashpaths_test/0 *¶

multiple_hashpaths_test() -> any()

normalize/1¶

normalize(Path) -> any()

Normalize a path to a binary, removing the leading slash if present.

pop_from_message_test/0 *¶

pop_from_message_test() -> any()

pop_from_path_list_test/0 *¶

pop_from_path_list_test() -> any()

pop_request/2¶

pop_request(Msg, Opts) -> any()

Pop the next element from a request path or path list.

priv_remaining/2¶

priv_remaining(Msg, Opts) -> any()

Return the Remaining-Path of a message, from its hidden AO-Core key. Does not use the get or set hb_private functions, such that it can be safely used inside the main AO-Core resolve function.

priv_store_remaining/2¶

priv_store_remaining(Msg, RemainingPath) -> any()

Store the remaining path of a message in its hidden AO-Core key.

priv_store_remaining/3¶

priv_store_remaining(Msg, RemainingPath, Opts) -> any()

push_request/2¶

push_request(Msg, Path) -> any()

Add a message to the head (next to execute) of a request path.

push_request/3¶

push_request(Msg, Path, Opts) -> any()

queue_request/2¶

queue_request(Msg, Path) -> any()

Queue a message at the back of a request path. path is the only key that we cannot use dev_message's set/3 function for (as it expects the compute path to be there), so we use hb_maps:put/3 instead.

queue_request/3¶

queue_request(Msg, Path, Opts) -> any()

regex_matches/2¶

regex_matches(Path1, Path2) -> any()

Check if two keys match using regex.

regex_matches_test/0 *¶

regex_matches_test() -> any()

term_to_path_parts/1¶

term_to_path_parts(Path) -> any()

Convert a term into an executable path. Supports binaries, lists, and atoms. Notably, it does not support strings as lists of characters.

term_to_path_parts/2¶

term_to_path_parts(Link, Opts) -> any()

term_to_path_parts_test/0 *¶

term_to_path_parts_test() -> any()

tl/2¶

tl(Msg2, Opts) -> any()

Return the message without its first path element. Note that this is the only transformation in AO-Core that does not make a log of its transformation. Subsequently, the message's IDs will not be verifiable after executing this transformation. This may or may not be the mainnet behavior we want.

tl_test/0 *¶

tl_test() -> any()

to_binary/1¶

to_binary(Path) -> any()

Convert a path of any form to a binary.

to_binary_test/0 *¶

to_binary_test() -> any()

validate_path_transitions/2 *¶

validate_path_transitions(X, Opts) -> any()

verify_hashpath/2¶

verify_hashpath(Rest, Opts) -> any()

Verify the HashPath of a message, given a list of messages that represent its history.

verify_hashpath_test/0 *¶

verify_hashpath_test() -> any()

Module hb_path.erl¶