Homestar

Outline

• Quickstart
• Packages
• Running Examples
• Workspace
• Contributing
• Releases and Builds
• Getting Help
• External Resources
• License

Quickstart

If you're looking to help develop Homestar, please dive right into our development guide.

Otherwise, the easiest way to get started and see Homestar in action is to follow-along with our examples. To start, try out our image-processing websocket relay example, which integrates Homestar with a browser application to run a statically-configured workflow. The associated README.md walks through what to install (i.e. rust, node/npm, ipfs), what commands to run, and embeds a video demonstrating its usage.

Throughout the Homestar ecosystem and documentation, we'll draw a distinction between the host runtime and the support for different guest languages and bindings.

If you're mainly interested in learning how to write and build-out Wasm components (currently focused on authoring in Rust), please jump into our homestar-functions directory and check out our examples there.

Packages

Each Homestar release will also build packages for distribution across different platforms.

• homebrew: brew install fission-codes/fission/homestar This includes ipfs in the install by default.
• npm: npm install homestar-runtime -g Wraps the homestar-runtime binary in a node script.

Running Examples

All examples contain instructions for running them, including what to install and how to run them. Please clone this repo, and get started!

Each example showcases something specific and interesting about Homestar as a system.

Our current list includes:

• websocket relay - An example (browser-based) application that connects to the homestar-runtime over a WebSocket connection in order to run a couple static Wasm-based, image processing workflows that chain inputs and outputs.

Workspace

This repository is comprised of a few library packages and a library/binary that represents the Homestar runtime. We recommend diving into each package's own README.md for more information when available.

Core Crates

• homestar-invocation

  The invocation library implements much of the Ucan Invocation specification and is used as the foundation for other packages in this workspace and within the runtime engine.

• homestar-wasm

  This wasm library manages the wasmtime runtime, provides the IPLD to/from WIT interpreter/translation-layer, and implements the input interface for working with Ipvm's standard Wasm tasks.

  You can find the spec for translating between IPLD and WIT runtime values based on WIT types here.

  Note: This library also includes a WIT world for bindings implemented on the host runtime.

• homestar-workflow

  The workflow library implements workflow-centric Ipvm features and is used as the foundation for other packages in this workspace and within the runtime engine.

Runtime Crate

• homestar-runtime

  The runtime is responsible for bootstrapping and running nodes, scheduling and executing workflows as well as tasks within workflows, handling retries and failure modes, etc.

Non-published Crates

• homestar-functions/*

  homestar-functions is a directory of helper, test, and example crates for writing and compiling Wasm component modules using wit-bindgen.

  You can find our component packages on wa.dev.

• homestar-schemas

homestar-schemas is a crate for generating OpenRPC docs and JSON Schemas that document the homestar-runtime JSON-RPC API, workflows, and receipts.

• examples/*

  examples contains examples and demos showcasing Homestar packages and the Homestar runtime. Each example is set up as its own crate, demonstrating the necessary dependencies and setup(s).

Contributing

🎈 We're thankful for any feedback and help in improving our project! We have a focused development guide, as well as a more general contributing guide to help you get involved. We always adhere to our Code of Conduct.

Releases and Builds

Crates, Tags, and GitHub Releases

Homestar uses release-plz to publish crates, tags, changelogs, and GitHub Releases. Upon merging, a release-plz bot PR, four crates are continuously published, all tied to the same cargo version currently (though this may change in the future):

• homestar-runtime
• homestar-invocation
• homestar-workflow
• homestar-wasm

Build Targets

Every GitHub release of the homestar-runtime contains build assets for running the homestar-runtime on different target architectures, as well as DEB and RPM packages (tagged with the architectured they were compiled for). Our homebrew package for the runtime is also tied to releases and can be installed with brew install fission-codes/fission/homestar.

We also leverage cross for locally cross-compiling to varying Linux and Apple target platforms.

NPM Packages

We also release some of our cross-compiled runtime binaries as npm binary packages:

• homestar-runtime - This is the main package that installs the os specific binary package and runs it.
• homestar-darwin-arm64
• homestar-darwin-x64
• homestar-linux-arm64
• homestar-linux-x64
• homestar-windows-x64

Getting Help

For usage questions, usecases, or issues reach out to us in our Discord channel.

We would be happy to try to answer your question or try opening a new issue on GitHub.

External Resources

• What Is An IPVM
• IPVM: High-Level Spec
• Contributing Research
• Seamless Services for an Open World by Brooklyn Zelenka
• Foundations for Open-World Compute by Zeeshan Lakhani
• IPVM: The Long-Fabled Execution Layer by Brooklyn Zelenka
• IPVM - IPFS and WASM by Brooklyn Zelenka
• Breaking Down the Interplanetary Virtual Machine
• Ucan Invocation Spec

License

This project is licensed under the Apache License 2.0, or http://www.apache.org/licenses/LICENSE-2.0.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.