Skip to main content

zombienet_sdk/
lib.rs

1use std::path::PathBuf;
2
3use async_trait::async_trait;
4pub use configuration::{
5    json_patch,
6    types::{Arg, AssetLocation},
7    Buildable, CustomProcess, CustomProcessBuilder, Dependency, DependencyCondition, EnvValue,
8    GlobalSettings, GlobalSettingsBuilder, NamedPort, NetworkConfig, NetworkConfigBuilder,
9    ProcessEnvVar, ReadyCheck, ReadyTarget, RegistrationStrategy, TransferedFile,
10};
11pub use orchestrator::{
12    errors::OrchestratorError,
13    network::{
14        jamchain::Jamchain,
15        node::{
16            CustomProcessNode, CustomProcessState, JamNetworkNode, NetworkNode, NodeKind,
17            ProcessPort, SpawnedNode,
18        },
19        Network,
20    },
21    sc_chain_spec, AddCollatorOptions, AddNodeOptions, Orchestrator,
22};
23pub use provider::types::{ExecutionResult, RunScriptOptions};
24
25/// Generator that could be handy from outside
26pub mod generators {
27    pub use orchestrator::generators::{
28        core_assignment, errors, generate_node_bootnode_addr, generate_node_identity,
29        generate_node_keys,
30    };
31}
32
33/// JAM: the genesis model of a spec built in process, and the blobs zombienet embeds.
34pub mod jam {
35    pub use configuration::{
36        JamAmount, JamAuthorizer, JamBalance, JamBytes, JamCoreIndex, JamGenesisConfig,
37        JamGenesisConfigBuilder, JamGenesisPrivileges, JamGenesisService, JamGenesisServiceBuilder,
38        JamServiceId, JAM_BOOTSTRAP_SERVICE_ID,
39    };
40    pub use orchestrator::generators::jam_blobs::{
41        authorizer_hash, embedded_bootstrap_service, null_authorizer_hash, NULL_AUTHORIZER_BLOB,
42        NULL_AUTHORIZER_HASH,
43    };
44    /// The embedded bootstrap service (with the `jam` feature).
45    #[cfg(feature = "jam")]
46    pub use orchestrator::generators::jam_blobs::{
47        BOOTSTRAP_SERVICE_BLOB, BOOTSTRAP_SERVICE_HASH, BOOTSTRAP_SERVICE_SOURCE,
48    };
49}
50
51/// Helpers used for interact with the network
52pub mod tx_helper {
53    pub use orchestrator::{
54        network::chain_upgrade::ChainUpgrade,
55        shared::types::RuntimeUpgradeOptions,
56        tx_helper::{parachain, runtime_upgrade},
57    };
58}
59
60use provider::{DockerProvider, KubernetesProvider, NativeProvider};
61pub use support::fs::local::LocalFileSystem;
62
63pub mod environment;
64pub mod snapshot;
65pub use snapshot::{Bundle, BundleBuilder, SnapshotManifest};
66pub const PROVIDERS: [&str; 3] = ["k8s", "native", "docker"];
67
68// re-export subxt
69pub use subxt;
70pub use subxt_signer;
71
72#[async_trait]
73pub trait NetworkConfigExt {
74    /// Spawns a network using the native or k8s provider.
75    ///
76    /// # Example:
77    /// ```rust
78    /// # use zombienet_sdk::{NetworkConfig, NetworkConfigExt};
79    /// # async fn example() -> Result<(), zombienet_sdk::OrchestratorError> {
80    /// let network = NetworkConfig::load_from_toml("config.toml")?
81    ///     .spawn_native()
82    ///     .await?;
83    /// # Ok(())
84    /// # }
85    /// ```
86    async fn spawn_native(self) -> Result<Network<LocalFileSystem>, OrchestratorError>;
87    async fn spawn_k8s(self) -> Result<Network<LocalFileSystem>, OrchestratorError>;
88    /// Spawns a network using the k8s provider into `namespace`, which must already
89    /// exist. It is left in place if spawning fails; `Network::destroy` deletes it.
90    async fn spawn_k8s_in_namespace(
91        self,
92        namespace: &str,
93    ) -> Result<Network<LocalFileSystem>, OrchestratorError>;
94    async fn spawn_docker(self) -> Result<Network<LocalFileSystem>, OrchestratorError>;
95}
96
97#[async_trait]
98pub trait AttachToLive {
99    /// Attaches to a running live network using the native, docker or k8s provider.
100    ///
101    /// # Example:
102    /// ```rust
103    /// # use zombienet_sdk::{AttachToLive, AttachToLiveNetwork};
104    /// # use std::path::PathBuf;
105    /// # async fn example() -> Result<(), zombienet_sdk::OrchestratorError> {
106    /// let zombie_json_path = PathBuf::from("some/path/zombie.json");
107    /// let network = AttachToLiveNetwork::attach_native(zombie_json_path).await?;
108    /// # Ok(())
109    /// # }
110    /// ```
111    async fn attach_native(
112        zombie_json_path: PathBuf,
113    ) -> Result<Network<LocalFileSystem>, OrchestratorError>;
114    async fn attach_k8s(
115        zombie_json_path: PathBuf,
116    ) -> Result<Network<LocalFileSystem>, OrchestratorError>;
117    async fn attach_docker(
118        zombie_json_path: PathBuf,
119    ) -> Result<Network<LocalFileSystem>, OrchestratorError>;
120
121    /// Attaches to a running live network using the k8s provider, from in-memory
122    /// `zombie.json` content. Its `local_base_dir` is used as-is.
123    ///
124    /// # Example:
125    /// ```rust
126    /// # use zombienet_sdk::{AttachToLive, AttachToLiveNetwork};
127    /// # async fn example(zombie_json: serde_json::Value) -> Result<(), zombienet_sdk::OrchestratorError> {
128    /// let network = AttachToLiveNetwork::attach_k8s_from_json(zombie_json).await?;
129    /// # Ok(())
130    /// # }
131    /// ```
132    async fn attach_k8s_from_json(
133        zombie_json: serde_json::Value,
134    ) -> Result<Network<LocalFileSystem>, OrchestratorError>;
135}
136
137#[async_trait]
138impl NetworkConfigExt for NetworkConfig {
139    async fn spawn_native(self) -> Result<Network<LocalFileSystem>, OrchestratorError> {
140        let filesystem = LocalFileSystem;
141        let provider = NativeProvider::new(filesystem.clone());
142        let orchestrator = Orchestrator::new(filesystem, provider);
143        orchestrator.spawn(self).await
144    }
145
146    async fn spawn_k8s(self) -> Result<Network<LocalFileSystem>, OrchestratorError> {
147        let filesystem = LocalFileSystem;
148        let provider = KubernetesProvider::new(filesystem.clone()).await;
149        let orchestrator = Orchestrator::new(filesystem, provider);
150        orchestrator.spawn(self).await
151    }
152
153    async fn spawn_k8s_in_namespace(
154        self,
155        namespace: &str,
156    ) -> Result<Network<LocalFileSystem>, OrchestratorError> {
157        let filesystem = LocalFileSystem;
158        let provider = KubernetesProvider::new_in_namespace(filesystem.clone(), namespace).await;
159        let orchestrator = Orchestrator::new(filesystem, provider);
160        orchestrator.spawn(self).await
161    }
162
163    async fn spawn_docker(self) -> Result<Network<LocalFileSystem>, OrchestratorError> {
164        let filesystem = LocalFileSystem;
165        let provider = DockerProvider::new(filesystem.clone()).await;
166        let orchestrator = Orchestrator::new(filesystem, provider);
167        orchestrator.spawn(self).await
168    }
169}
170
171pub struct AttachToLiveNetwork;
172
173#[async_trait]
174impl AttachToLive for AttachToLiveNetwork {
175    async fn attach_native(
176        zombie_json_path: PathBuf,
177    ) -> Result<Network<LocalFileSystem>, OrchestratorError> {
178        let filesystem = LocalFileSystem;
179        let provider = NativeProvider::new(filesystem.clone());
180        let orchestrator = Orchestrator::new(filesystem, provider);
181        orchestrator.attach_to_live(zombie_json_path.as_ref()).await
182    }
183
184    async fn attach_k8s(
185        zombie_json_path: PathBuf,
186    ) -> Result<Network<LocalFileSystem>, OrchestratorError> {
187        let filesystem = LocalFileSystem;
188        let provider = KubernetesProvider::new(filesystem.clone()).await;
189        let orchestrator = Orchestrator::new(filesystem, provider);
190        orchestrator.attach_to_live(zombie_json_path.as_ref()).await
191    }
192
193    async fn attach_docker(
194        zombie_json_path: PathBuf,
195    ) -> Result<Network<LocalFileSystem>, OrchestratorError> {
196        let filesystem = LocalFileSystem;
197        let provider = DockerProvider::new(filesystem.clone()).await;
198        let orchestrator = Orchestrator::new(filesystem, provider);
199        orchestrator.attach_to_live(zombie_json_path.as_ref()).await
200    }
201
202    async fn attach_k8s_from_json(
203        zombie_json: serde_json::Value,
204    ) -> Result<Network<LocalFileSystem>, OrchestratorError> {
205        let filesystem = LocalFileSystem;
206        let provider = KubernetesProvider::new(filesystem.clone()).await;
207        let orchestrator = Orchestrator::new(filesystem, provider);
208        orchestrator.attach_to_live_from_json(&zombie_json).await
209    }
210}