Expand description
Exports common types and functions according to the Rust prelude pattern.
Re-exports
pub use crate::capability::create_cap_claim;
pub use crate::capability::create_cap_grant;
pub use crate::capability::delete_cap_grant;
pub use crate::capability::generate_cap_secret;
pub use crate::capability::update_cap_grant;
pub use crate::chain::get_agent_activity;
pub use crate::chain::query;
pub use crate::countersigning::accept_countersigning_preflight_request;
pub use crate::countersigning::session_times_from_millis;
pub use crate::ed25519::sign;
pub use crate::ed25519::sign_ephemeral;
pub use crate::ed25519::sign_ephemeral_raw;
pub use crate::ed25519::sign_raw;
pub use crate::entry::create;
pub use crate::entry::create_entry;
pub use crate::entry::delete;
pub use crate::entry::delete_entry;
pub use crate::entry::get;
pub use crate::entry::get_details;
pub use crate::entry::update;
pub use crate::entry::update_entry;
pub use crate::hash_path::anchor::anchor;
pub use crate::hash_path::anchor::list_anchor_addresses;
pub use crate::hash_path::anchor::list_anchor_tags;
pub use crate::hash_path::anchor::list_anchor_type_addresses;
pub use crate::hash_path::anchor::Anchor;
pub use crate::hash_path::path::Path;
pub use crate::hash_path::path::TypedPath;
pub use crate::info::agent_info;
pub use crate::info::call_info;
pub use crate::link::create_link;
pub use crate::link::delete_link;
pub use crate::link::get_link_details;
pub use crate::link::get_links;
pub use crate::map_extern;
pub use crate::map_extern;
pub use crate::p2p::call;
pub use crate::p2p::call_remote;
pub use crate::p2p::emit_signal;
pub use crate::p2p::remote_signal;
pub use crate::time::schedule;
pub use crate::time::sleep;
pub use crate::time::sys_time;
pub use crate::x_salsa20_poly1305::create_x25519_keypair;
pub use crate::x_salsa20_poly1305::x_25519_x_salsa20_poly1305_encrypt;
pub use crate::x_salsa20_poly1305::x_salsa20_poly1305_encrypt;
pub use hdi;
pub use hdk_derive;
pub use holo_hash;
pub use holochain_zome_types;
pub use tracing;
pub use crate::hash::*;
pub use crate::hdk::*;
pub use crate::random::*;
pub use crate::time::*;
Modules
represent arbitrary bytes (not serialized)
e.g. totally random crypto bytes from random_bytes
Capability Grants and Claims
A “Cell” represents a DNA/AgentId pair - a space where one dna/agent
can track its source chain and service network requests / responses.
Countersigned entries involve preflights between many agents to build a session that is part of the entry.
Re-exported dependencies
Defines DnaDef struct
An Entry is a unit of data in a Holochain Source Chain.
Items related to the DNA initialization callback.
Attach a span to a
std::future::Future
.Wrapper type to indicate some data which has a ValidationStatus associated
with it.
Metadata types for use in wasm
Types for source chain queries
Types for rate limiting
Defines a Record, the basic unit of Holochain data.
Types for requesting metadata
Schedule functions to run outside a direct zome call.
Wrapper types to enable optimized handling of
&[u8]
and Vec<u8>
.App-defined signals
Signature for authenticity of data
Types related to the
debug
host functionTracking versions between the WASM host and guests and other interfaces.
Types for warrants
A
Zome
is a module of app-defined code which can be run by Holochain.
A group of Zomes are composed to form a DnaDef
.Macros
Implements conversion traits to allow a struct to be handled as an app entry.
If you have some need to implement custom serialization logic or metadata injection
you can do so by implementing these traits manually instead.
Constructs an event at the debug level.
Implements a whole lot of sane defaults for a struct or enum that should behave as an entry.
All the entry def fields are available as dedicated methods on the type and matching From impls
are provided for each. This allows for both Foo::entry_def() and EntryDef::from(Foo::new())
style logic which are both useful in different scenarios.
Constructs an event at the error level.
unidiomatic way to derive default trait implementations of TryFrom in/out of SerializedBytes
Helper macro for implementing ToSql, when using rusqlite as a dependency
Helper macro for implementing ToSql, when using rusqlite as a dependency
Constructs an event at the info level.
Hides away the gross bit where we hook up integer pointers to length-prefixed guest memory
to serialization and deserialization, and returning things to the host, and memory allocation
and deallocation.
Constructs an event at the trace level.
A simple macro to wrap
return_err_ptr
in an analogy to the native rust ?
.Constructs an event at the warn level.
Helper macro for returning an error from a WASM.
Structs
An agents chain records returned from a agent_activity_query
The struct containing all information about the executing agent’s identity.
Action for an agent validation package, used to determine whether an agent
is allowed to participate in this DNA
Newtype for the bytes comprising an App entry
Information about a class of Entries provided by the DNA
The location of an app entry definition.
Identifier for an entry definition.
This may be removed.
A signal emitted by an app via
emit_signal
An ordered set based on a B-Tree.
System entry to hold a capability token claim for use as a caller.
Stored by a claimant so they can remember what’s necessary to exercise
this capability by sending the secret to the grantor.
A CapSecret is used by a caller to prove to a callee access to a committed CapGrant.
The unique identifier for a Cell.
Cells are uniquely determined by this pair - this pair is necessary
and sufficient to refer to a cell in a conductor
Filter source chain items.
Starting from some chain position given as an
ActionHash
the chain is walked backwards to genesis.
The filter can stop early by specifying the number of
chain items to take and / or an ActionHash
to consume until.The chain has been forked by these two actions
The action at the head of the complete chain.
This is as far as this authority can see a
chain with no gaps.
Specifies arguments to a query of the source chain, including ordering and filtering.
Identifier of a clone cell, composed of the DNA’s role name and the index
of the clone, starting at 0.
When migrating to a new version of a DNA, this action is committed to the
old chain to declare the migration path taken. Currently unused
Every countersigning agent must sign against their chain state.
The chain must be frozen until each agent decides to sign or exit the session.
All the data required for a countersigning session.
Every countersigning session must complete a full set of actions between the start and end times to be valid.
A action which “speaks” Entry content into being. The same content can be
referenced by multiple such actions.
Base data for Create actions.
Zome input to create an entry.
Declares that a metadata Link should be made between two EntryHashes
Zome IO inner type for link creation.
@todo Ability to forcibly curry payloads into functions that are called with a claim.
Declare that a previously published Action should be nullified and
considered deleted.
Placeholder for future when we want to have deletes on actions
Not currently in use.
Zome input for all delete operations.
Declares that a previously made Link should be nullified and considered removed.
Query arguments for the deterministic version of GetAgentActivity
The Dna Action is always the first action in a source chain
The definition of a DNA: the hash of this data is what produces the DnaHash.
Information about the current DNA.
Modifiers of this DNA - the network seed, properties and origin time - as
opposed to the actual DNA code. These modifiers are included in the DNA
hash computation.
DnaModifiers
options of which all are optional.All definitions for all entry types in an integrity zome.
An Entry with all its metadata.
A newtype for a collection of EntryHashes, needed for some wasm return types.
Combination of the three main rate limiting data types, for convenience
The output of ephemeral signing.
The private key for this public key has been discarded by this point.
The signatures match the public key provided but cannot be reproduced
or forged because the private key no longer exists.
The signatures match the input items positionally in the vector,
it is up to the caller to reconstruct/align/zip them back together.
A single function name.
Data passed into the genesis_self_check callback for verifying the initial
chain entries
Zome input for get and get_details calls.
Options for controlling how get works
Parameters for granting a zome call capability.
256 Bit generic hash.
512 Bit generic hash.
The highest action sequence observed by this authority.
This also includes the actions at this sequence.
If there is more then one then there is a fork.
A HoloHash contains a vector of 36 bytes representing a 32-byte blake2b hash
plus 4 bytes representing a DHT location. It also contains a zero-sized
type which specifies what it is a hash of.
Represents some piece of content along with its hash representation, so that
hashes need not be calculated multiple times.
Provides an easy constructor which consumes the content.
A action which declares that all zome init functions have successfully
completed, and the chain is ready for commits. Contains no explicit data.
Data with an optional validation status.
CreateLinks with and DeleteLinks on them
[CreateLink, [DeleteLink]]
Opaque tag for the link applied at the app layer, used to differentiate
between different semantics and validation rules for different links
Metadata that can be requested on a basis
Zome input for must_get_action.
Input to the
must_get_agent_activity
call.Zome input for must_get_entry.
Zome input for must_get_valid_record.
256 Bit generic nonce.
When migrating to a new version of a DNA, this action is committed to the
new chain to declare the migration path taken. Currently unused
Every preflight request can have optional arbitrary bytes that can be agreed to.
The same PreflightRequest is sent to every agent.
Each agent signs this data as part of their PreflightResponse.
Every preflight must be identical and signed by every agent for a session to be valid.
Every agent must send back a preflight response.
All the preflight response data is signed by each agent and included in the session data.
Specifies arguments to a query of the source chain, including ordering and filtering.
Combination of two rate limiting data types, for convenience
a chain record containing the signed action along with the
entry if the action type has one.
A specific Record with any deletes
This is all the metadata available for a record.
Registers a link between two
Entry
s.
This is the act of creating a Action::CreateLink
and
publishing it to the DHT.
The authority is the entry authority for the base Entry
.Registers a deletion of an instance of an
Entry
in the DHT.
This is the act of creating a Action::Delete
and
publishing it to the DHT.Deletes a link between two
Entry
s.
This is the act of creating a Action::DeleteLink
and
publishing it to the DHT.
The delete always references a specific Action::CreateLink
.Registers an update from an instance of an
Entry
in the DHT.
This is the act of creating a Action::Update
and
publishing it to the DHT.
Note that the Action::Update
stores an new instance
of an Entry
and registers it as an update to the original Entry
.
This operation is only concerned with registering the update.Remote signal many agents without waiting for responses.
The number of validations required for an entry to
be considered published.
Agents can have a role specific to each countersigning session.
The role is app defined and opaque to the subconscious.
A fully qualified scheduled function.
A type with the zome that it is defined in.
zome types that are in scope for the calling zome.
The set of
EntryDefIndex
and LinkType
s in scope for the calling zome.A Canonical Serialized Bytes representation for data
If you have a data structure that needs a canonical byte representation use this
Always round-trip through SerializedBytes via. a single TryFrom implementation.
This ensures that the internal bytes of SerializedBytes are indeed canonical.
The corrolary is that if bytes are NOT wrapped in SerializedBytes we can assume they are NOT
canonical.
Typically we need a canonical serialization when data is to be handled at the byte level by
independently implemented and maintained systems.
Input structure for creating a signature.
Ephemerally sign a vector of bytes (i.e. a Vec<Vec>)
Each of the items of the outer vector represents something to sign
and will have a corresponding Signature in the output.
The public key for the ephemeral operation will be returned in the output.
Structurally mirrors/complements the
Signature
struct as a new type.
There we know the key on the input side, here we receive the key on the output.The raw bytes of a signature.
A combination of an action and its signature.
Any content that has been hashed and signed.
Stores a new
Entry
in the DHT.
This is the act of creating a either a Action::Create
or
a Action::Update
and publishing it to the DHT.
These actions create a new instance of an Entry
.A microsecond-precision UTC timestamp for use in Holochain’s actions.
Representation of message to be logged via the
debug
host functionUnsafeBytes the only way to implement a custom round trip through bytes for SerializedBytes
It is intended to be an internal implementation in TryFrom implementations
The assumption is that any code using UnsafeBytes is NOT valid messagepack data
This allows us to enforce that all data round-tripping through SerializedBytes is via TryFrom
and also allow for custom non-messagepack canonical representations of data types.
A action which specifies that some new Entry content is intended to be an
update to some old Entry.
Placeholder for future when we want to have updates on actions
Not currently in use.
Base data for Update actions.
Zome input type for all update operations.
Mirror struct for Sign that includes a signature to verify against a key and data.
Placeholder for warrant type
Wraps a WasmErrorInner with a file and line number.
The easiest way to generate this is with the
wasm_error!
macro that will
insert the correct file/line and can create strings by forwarding args to
the format!
macro.A zome defined by Wasm bytecode
Data that can be encrypted with secretbox.
Key refs represent shared secrets stored in the keystore.
They can either be user-specified, or auto-generated at time of
secret creation, or ingestion.
A Holochain Zome. Includes the ZomeDef as well as the name of the Zome.
The entry for the ZomeCall capability grant.
This data is committed to the callee’s source chain as a private entry.
The remote calling agent must provide a secret and we source their pubkey from the active
network connection. This must match the strictness of the CapAccess.
Zome calls need to be signed regardless of how they are called.
This defines exactly what needs to be signed.
The index into the
ZomeIndex
vec.this id is an internal reference, which also serves as a canonical ordering
for zome initialization. The value should be auto-generated from the Zome Bundle def
The properties of the current dna/zome being called.
ZomeName as a String.
A key to the
ScopedZomeTypes
container.Enums
Action contains variants for each type of action.
Enum to mirror Action for all the shared data required to build session actions.
Does NOT hold any agent specific information.
A unit enum which just maps onto the different Action variants,
without containing any extra data
Get either the full activity or just the status of the chain
Represents access requirements for capability grants.
Represents a potentially valid access grant to a zome call.
Zome call response will be Unauthorized without a valid grant.
Specify which
Action
s to allow through
this filter.Defines several ways that queries can be restricted to a range.
Notably hash bounded ranges disambiguate forks whereas sequence indexes do
not as the same position can be found in many forks.
The reason that this does NOT use native rust range traits is that the hash
bounded queries MUST be inclusive otherwise the integrity and fork
disambiguation logic is impossible. An exclusive range bound that does not
include the final action tells us nothing about which fork to select
between N forks of equal length that proceed it. With an inclusive hash
bounded range the final action always points unambiguously at the “correct”
fork that the range is over. Start hashes are not needed to provide this
property so ranges can be hash terminated with a length of preceeding
records to return only. Technically the seq bounded ranges do not imply
any fork disambiguation and so could be a range but for simplicity we left
the API symmetrical in boundedness across all enum variants.
@TODO It may be possible to provide/implement RangeBounds in the case that
a full sequence of records/actions is provided but it would need to be
handled as inclusive first, to enforce the integrity of the query, then the
exclusiveness achieved by simply removing the final record after the fact.
Status of the agent activity chain
Errors related to the secure primitive macro.
Return type for get_details calls.
ActionHash returns a Record.
EntryHash returns an Entry.
Structure holding the entry portion of a chain record.
Either an
EntryDefIndex
or one of:The status of an Entry in the Dht
Errors involving app entry creation
Allows Actions which reference Entries to know what type of Entry it is
referencing. Useful for examining Actions without needing to fetch the
corresponding Entries.
Describes the get call and what information
the caller is concerned about.
This helps the subconscious avoid unnecessary network calls.
Input to holochain hash function.
Output from the holochain hashing host function.
Anything that can go wrong while calling a HostFnApi method
A human-readable timestamp which is represented/serialized as an RFC3339
when possible, and a microsecond integer count otherwise.
Both representations can be deserialized to this type.
The result of the DNA initialization callback.
Maps directly to the tracing Levels but here to define the interface.
See https://docs.rs/tracing-core/0.1.17/tracing_core/struct.Level.html
Filter on a set of
LinkType
s.These are the operations that can be applied to Holochain data.
Every
Action
produces a set of operations.
These operations are each sent to an authority for validation.Data specific to the
Op::RegisterAgentActivity
operation.Data specific to the
Op::RegisterDelete
operation.Data specific to the
Op::StoreEntry
operation.Data specific to the
Op::StoreRecord
operation.Data specific to the
Op::RegisterUpdate
operation.A preflight request can be accepted, or invalid, or valid but the local agent cannot accept it.
Represents the different ways the entry_address reference within an action
can be intepreted
The level of validation package required by
an entry.
Defines either a persisted or ephemeral schedule for a schedule function.
Persisted schedules survive a conductor reboot, ephemeral will not.
Persisted schedules continue beyond irrecoverable errors, ephemeral do not.
Scheduling errors.
Unresolved dependencies that are either a set of hashes
or an agent activity query.
The validation status for an op or record
much of this happens in the subconscious
an entry missing validation dependencies may cycle through Pending many times before finally
reaching a final validation state or being abandoned
Enum of all possible ERROR states that wasm can encounter.
Input to the
weigh
callback. Includes an “unweighed” action, and Entry
if applicable.Response to a zome call.
Just the definition of a Zome, without the name included. This exists
mainly for use in HashMaps where ZomeDefs are keyed by ZomeName.
Anything that can go wrong while calling a HostFnApi method
Constants
The number of bits we want for a comfy secret.
The number of bytes we want for a comfy secret.
Delimiter in a clone id that separates the base cell’s role id from the
clone index.
Entries larger than this number of bytes cannot be created
8 seems like a reasonable limit of agents to countersign.
Need at least two to countersign.
One million
Expire persisted schedules after this long.
Any action with a action_seq less than this value is part of a record
created during genesis. Anything with this seq or higher was created
after genesis.
Tick the scheduler every this many millis.
The timestamps on actions for a session use this offset relative to the session start time.
This makes it easier for agents to accept a preflight request with actions that are after their current chain top, after network latency.
Maximum time in the future the session start can be in the opinion of the participating agent.
As the action will be
SESSION_ACTION_TIME_OFFSET
after the session start we include that here.Ed25519 signatures are always the same length, 64 bytes.
Traits
Builder for non-genesis Actions
A trait to unify the “inner” parts of an Action, i.e. the structs inside
the Action enum’s variants. This trait is used for the “unweighed” version
of each struct, i.e. the version with weight information erased.
A trait to unify the “inner” parts of an Action, i.e. the structs inside
the Action enum’s variants. This trait is used for the “weighed” version
of each struct, i.e. the version without weight information erased.
A data structure that can be deserialized from any data format supported
by Serde.
Helper trait for deserializing
Entry
s to the correct type.Anything which has an owned HoloHashOf.
Data that requires a validation status.
An extension to obtain a link type filter.
This trait provides a conversion to a convenience type
OpType
for use in the validation call back.A data structure that can be serialized into any data format supported
by Serde.
Simple and safe type conversions that may fail in a controlled
way under some circumstances. It is the reciprocal of
TryInto
.An attempted conversion that consumes
self
, which may or may not be
expensive.Helper trait for types that are internally
represented as
u8
but need to be used
as indicies into containers.A utility trait for associating a data enum
with a unit enum that has the same variants.
Functions
Helpful pattern for debug formatting many bytes.
If the size is > 32 bytes, only the first 8 and last 8 bytes will be displayed.
Receive arguments from the host.
The guest sets the type
O
that the host needs to match.
If deserialization fails then a GuestPtr
to a WasmError::Deserialize
is returned.
The guest should immediately return an Err
back to the host.
The WasmError::Deserialize
enum contains the bytes that failed to deserialize so the host can
unambiguously provide debug information.Given an extern that we expect the host to provide:
Given a pointer and a length, return a
u64
merged GuestPtrLen
.
Works via a simple bitwise shift to move the pointer to high bits then OR
the length into the low bits.MUST get a SignedActionHashed at a given ActionHash.
The chain this filter produces on the given agents chain
must be fetched before the validation can be completed.
This allows for deterministic validation of chain activity by
making a hash bounded range of an agents chain into a dependency
for something that is being validated.
MUST get an EntryHashed at a given EntryHash.
MUST get a VALID Record at a given ActionHash.
Convert a
WasmError
to a GuestPtrLen
as best we can. This is not
necessarily straightforward as the serialization process can error recursively.
In the worst case we can’t even serialize an enum variant, in which case we panic.
The casts from usize
to u32
are safe as long as the guest code is compiled
for wasm32-unknown-unknown
target.Convert any serializable value into a
GuestPtr
that can be returned to the host.
The host is expected to know how to consume and deserialize it.Given a merged
GuestPtrLen
, split out a u32
pointer and length.
Performs the inverse of merge_u64
. Takes the low u32
bits as the length
then shifts the 32 high bits down and takes those as the pointer.Verify the passed signature and public key against the passed serializable input.
Verify the passed signature and public key against the literal bytes input.
Libsodium keypair based authenticated encryption: box_open
Libsodium secret-key authenticated encryption: secretbox_open
Type Definitions
The hash of an action
An Agent public signing key. Not really a hash, more of an “identity hash”.
The hash of anything referrable in the DHT.
This is a composite of either an EntryHash or a ActionHash
The hash of anything linkable.
simply alias whatever serde bytes is already doing for Vec
The data type written to the source chain to denote a capability claim
The data type written to the source chain when explicitly granting a capability.
NB: this is not simply
CapGrant
, because the CapGrant::ChainAuthor
grant is already implied by Entry::Agent
, so that should not be committed
to a chain. This is a type alias because if we add other capability types
in the future, we may want to include themA fixed size array of bytes that a secret must be.
Ordered list of coordinator zomes in this DNA.
Alias for a list of agents and their roles.
The hash of an Entry.
An Entry paired with its EntryHash
Every extern must return a
WasmError
in the case of failure.The hash of some external data that can’t or doesn’t exist on the DHT.
a single zome/function pair
A collection of zome/function pairs
A
WasmSize
that points to a position in wasm linear memory that the host
and guest are sharing to communicate across function calls.Enough bits to fit a pointer and length into so we can return it. The externs
defined as “C” don’t support multiple return values (unlike wasm). The native
Rust support for wasm externs is not stable at the time of writing.
Ordered list of integrity zomes in this DNA.
A
WasmSize
integer that represents the size of bytes to read/write to memory.App-specific payload for proving membership in the membrane of the app
Placeholder for a real network seed type. See
DnaDef
.The amount that a bucket is “filled”
A bucket ID, for rate limiting
The normalized total size of this action, for rate limiting
The weight of this action, for rate limiting
Identifier for an App Role, a foundational concept in the App manifest.
An
EntryDefIndex
within the scope of the zome where it’s defined.A
LinkType
within the scope of the zome where it’s defined.The hashed action and the signature that signed it
Something like
usize
for wasm.
Wasm has a memory limit of 4GB so offsets and lengths fit in u32
.A key to the
ScopedZomeTypes<EntryDefIndex>
container.A key to the
ScopedZomeTypes<LinkType>
container.Attribute Macros
Declares the integrity zome’s entry types.
Helper for entry data types.
Implements all the required types needed for a
LinkTypes
enum.Instruments a function to create and enter a
tracing
span every time
the function is called.