From b96d11da15ea488a39ec700d4f4ac080eb9732e6 Mon Sep 17 00:00:00 2001 From: Benno Zeeman Date: Wed, 4 Dec 2024 11:31:51 +0100 Subject: [PATCH 1/7] docs(autonomi): add archive_get rustdoc example --- autonomi/src/client/archive.rs | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/autonomi/src/client/archive.rs b/autonomi/src/client/archive.rs index 8eb23bb686..8810c0809d 100644 --- a/autonomi/src/client/archive.rs +++ b/autonomi/src/client/archive.rs @@ -146,6 +146,19 @@ impl Archive { impl Client { /// Fetch an archive from the network + /// + /// # Example + /// + /// ```no_run + /// # use autonomi::client::{Client, archive::ArchiveAddr}; + /// # #[tokio::main] + /// # async fn main() -> Result<(), Box> { + /// # let peers = ["/ip4/127.0.0.1/udp/1234/quic-v1".parse()?]; + /// let client = Client::connect(&peers).await?; + /// let archive = client.archive_get(ArchiveAddr::random(&mut rand::thread_rng())).await?; + /// # Ok(()) + /// # } + /// ``` pub async fn archive_get(&self, addr: ArchiveAddr) -> Result { let data = self.data_get(addr).await?; Ok(Archive::from_bytes(data)?) From 6adfc0e60d973b98ee507ec2858f4b744aba5ebc Mon Sep 17 00:00:00 2001 From: Benno Zeeman Date: Wed, 4 Dec 2024 15:15:56 +0100 Subject: [PATCH 2/7] docs(autonomi): rename EvmNetwork to Network --- ant-cli/src/wallet/mod.rs | 4 ++-- autonomi/src/lib.rs | 2 +- autonomi/src/python.rs | 5 ++--- 3 files changed, 5 insertions(+), 6 deletions(-) diff --git a/ant-cli/src/wallet/mod.rs b/ant-cli/src/wallet/mod.rs index b0dddfb889..ae95594a1b 100644 --- a/ant-cli/src/wallet/mod.rs +++ b/ant-cli/src/wallet/mod.rs @@ -8,14 +8,14 @@ use crate::keys::{get_secret_key_from_env, load_evm_wallet_from_env}; use crate::wallet::fs::{select_wallet, select_wallet_private_key}; -use autonomi::{EvmNetwork, Wallet}; +use autonomi::{Network, Wallet}; pub(crate) mod encryption; pub(crate) mod error; pub(crate) mod fs; pub(crate) mod input; -pub const DUMMY_NETWORK: EvmNetwork = EvmNetwork::ArbitrumSepolia; +pub const DUMMY_NETWORK: Network = Network::ArbitrumSepolia; /// Load wallet from ENV or disk pub(crate) fn load_wallet() -> color_eyre::Result { diff --git a/autonomi/src/lib.rs b/autonomi/src/lib.rs index 705623a833..99c98b9a79 100644 --- a/autonomi/src/lib.rs +++ b/autonomi/src/lib.rs @@ -44,7 +44,7 @@ mod self_encryption; mod utils; pub use ant_evm::get_evm_network_from_env; -pub use ant_evm::EvmNetwork; +pub use ant_evm::EvmNetwork as Network; pub use ant_evm::EvmWallet as Wallet; pub use ant_evm::RewardsAddress; #[cfg(feature = "external-signer")] diff --git a/autonomi/src/python.rs b/autonomi/src/python.rs index 5be03cc4ec..2106327347 100644 --- a/autonomi/src/python.rs +++ b/autonomi/src/python.rs @@ -9,8 +9,7 @@ use crate::client::{ vault::{UserData, VaultSecretKey}, Client as RustClient, }; -use crate::{Bytes, Wallet as RustWallet}; -use ant_evm::EvmNetwork; +use crate::{Bytes, Network, Wallet as RustWallet}; use pyo3::exceptions::PyValueError; use pyo3::prelude::*; use xor_name::XorName; @@ -176,7 +175,7 @@ impl PyWallet { #[new] fn new(private_key: String) -> PyResult { let wallet = RustWallet::new_from_private_key( - EvmNetwork::ArbitrumOne, // TODO: Make this configurable + Network::ArbitrumOne, // TODO: Make this configurable &private_key, ) .map_err(|e| { From 9039aafd0522dfbb1f2e6516afe07dfe69cccdd9 Mon Sep 17 00:00:00 2001 From: Benno Zeeman Date: Wed, 4 Dec 2024 15:16:45 +0100 Subject: [PATCH 3/7] docs(autonomi): improve exposing doc/types --- autonomi/src/client/archive.rs | 19 +++++++++++++++++++ autonomi/src/lib.rs | 1 + evmlib/src/utils.rs | 3 ++- 3 files changed, 22 insertions(+), 1 deletion(-) diff --git a/autonomi/src/client/archive.rs b/autonomi/src/client/archive.rs index 8810c0809d..6ed3a343ff 100644 --- a/autonomi/src/client/archive.rs +++ b/autonomi/src/client/archive.rs @@ -165,6 +165,25 @@ impl Client { } /// Upload an archive to the network + /// + /// # Example + /// + /// Create simple archive containing `file.txt` pointing to random XOR name. + /// + /// ```no_run + /// # use autonomi::client::{Client, data::DataAddr, archive::{Archive, ArchiveAddr, Metadata}}; + /// # use std::path::PathBuf; + /// # #[tokio::main] + /// # async fn main() -> Result<(), Box> { + /// # let peers = ["/ip4/127.0.0.1/udp/1234/quic-v1".parse()?]; + /// # let client = Client::connect(&peers).await?; + /// # let wallet = todo!(); + /// let mut archive = Archive::new(); + /// archive.add_file(PathBuf::from("file.txt"), DataAddr::random(&mut rand::thread_rng()), Metadata::new_with_size(0)); + /// let address = client.archive_put(archive, &wallet).await?; + /// # Ok(()) + /// # } + /// ``` pub async fn archive_put( &self, archive: Archive, diff --git a/autonomi/src/lib.rs b/autonomi/src/lib.rs index 99c98b9a79..b21c90fd42 100644 --- a/autonomi/src/lib.rs +++ b/autonomi/src/lib.rs @@ -55,6 +55,7 @@ pub use bytes::Bytes; #[doc(no_inline)] // Place this under 'Re-exports' in the docs. pub use libp2p::Multiaddr; +#[doc(inline)] pub use client::Client; #[cfg(feature = "extension-module")] diff --git a/evmlib/src/utils.rs b/evmlib/src/utils.rs index 800fa7cc99..f212b466d5 100644 --- a/evmlib/src/utils.rs +++ b/evmlib/src/utils.rs @@ -70,7 +70,8 @@ pub fn get_evm_network( )) } -/// Get the `Network` from environment variables +/// Get the `Network` from environment variables. +/// /// Returns an error if we cannot obtain the network from any means. pub fn get_evm_network_from_env() -> Result { let evm_vars = [ From e841fb1f7e08af38fcbecb390bec2fa4d6eb6d63 Mon Sep 17 00:00:00 2001 From: Benno Zeeman Date: Wed, 4 Dec 2024 15:19:49 +0100 Subject: [PATCH 4/7] docs(autonomi): move Python/WASM to own READMEs --- autonomi/README.md | 245 +------------------------------------- autonomi/README_PYTHON.md | 188 +++++++++++++++++++++++++++++ autonomi/README_WASM.md | 95 +++++++++++++++ autonomi/WASM_docs.md | 39 ------ 4 files changed, 284 insertions(+), 283 deletions(-) create mode 100644 autonomi/README_PYTHON.md create mode 100644 autonomi/README_WASM.md delete mode 100644 autonomi/WASM_docs.md diff --git a/autonomi/README.md b/autonomi/README.md index a5ce30a3d1..32a50c5c5e 100644 --- a/autonomi/README.md +++ b/autonomi/README.md @@ -98,60 +98,6 @@ EVM_NETWORK=arbitrum-one EVM_PRIVATE_KEY= cargo test --package auto RUST_LOG=autonomi EVM_NETWORK=arbitrum-one EVM_PRIVATE_KEY= cargo test --package autonomi --features local -- --nocapture ``` -### WebAssembly - -To run a WASM test - -- Install `wasm-pack` -- Make sure your Rust supports the `wasm32-unknown-unknown` target. (If you - have `rustup`: `rustup target add wasm32-unknown-unknown`.) -- Pass a bootstrap peer via `ANT_PEERS`. This *has* to be the websocket address, - e.g. `/ip4//tcp//ws/p2p/`. - - As well as the other environment variables needed for EVM payments (e.g. `RPC_URL`). -- Optionally specify the specific test, e.g. `-- put` to run `put()` in `wasm.rs` only. - -Example: - -```sh -ANT_PEERS=/ip4//tcp//ws/p2p/ wasm-pack test --release --firefox autonomi --features=data,files --test wasm -- put -``` - -#### Test from JS in the browser - -`wasm-pack test` does not execute JavaScript, but runs mostly WebAssembly. Again make sure the environment variables are -set and build the JS package: - -```sh -wasm-pack build --dev --target web autonomi --features vault -``` - -Then cd into `autonomi/tests-js`, and use `npm` to install and serve the test html file. - -``` -cd autonomi/tests-js -npm install -npm run serve -``` - -Then go to `http://127.0.0.1:8080/tests-js` in the browser. Here, enter a `ws` multiaddr of a local node and press ' -run'. - -#### MetaMask example - -There is a MetaMask example for doing a simple put operation. - -Build the package with the `external-signer` feature (and again with the env variables) and run a webserver, e.g. with -Python: - -```sh -wasm-pack build --dev --target web autonomi --features external-signer -python -m http.server --directory autonomi 8000 -``` - -Then visit `http://127.0.0.1:8000/examples/metamask` in your (modern) browser. - -Here, enter a `ws` multiaddr of a local node and press 'run'. - ## Faucet (local) There is no faucet server, but instead you can use the `Deployer wallet private key` printed in the EVM node output to @@ -182,7 +128,7 @@ Alternatively, you can provide the wallet address that should own all the gas an startup command using the `--genesis-wallet` flag: ```sh -cargo run --bin evm-testnet -- --genesis-wallet +cargo run --bin evm-testnet -- --genesis-wallet= ``` ```shell @@ -195,192 +141,3 @@ Chunk payments address: 0x8464135c8F25Da09e49BC8782676a84730C318bC Deployer wallet private key: 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 Genesis wallet balance: (tokens: 20000000000000000000000000, gas: 9998998011366954730202) ``` - -## Python Bindings - -The Autonomi client library provides Python bindings for easy integration with Python applications. - -### Installation - -```bash -pip install autonomi-client -``` - -### Quick Start - -```python -from autonomi_client import Client, Wallet, PaymentOption - -# Initialize wallet with private key -wallet = Wallet("your_private_key_here") -print(f"Wallet address: {wallet.address()}") -print(f"Balance: {wallet.balance()}") - -# Connect to network -client = Client.connect(["/ip4/127.0.0.1/tcp/12000"]) - -# Create payment option -payment = PaymentOption.wallet(wallet) - -# Upload data -data = b"Hello, Safe Network!" -addr = client.data_put(data, payment) -print(f"Data uploaded to: {addr}") - -# Download data -retrieved = client.data_get(addr) -print(f"Retrieved: {retrieved.decode()}") -``` - -### Available Modules - -#### Core Components - -- `Client`: Main interface to the Autonomi network - - `connect(peers: List[str])`: Connect to network nodes - - `data_put(data: bytes, payment: PaymentOption)`: Upload data - - `data_get(addr: str)`: Download data - - `private_data_put(data: bytes, payment: PaymentOption)`: Store private data - - `private_data_get(access: PrivateDataAccess)`: Retrieve private data - - `register_generate_key()`: Generate register key - -- `Wallet`: Ethereum wallet management - - `new(private_key: str)`: Create wallet from private key - - `address()`: Get wallet address - - `balance()`: Get current balance - -- `PaymentOption`: Payment configuration - - `wallet(wallet: Wallet)`: Create payment option from wallet - -#### Private Data - -- `PrivateDataAccess`: Handle private data storage - - `from_hex(hex: str)`: Create from hex string - - `to_hex()`: Convert to hex string - - `address()`: Get short reference address - -```python -# Private data example -access = client.private_data_put(secret_data, payment) -print(f"Private data stored at: {access.to_hex()}") -retrieved = client.private_data_get(access) -``` - -#### Registers - -- Register operations for mutable data - - `register_create(value: bytes, name: str, key: RegisterSecretKey, wallet: Wallet)` - - `register_get(address: str)` - - `register_update(register: Register, value: bytes, key: RegisterSecretKey)` - -```python -# Register example -key = client.register_generate_key() -register = client.register_create(b"Initial value", "my_register", key, wallet) -client.register_update(register, b"New value", key) -``` - -#### Vaults - -- `VaultSecretKey`: Manage vault access - - `new()`: Generate new key - - `from_hex(hex: str)`: Create from hex string - - `to_hex()`: Convert to hex string - -- `UserData`: User data management - - `new()`: Create new user data - - `add_file_archive(archive: str)`: Add file archive - - `add_private_file_archive(archive: str)`: Add private archive - - `file_archives()`: List archives - - `private_file_archives()`: List private archives - -```python -# Vault example -vault_key = VaultSecretKey.new() -cost = client.vault_cost(vault_key) -client.write_bytes_to_vault(data, payment, vault_key, content_type=1) -data, content_type = client.fetch_and_decrypt_vault(vault_key) -``` - -#### Utility Functions - -- `encrypt(data: bytes)`: Self-encrypt data -- `hash_to_short_string(input: str)`: Generate short reference - -### Complete Examples - -#### Data Management - -```python -def handle_data_operations(client, payment): - # Upload text - text_data = b"Hello, Safe Network!" - text_addr = client.data_put(text_data, payment) - - # Upload binary data - with open("image.jpg", "rb") as f: - image_data = f.read() - image_addr = client.data_put(image_data, payment) - - # Download and verify - downloaded = client.data_get(text_addr) - assert downloaded == text_data -``` - -#### Private Data and Encryption - -```python -def handle_private_data(client, payment): - # Create and encrypt private data - secret = {"api_key": "secret_key"} - data = json.dumps(secret).encode() - - # Store privately - access = client.private_data_put(data, payment) - print(f"Access token: {access.to_hex()}") - - # Retrieve - retrieved = client.private_data_get(access) - secret = json.loads(retrieved.decode()) -``` - -#### Vault Management - -```python -def handle_vault(client, payment): - # Create vault - vault_key = VaultSecretKey.new() - - # Store user data - user_data = UserData() - user_data.add_file_archive("archive_address") - - # Save to vault - cost = client.put_user_data_to_vault(vault_key, payment, user_data) - - # Retrieve - retrieved = client.get_user_data_from_vault(vault_key) - archives = retrieved.file_archives() -``` - -### Error Handling - -All operations can raise exceptions. It's recommended to use try-except blocks: - -```python -try: - client = Client.connect(peers) - # ... operations ... -except Exception as e: - print(f"Error: {e}") -``` - -### Best Practices - -1. Always keep private keys secure -2. Use error handling for all network operations -3. Clean up resources when done -4. Monitor wallet balance for payments -5. Use appropriate content types for vault storage - -For more examples, see the `examples/` directory in the repository. diff --git a/autonomi/README_PYTHON.md b/autonomi/README_PYTHON.md new file mode 100644 index 0000000000..9bbb5a79b8 --- /dev/null +++ b/autonomi/README_PYTHON.md @@ -0,0 +1,188 @@ +## Python Bindings + +The Autonomi client library provides Python bindings for easy integration with Python applications. + +### Installation + +```bash +pip install autonomi-client +``` + +### Quick Start + +```python +from autonomi_client import Client, Wallet, PaymentOption + +# Initialize wallet with private key +wallet = Wallet("your_private_key_here") +print(f"Wallet address: {wallet.address()}") +print(f"Balance: {wallet.balance()}") + +# Connect to network +client = Client.connect(["/ip4/127.0.0.1/tcp/12000"]) + +# Create payment option +payment = PaymentOption.wallet(wallet) + +# Upload data +data = b"Hello, Safe Network!" +addr = client.data_put(data, payment) +print(f"Data uploaded to: {addr}") + +# Download data +retrieved = client.data_get(addr) +print(f"Retrieved: {retrieved.decode()}") +``` + +### Available Modules + +#### Core Components + +- `Client`: Main interface to the Autonomi network + - `connect(peers: List[str])`: Connect to network nodes + - `data_put(data: bytes, payment: PaymentOption)`: Upload data + - `data_get(addr: str)`: Download data + - `private_data_put(data: bytes, payment: PaymentOption)`: Store private data + - `private_data_get(access: PrivateDataAccess)`: Retrieve private data + - `register_generate_key()`: Generate register key + +- `Wallet`: Ethereum wallet management + - `new(private_key: str)`: Create wallet from private key + - `address()`: Get wallet address + - `balance()`: Get current balance + +- `PaymentOption`: Payment configuration + - `wallet(wallet: Wallet)`: Create payment option from wallet + +#### Private Data + +- `PrivateDataAccess`: Handle private data storage + - `from_hex(hex: str)`: Create from hex string + - `to_hex()`: Convert to hex string + - `address()`: Get short reference address + +```python +# Private data example +access = client.private_data_put(secret_data, payment) +print(f"Private data stored at: {access.to_hex()}") +retrieved = client.private_data_get(access) +``` + +#### Registers + +- Register operations for mutable data + - `register_create(value: bytes, name: str, key: RegisterSecretKey, wallet: Wallet)` + - `register_get(address: str)` + - `register_update(register: Register, value: bytes, key: RegisterSecretKey)` + +```python +# Register example +key = client.register_generate_key() +register = client.register_create(b"Initial value", "my_register", key, wallet) +client.register_update(register, b"New value", key) +``` + +#### Vaults + +- `VaultSecretKey`: Manage vault access + - `new()`: Generate new key + - `from_hex(hex: str)`: Create from hex string + - `to_hex()`: Convert to hex string + +- `UserData`: User data management + - `new()`: Create new user data + - `add_file_archive(archive: str)`: Add file archive + - `add_private_file_archive(archive: str)`: Add private archive + - `file_archives()`: List archives + - `private_file_archives()`: List private archives + +```python +# Vault example +vault_key = VaultSecretKey.new() +cost = client.vault_cost(vault_key) +client.write_bytes_to_vault(data, payment, vault_key, content_type=1) +data, content_type = client.fetch_and_decrypt_vault(vault_key) +``` + +#### Utility Functions + +- `encrypt(data: bytes)`: Self-encrypt data +- `hash_to_short_string(input: str)`: Generate short reference + +### Complete Examples + +#### Data Management + +```python +def handle_data_operations(client, payment): + # Upload text + text_data = b"Hello, Safe Network!" + text_addr = client.data_put(text_data, payment) + + # Upload binary data + with open("image.jpg", "rb") as f: + image_data = f.read() + image_addr = client.data_put(image_data, payment) + + # Download and verify + downloaded = client.data_get(text_addr) + assert downloaded == text_data +``` + +#### Private Data and Encryption + +```python +def handle_private_data(client, payment): + # Create and encrypt private data + secret = {"api_key": "secret_key"} + data = json.dumps(secret).encode() + + # Store privately + access = client.private_data_put(data, payment) + print(f"Access token: {access.to_hex()}") + + # Retrieve + retrieved = client.private_data_get(access) + secret = json.loads(retrieved.decode()) +``` + +#### Vault Management + +```python +def handle_vault(client, payment): + # Create vault + vault_key = VaultSecretKey.new() + + # Store user data + user_data = UserData() + user_data.add_file_archive("archive_address") + + # Save to vault + cost = client.put_user_data_to_vault(vault_key, payment, user_data) + + # Retrieve + retrieved = client.get_user_data_from_vault(vault_key) + archives = retrieved.file_archives() +``` + +### Error Handling + +All operations can raise exceptions. It's recommended to use try-except blocks: + +```python +try: + client = Client.connect(peers) + # ... operations ... +except Exception as e: + print(f"Error: {e}") +``` + +### Best Practices + +1. Always keep private keys secure +2. Use error handling for all network operations +3. Clean up resources when done +4. Monitor wallet balance for payments +5. Use appropriate content types for vault storage + +For more examples, see the `examples/` directory in the repository. diff --git a/autonomi/README_WASM.md b/autonomi/README_WASM.md new file mode 100644 index 0000000000..cf9a2c6d8f --- /dev/null +++ b/autonomi/README_WASM.md @@ -0,0 +1,95 @@ +# Autonomi JS API + +Note: the JS API is experimental and will be subject to change. + +The entry point for connecting to the network is {@link Client.connect}. + +This API is a wrapper around the Rust API, found here: https://docs.rs/autonomi/latest/autonomi. The Rust API contains more detailed documentation on concepts and some types. + +## Addresses + +For addresses (chunk, data, archives, etc) we're using hex-encoded strings containing a 256-bit XOR addresse. For example: `abcdefg012345678900000000000000000000000000000000000000000000000`. + +## Example + +Note: `getEvmNetwork` will use hardcoded EVM network values that should be set during compilation of this library. + +```javascript +import init, { Client, Wallet, getEvmNetwork } from 'autonomi'; + +let client = await new Client(["/ip4/127.0.0.1/tcp/36075/ws/p2p/12D3KooWALb...BhDAfJY"]); +console.log("connected"); + +let wallet = Wallet.new_from_private_key(getEvmNetwork, "your_private_key_here"); +console.log("wallet retrieved"); + +let data = new Uint8Array([1, 2, 3]); +let result = await client.put(data, wallet); +console.log("Data stored at:", result); + +let fetchedData = await client.get(result); +console.log("Data retrieved:", fetchedData); +``` + +## Funded wallet from custom local network + +```js +const evmNetwork = getEvmNetworkCustom("http://localhost:4343", "", ""); +const wallet = getFundedWalletWithCustomNetwork(evmNetwork, "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"); +``` + +# Developing + +## WebAssembly + +To run a WASM test + +- Install `wasm-pack` +- Make sure your Rust supports the `wasm32-unknown-unknown` target. (If you + have `rustup`: `rustup target add wasm32-unknown-unknown`.) +- Pass a bootstrap peer via `ANT_PEERS`. This *has* to be the websocket address, + e.g. `/ip4//tcp//ws/p2p/`. + - As well as the other environment variables needed for EVM payments (e.g. `RPC_URL`). +- Optionally specify the specific test, e.g. `-- put` to run `put()` in `wasm.rs` only. + +Example: + +```sh +ANT_PEERS=/ip4//tcp//ws/p2p/ wasm-pack test --release --firefox autonomi --features=data,files --test wasm -- put +``` + +### Test from JS in the browser + +`wasm-pack test` does not execute JavaScript, but runs mostly WebAssembly. Again make sure the environment variables are +set and build the JS package: + +```sh +wasm-pack build --dev --target web autonomi --features=vault +``` + +Then cd into `autonomi/tests-js`, and use `npm` to install and serve the test html file. + +``` +cd autonomi/tests-js +npm install +npm run serve +``` + +Then go to `http://127.0.0.1:8080/tests-js` in the browser. Here, enter a `ws` multiaddr of a local node and press ' +run'. + +## MetaMask example + +There is a MetaMask example for doing a simple put operation. + +Build the package with the `external-signer` feature (and again with the env variables) and run a webserver, e.g. with +Python: + +```sh +wasm-pack build --dev --target web autonomi --features=external-signer +python -m http.server --directory autonomi 8000 +``` + +Then visit `http://127.0.0.1:8000/examples/metamask` in your (modern) browser. + +Here, enter a `ws` multiaddr of a local node and press 'run'. diff --git a/autonomi/WASM_docs.md b/autonomi/WASM_docs.md deleted file mode 100644 index ee62681aba..0000000000 --- a/autonomi/WASM_docs.md +++ /dev/null @@ -1,39 +0,0 @@ -# Autonomi JS API - -Note: the JS API is experimental and will be subject to change. - -The entry point for connecting to the network is {@link Client.connect}. - -This API is a wrapper around the Rust API, found here: https://docs.rs/autonomi/latest/autonomi. The Rust API contains more detailed documentation on concepts and some types. - -## Addresses - -For addresses (chunk, data, archives, etc) we're using hex-encoded strings containing a 256-bit XOR addresse. For example: `abcdefg012345678900000000000000000000000000000000000000000000000`. - -## Example - -Note: `getEvmNetwork` will use hardcoded EVM network values that should be set during compilation of this library. - -```javascript -import init, { Client, Wallet, getEvmNetwork } from 'autonomi'; - -let client = await new Client(["/ip4/127.0.0.1/tcp/36075/ws/p2p/12D3KooWALb...BhDAfJY"]); -console.log("connected"); - -let wallet = Wallet.new_from_private_key(getEvmNetwork, "your_private_key_here"); -console.log("wallet retrieved"); - -let data = new Uint8Array([1, 2, 3]); -let result = await client.put(data, wallet); -console.log("Data stored at:", result); - -let fetchedData = await client.get(result); -console.log("Data retrieved:", fetchedData); -``` - -## Funded wallet from custom local network - -```js -const evmNetwork = getEvmNetworkCustom("http://localhost:4343", "", ""); -const wallet = getFundedWalletWithCustomNetwork(evmNetwork, "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"); -``` From e54d840dbf4dd2f13ca7cde0334f87808e72542d Mon Sep 17 00:00:00 2001 From: Benno Zeeman Date: Wed, 4 Dec 2024 16:18:00 +0100 Subject: [PATCH 5/7] refactor(autonomi): remove data feature --- ant-cli/Cargo.toml | 6 +----- autonomi/Cargo.toml | 13 ++++++------- autonomi/src/client/mod.rs | 4 ---- autonomi/src/lib.rs | 2 -- autonomi/tests/put.rs | 2 -- 5 files changed, 7 insertions(+), 20 deletions(-) diff --git a/ant-cli/Cargo.toml b/ant-cli/Cargo.toml index 7f1983fcfa..1bad9b6a61 100644 --- a/ant-cli/Cargo.toml +++ b/ant-cli/Cargo.toml @@ -29,7 +29,6 @@ ant-build-info = { path = "../ant-build-info", version = "0.1.19" } ant-logging = { path = "../ant-logging", version = "0.2.40" } ant-peers-acquisition = { path = "../ant-peers-acquisition", version = "0.5.7" } autonomi = { path = "../autonomi", version = "0.2.4", features = [ - "data", "fs", "vault", "registers", @@ -61,10 +60,7 @@ tracing = { version = "~0.1.26" } walkdir = "2.5.0" [dev-dependencies] -autonomi = { path = "../autonomi", version = "0.2.4", features = [ - "data", - "fs", -]} +autonomi = { path = "../autonomi", version = "0.2.4", features = ["fs"]} criterion = "0.5.1" eyre = "0.6.8" rand = { version = "~0.8.5", features = ["small_rng"] } diff --git a/autonomi/Cargo.toml b/autonomi/Cargo.toml index 88d61c711a..0e15996c27 100644 --- a/autonomi/Cargo.toml +++ b/autonomi/Cargo.toml @@ -14,16 +14,15 @@ name = "autonomi" crate-type = ["cdylib", "rlib"] [features] -data = [] -default = ["data", "vault"] -external-signer = ["ant-evm/external-signer", "data"] +default = ["vault"] +external-signer = ["ant-evm/external-signer"] extension-module = ["pyo3/extension-module"] -fs = ["tokio/fs", "data"] -full = ["data", "registers", "vault", "fs"] +fs = ["tokio/fs"] +full = ["registers", "vault", "fs"] local = ["ant-networking/local", "ant-evm/local"] loud = [] -registers = ["data"] -vault = ["data", "registers"] +registers = [] +vault = ["registers"] websockets = ["ant-networking/websockets"] [dependencies] diff --git a/autonomi/src/client/mod.rs b/autonomi/src/client/mod.rs index f039d097a0..f93fba1157 100644 --- a/autonomi/src/client/mod.rs +++ b/autonomi/src/client/mod.rs @@ -9,13 +9,9 @@ pub mod address; pub mod payment; -#[cfg(feature = "data")] pub mod archive; -#[cfg(feature = "data")] pub mod archive_private; -#[cfg(feature = "data")] pub mod data; -#[cfg(feature = "data")] pub mod data_private; #[cfg(feature = "external-signer")] pub mod external_signer; diff --git a/autonomi/src/lib.rs b/autonomi/src/lib.rs index b21c90fd42..9e288cd05e 100644 --- a/autonomi/src/lib.rs +++ b/autonomi/src/lib.rs @@ -26,7 +26,6 @@ //! //! - `fs`: Up/download files and directories from filesystem //! - `registers`: Operate on register datatype -//! - `data`: Operate on raw bytes and chunks //! - `vault`: Operate on Vault datatype //! - `full`: All of above //! - `local`: Discover local peers using mDNS. Useful for development. @@ -39,7 +38,6 @@ extern crate tracing; pub mod client; -#[cfg(feature = "data")] mod self_encryption; mod utils; diff --git a/autonomi/tests/put.rs b/autonomi/tests/put.rs index 4ec9f4dc87..401b5d3356 100644 --- a/autonomi/tests/put.rs +++ b/autonomi/tests/put.rs @@ -6,8 +6,6 @@ // KIND, either express or implied. Please review the Licences for the specific language governing // permissions and limitations relating to use of the SAFE Network Software. -#![cfg(feature = "data")] - use ant_logging::LogBuilder; use autonomi::Client; use eyre::Result; From 0c283796aa13ab1ae0cc0ec91f3964a93601a089 Mon Sep 17 00:00:00 2001 From: Benno Zeeman Date: Wed, 4 Dec 2024 16:18:23 +0100 Subject: [PATCH 6/7] docs(autonomi): add feature flag note to doc items --- autonomi/README_WASM.md | 2 +- autonomi/src/client/fs.rs | 3 --- autonomi/src/client/mod.rs | 8 ++++++++ autonomi/src/lib.rs | 25 +++++++++++++++++++++++++ 4 files changed, 34 insertions(+), 4 deletions(-) diff --git a/autonomi/README_WASM.md b/autonomi/README_WASM.md index cf9a2c6d8f..8c6478def7 100644 --- a/autonomi/README_WASM.md +++ b/autonomi/README_WASM.md @@ -55,7 +55,7 @@ To run a WASM test Example: ```sh -ANT_PEERS=/ip4//tcp//ws/p2p/ wasm-pack test --release --firefox autonomi --features=data,files --test wasm -- put +ANT_PEERS=/ip4//tcp//ws/p2p/ wasm-pack test --release --firefox autonomi --features=files --test wasm -- put ``` ### Test from JS in the browser diff --git a/autonomi/src/client/fs.rs b/autonomi/src/client/fs.rs index 15e32d1bf5..2dced2beee 100644 --- a/autonomi/src/client/fs.rs +++ b/autonomi/src/client/fs.rs @@ -36,7 +36,6 @@ pub static FILE_UPLOAD_BATCH_SIZE: LazyLock = LazyLock::new(|| { }); /// Errors that can occur during the file upload operation. -#[cfg(feature = "fs")] #[derive(Debug, thiserror::Error)] pub enum UploadError { #[error("Failed to recursively traverse directory")] @@ -53,7 +52,6 @@ pub enum UploadError { Deserialization(#[from] rmp_serde::decode::Error), } -#[cfg(feature = "fs")] /// Errors that can occur during the download operation. #[derive(Debug, thiserror::Error)] pub enum DownloadError { @@ -63,7 +61,6 @@ pub enum DownloadError { IoError(#[from] std::io::Error), } -#[cfg(feature = "fs")] /// Errors that can occur during the file cost calculation. #[derive(Debug, thiserror::Error)] pub enum FileCostError { diff --git a/autonomi/src/client/mod.rs b/autonomi/src/client/mod.rs index f93fba1157..be0579c29d 100644 --- a/autonomi/src/client/mod.rs +++ b/autonomi/src/client/mod.rs @@ -6,6 +6,9 @@ // KIND, either express or implied. Please review the Licences for the specific language governing // permissions and limitations relating to use of the SAFE Network Software. +// Optionally enable nightly `doc_cfg`. Allows items to be annotated, e.g.: "Available on crate feature X only". +#![cfg_attr(docsrs, feature(doc_cfg))] + pub mod address; pub mod payment; @@ -14,14 +17,19 @@ pub mod archive_private; pub mod data; pub mod data_private; #[cfg(feature = "external-signer")] +#[cfg_attr(docsrs, doc(cfg(feature = "external-signer")))] pub mod external_signer; #[cfg(feature = "fs")] +#[cfg_attr(docsrs, doc(cfg(feature = "fs")))] pub mod fs; #[cfg(feature = "fs")] +#[cfg_attr(docsrs, doc(cfg(feature = "fs")))] pub mod fs_private; #[cfg(feature = "registers")] +#[cfg_attr(docsrs, doc(cfg(feature = "registers")))] pub mod registers; #[cfg(feature = "vault")] +#[cfg_attr(docsrs, doc(cfg(feature = "vault")))] pub mod vault; #[cfg(target_arch = "wasm32")] diff --git a/autonomi/src/lib.rs b/autonomi/src/lib.rs index 9e288cd05e..4f219ea116 100644 --- a/autonomi/src/lib.rs +++ b/autonomi/src/lib.rs @@ -8,6 +8,31 @@ //! Connect to and build on the Autonomi network. //! +//! # Example +//! +//! ```rust +//! use autonomi::{Bytes, Client, Wallet}; +//! +//! #[tokio::main] +//! async fn main() -> Result<(), Box> { +//! let client = Client::connect(&["/ip4/127.0.0.1/udp/1234/quic-v1".parse()?]).await?; +//! +//! // Default wallet of testnet. +//! let key = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"; +//! let wallet = Wallet::new_from_private_key(Default::default(), key)?; +//! +//! // Put and fetch data. +//! let data_addr = client.data_put(Bytes::from("Hello, World"), (&wallet).into()).await?; +//! let _data_fetched = client.data_get(data_addr).await?; +//! +//! // Put and fetch directory from local file system. +//! let dir_addr = client.dir_upload("files/to/upload".into(), &wallet).await?; +//! client.dir_download(dir_addr, "files/downloaded".into()).await?; +//! +//! Ok(()) +//! } +//! ``` +//! //! # Data types //! //! This API gives access to two fundamental types on the network: chunks and From 57dd0828fe1d485c0c63e9c2a10a46a9a2c34732 Mon Sep 17 00:00:00 2001 From: Benno Zeeman Date: Wed, 4 Dec 2024 17:50:46 +0100 Subject: [PATCH 7/7] docs(autonomi): improve README.md --- autonomi/README.md | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/autonomi/README.md b/autonomi/README.md index 32a50c5c5e..c781c46bf9 100644 --- a/autonomi/README.md +++ b/autonomi/README.md @@ -7,10 +7,9 @@ Connect to and build on the Autonomi network. ## Usage -Add the autonomi crate to your `Cargo.toml`: +Add the `autonomi` crate to your project with `cargo add`: ```sh -# `cargo add` adds dependencies to your Cargo.toml manifest file cargo add autonomi ``` @@ -61,19 +60,19 @@ let wallet = Wallet::new_from_private_key(EvmNetwork::new_custom("", "< 2. Run a local EVM node: ```sh -cargo run --bin evm-testnet +cargo run --bin=evm-testnet ``` 3. Run a local network with the `local` feature and use the local evm node. ```sh -cargo run --bin antctl --features local -- local run --build --clean --rewards-address evm-local +cargo run --bin=antctl --features=local -- local run --build --clean --rewards-address= evm-local ``` 4. Then run the tests with the `local` feature and pass the EVM params again: ```sh -EVM_NETWORK=local cargo test --package autonomi --features local +EVM_NETWORK=local cargo test --package autonomi --features=local # Or with logs RUST_LOG=autonomi EVM_NETWORK=local cargo test --package autonomi --features local -- --nocapture ``` @@ -86,21 +85,19 @@ point it to a live network. 1. Run a local network with the `local` feature: ```sh -cargo run --bin antctl --features local -- local run --build --clean --rewards-address evm-arbitrum-one +cargo run --bin=antctl --features=local -- local run --build --clean --rewards-address= evm-arbitrum-one ``` 2. Then run the tests with the `local` feature. Make sure that the wallet of the private key you pass has enough gas and payment tokens on the network (in this case Arbitrum One): ```sh -EVM_NETWORK=arbitrum-one EVM_PRIVATE_KEY= cargo test --package autonomi --features local -# Or with logs -RUST_LOG=autonomi EVM_NETWORK=arbitrum-one EVM_PRIVATE_KEY= cargo test --package autonomi --features local -- --nocapture +EVM_NETWORK=arbitrum-one EVM_PRIVATE_KEY= cargo test --package=autonomi --features=local ``` -## Faucet (local) +## Using funds from the Deployer Wallet -There is no faucet server, but instead you can use the `Deployer wallet private key` printed in the EVM node output to +You can use the `Deployer wallet private key` printed in the EVM node output to initialise a wallet from with almost infinite gas and payment tokens. Example: ```rust