Struct InstallAppPayload

pub struct InstallAppPayload {
    pub source: AppBundleSource,
    pub agent_key: Option<HoloHash<Agent>>,
    pub installed_app_id: Option<String>,
    pub network_seed: Option<String>,
    pub roles_settings: Option<HashMap<String, RoleSettings>>,
    pub ignore_genesis_failure: bool,
    pub allow_throwaway_random_agent_key: bool,
}

All the information necessary to install an app

Fields

source: AppBundleSource

Where to obtain the AppBundle, which contains the app manifest and DNA bundles to be installed. This is the main payload of app installation.

Since this field uses #[serde(flatten)], when using other serialized data formats like JSON or YAML, this field will actually show up as one of the variants of AppBundleSource (e.g. bundle or path), rather than as a source field.

agent_key: Option<HoloHash<Agent>>

The agent to use when creating Cells for this App. If None, a new agent key will be generated in the right circumstances (read on).

It’s always OK to provide a pregenerated agent key here, but there is at least one major benefit to letting Holochain generate keys for you (other than the sheer convenience of not having to generate your own):

If you are using a device seed in your conductor config, the agent key will be derived from that seed using a sensible scheme based on the total number of app installations in this conductor, which means you can fairly easily regenerate all of your auto-generated agent keys if you lose access to the device with your conductor data (as long as you retain exclusive access to the device seed of course).

Holochain will only generate an agent key for you if [ConductorConfig::device_seed_lair_tag] is set and pointing to a seed present in lair. If this config is not set, installation will fail if no agent key is provided. This safety mechanism can however be overridden by setting the allow_throwaway_random_agent_key flag on this payload, which will cause Holochain to generate a totally random (non-recoverable) agent key.

If you are not using a device seed, or if your app has special requirements for agent keys, you can always provide your own here, no matter what setting you’re using.

installed_app_id: Option<String>

The unique identifier for an installed app in this conductor. If not specified, it will be derived from the app name in the bundle manifest.

network_seed: Option<String>

Optional: Overwrites all network seeds for all DNAs of Cells created by this app. This has a lower precedence than role-specific network seeds provided in the role_settings field of the InstallAppPayload.

The app can still use existing Cells, i.e. this does not require that all Cells have DNAs with the same overridden DNA.

roles_settings: Option<HashMap<String, RoleSettings>>

Specify role specific settings or modifiers that will override any settings in the dna manifets.

ignore_genesis_failure: bool

Optional: If app installation fails due to genesis failure, normally the app will be immediately uninstalled. When this flag is set, the app is left installed with empty cells intact. This can be useful for using graft_records_onto_source_chain, or for diagnostics.

allow_throwaway_random_agent_key: bool

By default, if an agent key is not specified, the conductor will generate a new one by deriving a key from the device seed specified in the config. If the device seed is not set, app installation will fail. If this flag is set, a random key will be created if no device seed is present. This is a risky decision, because it will mean that if you lose control of this device, you will not be able to regenerate your agent key from the device seed. Use only in situations where you know that this is a throwaway key!

Trait Implementations

impl Debug for InstallAppPayload

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for InstallAppPayload

fn deserialize<__D>( __deserializer: __D, ) -> Result<InstallAppPayload, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for InstallAppPayload

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.