Skip to content

Latest commit

 

History

History
194 lines (138 loc) · 6.46 KB

README.md

File metadata and controls

194 lines (138 loc) · 6.46 KB
Raw

👋 Welcome to the
Logo
Holochain library

license PRs welcome made with love

TrustGraph::Holochain is a Rust library, intended to allow for Holochain developers to easily use the Trust Graph protocol in their Happs.

TrustGraph::Holochain is a very young codebase; expect limited functionality, and don’t use it in production just yet -- but do come collaborate and play as we develop it!

Prerequisites

  • rust >= 1.56

Install

In your Cargo.toml:

trust_atom = {git = "https://github.com/trustgraph/trustgraph-holochain.git", rev="v1.2.3", package = "trust_atom"}

Replace v1.2.3 with the tag corresponding to the version you want. See the list of available tags.

HDK version correspondence:

  • TrustGraph::Holochain v0.0.1 - v0.0.6 works with hdk version 0.0.116
  • TrustGraph::Holochain v0.0.7 works with hdk version 0.0.125
  • TrustGraph::Holochain v0.0.8 (pulled)
  • TrustGraph::Holochain v0.0.9 works with hdk version 0.0.131
  • TrustGraph::Holochain v0.1.0 works with hdk version 0.1.1 and hdi version 0.2.1

Usage

TrustAtom Creation

pub struct TrustAtomInput {
  pub target: AnyLinkableHash,
  pub content: Option<String>,
  pub value: Option<String>,
  pub extra: Option<BTreeMap<String, String>>,
}

#[hdk_extern]
pub fn create_trust_atom(input: TrustAtomInput) -> ExternResult<TrustAtom> {
    // ...
}

TrustAtom Query

pub struct QueryInput {
  pub source: Option<AnyLinkableHash>,
  pub target: Option<AnyLinkableHash>,
  pub content_full: Option<String>,
  pub content_starts_with: Option<String>,
  pub value_starts_with: Option<String>,
}

#[hdk_extern]
pub fn query(input: QueryInput) -> ExternResult<Vec<TrustAtom>> {
    // ...
}

TrustAtom

Client-facing representation of a Trust Atom (this is what is returned to client from a query)

pub struct TrustAtom {
  pub source_hash: AnyLinkableHash,
  pub target_hash: AnyLinkableHash,
  pub content: Option<String>,
  pub value: Option<String>,
  pub extra: Option<BTreeMap<String, String>>,
}

For more detailed usage, see also the tests: https://github.com/trustgraph/trustgraph-holochain/blob/main/zomes/trust_atom/tests/trust_atom_tests.rs

Data format

We encode TrustAtoms as links, with the following components:

  1. Holochain Link base == TrustAtom source - creating agent (AgentPubKey)
  2. Holochain Link target == TrustAtom target - entity being rated/reviewed/etc - AnyLinkableHash
  3. Holochain Link tag* (max 999 bytes) - formatted as UTF-8 string
  • TrustAtom header bytes: [0xC5][0xA6] (which together comprise the unicode character Ŧ) (required)
  • Direction byte:
    • [0x21][0x92] (unicode →) means: HC target = TA target
    • [0x21][0xA9] (unicode ↩) means: HC target = TA source
  • TrustAtom content - semantic info (eg sushi) - max 900 bytes
  • Separator: null byte [0x00]
  • TrustAtom value - rating ( "-0.999999999" to "0.999999999") - max 12 chars
  • Separator: null byte [0x00]
  • Random 9 characters for bucketing purposes
  • Separator: null byte [0x00]
  • Optional "extra" EntryHash if additional metadata is needed:
    • Entry contains attributes formatted in: BTreeMap<String, String>
    • Entry hash is a sring version of EntryHash (eg uhCEkto7…) for debugging purposes, not raw bytes

*This format is designed to allow us to encode trust atoms as Holochain links, and search them by their tags. Holochain can search for all links starting with a given set of bytes (characters).

Full Example Link Tags

Ŧ→[0x00]sushi[0x00]0.999999999[0x00]892412523[0x00]uhCEk…UFnFF
Ŧ↩[0x00]sushi[0x00]0.999999999[0x00]892412523[0x00]uhCEk…UFnFF

Ŧ→[0x00]content[0x00]0.800000000[0x00]087423432[0x00]uhCEk…qS5wc
Ŧ↩[0x00]content[0x00]0.800000000[0x00]087423432[0x00]uhCEk…qS5wc

Ŧ→[0x00]spam[0x00]-0.999999999[0x00]328425615[0x00]uhCEk…VaaDd
Ŧ→[0x00]block[0x00]-0.999999999[0x00]837592944[0x00]uhCEk…VaaDd

Roadmap

  • Create TrustAtoms as paired Holochain links
  • Fetch TrustAtoms by content leading bytes
  • Fetch TrustAtoms by content and value
  • Integration into holochain example projects, eg Clutter
  • Roll up a TrustGraph by crawling TrustAtoms (2 levels deep)

Authors

👤 Harlan T Wood (https://github.com/harlantwood) 👤 Zeek (https://github.com/dauphin3)

🤝 Contributing

Contributions, issues and feature requests are welcome!

Report a Bug · Request a Feature · Ask a Question

Show your support

Give a ⭐️ if you like the project!

Dev

If you're new to holochain dev, start here: https://developer.holochain.org/quick-start. Then, from a terminal in the root of this repo:

nix develop

Then within nix shell:

bin/run test             # rust tests
bin/run test_watch       # rust tests with watch

bin/run clippy           # rust linter
bin/run clippy_watch     # rust linter with watch

bin/run clean            # reset to clean repo state; removes all gitignored files

Or to run all checks:

bin/run checks

When you have commits that you are ready to push, to run checks and push only if checks are all green:

bin/run shipit

📝 License

Copyright © 2022 Harlan T Wood (https://github.com/harlantwood).
This project is Apache-2.0 licensed.