Module hdk::prelude [−][src]
Expand description
Exports common types and functions according to the Rust prelude pattern.
Re-exports
pub use crate::app_entry;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::ed25519::verify_signature;pub use crate::ed25519::verify_signature_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::hash_entry;pub use crate::entry::must_get_entry;pub use crate::entry::must_get_header;pub use crate::entry::must_get_valid_element;pub use crate::entry::update;pub use crate::entry::update_entry;pub use crate::entry::EntryDefRegistration;pub use crate::entry_def;pub use crate::entry_def_index;pub use crate::entry_defs;pub use crate::entry_type;pub use crate::hash_path::anchor::anchor;pub use crate::hash_path::anchor::get_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::hdk::*;pub use crate::info::agent_info;pub use crate::info::zome_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::map_extern::ExternResult;pub use crate::map_extern_infallible;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::random::*;pub use crate::register_entry;pub use crate::time::schedule;pub use crate::time::sleep;pub use crate::time::sys_time;pub use crate::time::*;pub use crate::x_salsa20_poly1305::create_x25519_keypair;pub use crate::x_salsa20_poly1305::x_25519_x_salsa20_poly1305_decrypt;pub use crate::x_salsa20_poly1305::x_25519_x_salsa20_poly1305_encrypt;pub use crate::x_salsa20_poly1305::x_salsa20_poly1305_decrypt;pub use crate::x_salsa20_poly1305::x_salsa20_poly1305_encrypt;pub use holo_hash;pub use holochain_zome_types;pub use tracing;pub use tracing_subscriber;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
Defines a Element, the basic unit of Holochain data.
An Entry is a unit of data in a Holochain Source Chain.
Types related to the genesis process whereby a user commits their initial elements and validates them to the best of their ability. Full validation may not be possible if network access is required, so they perform a “self-check” (as in “check yourself before you wreck yourself”) before joining to ensure that they can catch any problems they can before being subject to the scrutiny of their peers and facing possible rejection.
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 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
A microsecond-precision UTC timestamp for use in Holochain’s headers.
Types related to the debug host function
Tracking 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
Constructs an event at the debug level.
Constructs an event at the error level.
Serialization for fixed arrays is generally not available in a way that can be derived. Being able to wrap fixed size arrays is important e.g. for crypto safety etc. so this is a simple way to implement serialization so that we can send these types between the host/guest.
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.
Cryptographic secrets are fiddly at the best of times.
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.
Structs
An agents chain elements returned from a agent_activity_query
The struct containing all information about the executing agent’s identity.
Header 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
A signal emitted by an app via emit_signal
A 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
The chain has been forked by these two headers
The header at the head of the complete chain. This is as far as this authority can see a chain with no gaps.
Query arguments
When migrating to a new version of a DNA, this header 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 headers between the start and end times to be valid.
A header which “speaks” Entry content into being. The same content can be referenced by multiple such headers.
Base data for Create headers.
Data 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 Header should be nullified and considered deleted.
Placeholder for future when we want to have deletes on headers Not currently in use.
Zome IO inner for delete.
Declares that a previously made Link should be nullified and considered removed.
Query arguments for the deterministic version of GetAgentActivity
The Dna Header is always the first header in a source chain
The definition of a DNA: the hash of this data is what produces the DnaHash.
a chain element containing the signed header along with the entry if the header type has one.
A specific Element with any deletes This is all the metadata available for an element.
An Entry with all it’s metadata.
A newtype for a collection of EntryHashes, needed for some wasm return types.
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 IO for get and get_details calls.
Options for controlling how get works
A hash set implemented as a HashMap where the value is ().
The highest header sequence observed by this authority. This also includes the headers 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 header 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 IO for must_get_entry.
Zome IO for must_get_header.
Zome IO for must_get_valid_element.
When migrating to a new version of a DNA, this header 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.
Query arguments
Remote signal many agents without waiting for responses.
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 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<VecSignature 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. The equality is not different, it’s just constant time, so we can derive a hash. For an actually secure thing we wouldn’t want to just assume a safe default hashing But that is not what clippy is complaining about here.
A combination of a Header and its signature.
The header and the signature that signed it
A microsecond-precision UTC timestamp for use in Holochain’s headers.
Representation of message to be logged via the debug host function
UnsafeBytes 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 header which specifies that some new Entry content is intended to be an update to some old Entry.
Base data for Update headers.
Placeholder for future when we want to have updates on headers Not currently in use.
Zome IO inner for update.
Mirror struct for Sign that includes a signature to verify against a key and data.
Placeholder for warrant type
A zome defined by Wasm bytecode
Data that can be encrypted with secretbox.
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.
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.
Enums
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.
Status of the agent activity chain
Errors related to the secure primitive macro.
Return type for get_details calls. HeaderHash returns an Element. EntryHash returns an Entry.
Represents the different ways the entry_address reference within a Header can be intepreted
Structure holding the entry portion of a chain element.
The status of an Entry in the Dht
Errors involving app entry creation
Allows Headers which reference Entries to know what type of Entry it is referencing. Useful for examining Headers 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.
Header contains variants for each type of header.
Enum to mirror Header for all the shared data required to build session headers. Does NOT hold any agent specific information.
A unit enum which just maps onto the different Header variants, without containing any extra data
Anything that can go wrong while calling a HostFnApi method
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
A preflight request can be accepted, or invalid, or valid but the local agent cannot accept it.
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.
Errors related to the secure primitive macro.
The validation status for an op or element 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 codes that a Zome API Function could return.
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.
Entries larger than this number of bytes cannot be created
Key refs are the same length as the keys themselves. The key ref is just a sha256 of the key. There are no benefits, only downsides, to having either a larger or smaller set of outputs (ref size) vs. the set of inputs (key size).
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 header with a header_seq less than this value is part of an element created during genesis. Anything with this seq or higher was created after genesis.
Tick the scheduler every this many millis.
The timestamps on headers for a session use this offset relative to the session start time. This makes it easier for agents to accept a preflight request with headers 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 header will be SESSION_HEADER_TIME_OFFSET after the session start we include that here.
Ed25519 signatures are always the same length, 64 bytes.
Traits
A data structure that can be deserialized from any data format supported by Serde.
Anything which has an owned HoloHashOf.
Data that requires a validation status.
Builder for non-genesis Headers
A trait to specify the common parts of a Header
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.
Functions
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:
Convert a WasmError to a GuestPtrLen as best we can.
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.
Type Definitions
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 HeaderHash
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 them
A fixed size array of bytes that a secret must be.
Alias for a list of agents and their roles.
The hash of an Entry.
An Entry paired with its EntryHash
a single zome/function pair
A collection of zome/function pairs
a WasmSize integer that points to a position in wasm linear memory that the host and guest are sharing to communicate across function calls
The hash of a Header
a WasmSize integer that represents the size of bytes to read/write to memory in direct manipulations
App-specific payload for proving membership in the membrane of the app
Placeholder for a real UID type
something like usize for wasm wasm has a memory limit of 4GB so offsets and lengths fit in u32
Zomes need to be an ordered map from ZomeName to a Zome
Attribute Macros
Instruments a function to create and enter a tracing span every time
the function is called.