@withautonomi/autonomi 0.2.2-rc.2

package/README.md

@@ -0,0 +1,159 @@
+# `autonomi` - Autonomi client API
+
+[![Crates.io](https://img.shields.io/crates/v/autonomi.svg)](https://crates.io/crates/autonomi)
+[![docs.rs](https://img.shields.io/badge/api-rustdoc-blue.svg)](https://docs.rs/autonomi)
+
+Connect to and build on the Autonomi network.
+
+## Usage
+
+Add the autonomi crate to your `Cargo.toml`:
+
+```toml
+[dependencies]
+autonomi = { path = "../autonomi", version = "0.1.0" }
+```
+
+## Running tests
+
+### Using a local EVM testnet
+
+1. If you haven't, install Foundry, to be able to run Anvil
+   nodes: https://book.getfoundry.sh/getting-started/installation
+2. Run a local EVM node:
+
+```sh
+cargo run --bin evm_testnet
+```
+
+3. Run a local network with the `local` feature and use the local evm node.
+
+```sh
+cargo run --bin=safenode-manager --features=local -- local run --build --clean --rewards-address <ETHEREUM_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
+# Or with logs
+RUST_LOG=autonomi EVM_NETWORK=local cargo test --package=autonomi --features=local -- --nocapture
+```
+
+### Using a live testnet or mainnet
+
+Using the hardcoded `Arbitrum One` option as an example, but you can also use the command flags of the steps above and
+point it to a live network.
+
+1. Run a local network with the `local` feature:
+
+```sh
+cargo run --bin=safenode-manager --features=local -- local run --build --clean --rewards-address <ETHEREUM_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=<PRIVATE_KEY> cargo test --package=autonomi --features=local
+# Or with logs
+RUST_LOG=autonomi EVM_NETWORK=arbitrum-one EVM_PRIVATE_KEY=<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 `SAFE_PEERS`. This *has* to be the websocket address,
+  e.g. `/ip4/<ip>/tcp/<port>/ws/p2p/<peer ID>`.
+    - 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
+SAFE_PEERS=/ip4/<ip>/tcp/<port>/ws/p2p/<peer ID> 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
+initialise a wallet from with almost infinite gas and payment tokens. Example:
+
+```rust
+let rpc_url = "http://localhost:54370/";
+let payment_token_address = "0x5FbDB2315678afecb367f032d93F642f64180aa3";
+let data_payments_address = "0x8464135c8F25Da09e49BC8782676a84730C318bC";
+let private_key = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80";
+
+let network = Network::Custom(CustomNetwork::new(
+rpc_url,
+payment_token_address,
+data_payments_address,
+));
+
+let deployer_wallet = Wallet::new_from_private_key(network, private_key).unwrap();
+let receiving_wallet = Wallet::new_with_random_wallet(network);
+
+// Send 10 payment tokens (atto)
+let _ = deployer_wallet
+.transfer_tokens(receiving_wallet.address(), Amount::from(10))
+.await;
+```
+
+Alternatively, you can provide the wallet address that should own all the gas and payment tokens to the EVM testnet
+startup command using the `--genesis-wallet` flag:
+
+```sh
+cargo run --bin evm_testnet -- --genesis-wallet <ETHEREUM_ADDRESS>
+```
+
+```shell
+*************************
+* Ethereum node started *
+*************************
+RPC URL: http://localhost:60093/
+Payment token address: 0x5FbDB2315678afecb367f032d93F642f64180aa3
+Chunk payments address: 0x8464135c8F25Da09e49BC8782676a84730C318bC
+Deployer wallet private key: 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
+Genesis wallet balance: (tokens: 20000000000000000000000000, gas: 9998998011366954730202)
+```

package/autonomi.d.ts

@@ -0,0 +1,314 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+* # Example
+*
+* ```js
+* const secretKey = genSecretKey();
+* await client.putUserDataToVault(userData, wallet, secretKey);
+* const userDataFetched = await client.getUserDataFromVault(secretKey);
+* ```
+* @returns {SecretKey}
+*/
+export function genSecretKey(): SecretKey;
+/**
+* Get the current `EvmNetwork` that was set using environment variables that were used during the build process of this library.
+* @returns {any}
+*/
+export function getEvmNetwork(): any;
+/**
+* Get a funded wallet for testing. This either uses a default private key or the `EVM_PRIVATE_KEY`
+* environment variable that was used during the build process of this library.
+* @returns {Wallet}
+*/
+export function getFundedWallet(): Wallet;
+/**
+* Enable tracing logging in the console.
+*
+* A level could be passed like `trace` or `warn`. Or set for a specific module/crate
+* with `sn_networking=trace,autonomi=info`.
+*
+* # Example
+*
+* ```js
+* logInit("sn_networking=warn,autonomi=trace");
+* ```
+* @param {string} directive
+*/
+export function logInit(directive: string): void;
+/**
+* Structure mapping paths to data addresses.
+*/
+export class Archive {
+  free(): void;
+/**
+* Create a new archive.
+*/
+  constructor();
+/**
+* Add a new file to the archive.
+* @param {string} path
+* @param {string} data_addr
+*/
+  addNewFile(path: string, data_addr: string): void;
+/**
+* @param {string} old_path
+* @param {string} new_path
+*/
+  renameFile(old_path: string, new_path: string): void;
+/**
+* @returns {any}
+*/
+  map(): any;
+}
+/**
+*/
+export class AttoTokens {
+  free(): void;
+/**
+* @returns {string}
+*/
+  toString(): string;
+}
+/**
+* The `Client` object allows interaction with the network to store and retrieve data.
+*
+* To connect to the network, see {@link Client.connect}.
+*
+* # Example
+*
+* ```js
+* let client = await Client.connect(["/ip4/127.0.0.1/tcp/36075/ws/p2p/12D3KooWALb...BhDAfJY"]);
+* const dataAddr = await client.dataPut(new Uint8Array([0, 1, 2, 3]), wallet);
+*
+* const archive = new Archive();
+* archive.addNewFile("foo", dataAddr);
+*
+* const archiveAddr = await client.archivePut(archive, wallet);
+* const archiveFetched = await client.archiveGet(archiveAddr);
+* ```
+*/
+export class Client {
+  free(): void;
+/**
+* Connect to the network via the given peers.
+*
+* # Example
+*
+* ```js
+* let client = await Client.connect(["/ip4/127.0.0.1/tcp/36075/ws/p2p/12D3KooWALb...BhDAfJY"]);
+* ```
+* @param {(string)[]} peers
+* @returns {Promise<Client>}
+*/
+  static connect(peers: (string)[]): Promise<Client>;
+/**
+* Upload a chunk to the network.
+*
+* Returns the hex encoded address of the chunk.
+*
+* This is not yet implemented.
+* @param {Uint8Array} _data
+* @param {Wallet} _wallet
+* @returns {Promise<string>}
+*/
+  chunkPut(_data: Uint8Array, _wallet: Wallet): Promise<string>;
+/**
+* Fetch the chunk from the network.
+* @param {string} addr
+* @returns {Promise<Uint8Array>}
+*/
+  chunkGet(addr: string): Promise<Uint8Array>;
+/**
+* Upload data to the network.
+*
+* Returns the hex encoded address of the data.
+* @param {Uint8Array} data
+* @param {Wallet} wallet
+* @returns {Promise<string>}
+*/
+  dataPut(data: Uint8Array, wallet: Wallet): Promise<string>;
+/**
+* Fetch the data from the network.
+* @param {string} addr
+* @returns {Promise<Uint8Array>}
+*/
+  dataGet(addr: string): Promise<Uint8Array>;
+/**
+* Get the cost of uploading data to the network.
+* @param {Uint8Array} data
+* @returns {Promise<AttoTokens>}
+*/
+  dataCost(data: Uint8Array): Promise<AttoTokens>;
+/**
+* Fetch an archive from the network.
+* @param {string} addr
+* @returns {Promise<Archive>}
+*/
+  archiveGet(addr: string): Promise<Archive>;
+/**
+* Upload an archive to the network.
+*
+* Returns the hex encoded address of the archive.
+* @param {Archive} archive
+* @param {Wallet} wallet
+* @returns {Promise<string>}
+*/
+  archivePut(archive: Archive, wallet: Wallet): Promise<string>;
+/**
+* Fetch the user data from the vault.
+*
+* # Example
+*
+* ```js
+* const secretKey = genSecretKey();
+* const userData = await client.getUserDataFromVault(secretKey);
+* ```
+* @param {SecretKey} secret_key
+* @returns {Promise<UserData>}
+*/
+  getUserDataFromVault(secret_key: SecretKey): Promise<UserData>;
+/**
+* Put the user data to the vault.
+*
+* # Example
+*
+* ```js
+* const secretKey = genSecretKey();
+* await client.putUserDataToVault(userData, wallet, secretKey);
+* ```
+* @param {UserData} user_data
+* @param {Wallet} wallet
+* @param {SecretKey} secret_key
+* @returns {Promise<void>}
+*/
+  putUserDataToVault(user_data: UserData, wallet: Wallet, secret_key: SecretKey): Promise<void>;
+}
+/**
+*/
+export class SecretKey {
+  free(): void;
+}
+/**
+* Structure to keep track of uploaded archives, registers and other data.
+*/
+export class UserData {
+  free(): void;
+/**
+* Create a new user data structure.
+*/
+  constructor();
+/**
+* Store an archive address in the user data with an optional name.
+*
+* # Example
+*
+* ```js
+* userData.addFileArchive(archiveAddr, "foo");
+* ```
+* @param {string} archive
+* @param {string | undefined} [name]
+*/
+  addFileArchive(archive: string, name?: string): void;
+/**
+* @param {string} archive
+*/
+  removeFileArchive(archive: string): void;
+/**
+* @returns {any}
+*/
+  fileArchives(): any;
+}
+/**
+*/
+export class Wallet {
+  free(): void;
+}
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+  readonly memory: WebAssembly.Memory;
+  readonly __wbg_client_free: (a: number, b: number) => void;
+  readonly __wbg_attotokens_free: (a: number, b: number) => void;
+  readonly attotokens_toString: (a: number, b: number) => void;
+  readonly client_connect: (a: number, b: number) => number;
+  readonly client_chunkPut: (a: number, b: number, c: number, d: number) => number;
+  readonly client_chunkGet: (a: number, b: number, c: number) => number;
+  readonly client_dataPut: (a: number, b: number, c: number, d: number) => number;
+  readonly client_dataGet: (a: number, b: number, c: number) => number;
+  readonly client_dataCost: (a: number, b: number, c: number) => number;
+  readonly __wbg_archive_free: (a: number, b: number) => void;
+  readonly archive_new: () => number;
+  readonly archive_addNewFile: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+  readonly archive_renameFile: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+  readonly archive_map: (a: number, b: number) => void;
+  readonly client_archiveGet: (a: number, b: number, c: number) => number;
+  readonly client_archivePut: (a: number, b: number, c: number) => number;
+  readonly __wbg_userdata_free: (a: number, b: number) => void;
+  readonly userdata_new: () => number;
+  readonly userdata_addFileArchive: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+  readonly userdata_removeFileArchive: (a: number, b: number, c: number, d: number) => void;
+  readonly userdata_fileArchives: (a: number, b: number) => void;
+  readonly client_getUserDataFromVault: (a: number, b: number) => number;
+  readonly client_putUserDataToVault: (a: number, b: number, c: number, d: number) => number;
+  readonly __wbg_secretkey_free: (a: number, b: number) => void;
+  readonly genSecretKey: () => number;
+  readonly getEvmNetwork: (a: number) => void;
+  readonly __wbg_wallet_free: (a: number, b: number) => void;
+  readonly getFundedWallet: () => number;
+  readonly logInit: (a: number, b: number) => void;
+  readonly BrotliDecoderCreateInstance: (a: number, b: number, c: number) => number;
+  readonly BrotliDecoderSetParameter: (a: number, b: number, c: number) => void;
+  readonly BrotliDecoderDecompressPrealloc: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number) => void;
+  readonly BrotliDecoderDecompressWithReturnInfo: (a: number, b: number, c: number, d: number, e: number) => void;
+  readonly BrotliDecoderDecompress: (a: number, b: number, c: number, d: number) => number;
+  readonly BrotliDecoderDecompressStream: (a: number, b: number, c: number, d: number, e: number, f: number) => number;
+  readonly BrotliDecoderDecompressStreaming: (a: number, b: number, c: number, d: number, e: number) => number;
+  readonly BrotliDecoderMallocU8: (a: number, b: number) => number;
+  readonly BrotliDecoderFreeU8: (a: number, b: number, c: number) => void;
+  readonly BrotliDecoderMallocUsize: (a: number, b: number) => number;
+  readonly BrotliDecoderFreeUsize: (a: number, b: number, c: number) => void;
+  readonly BrotliDecoderDestroyInstance: (a: number) => void;
+  readonly BrotliDecoderHasMoreOutput: (a: number) => number;
+  readonly BrotliDecoderTakeOutput: (a: number, b: number) => number;
+  readonly BrotliDecoderIsUsed: (a: number) => number;
+  readonly BrotliDecoderIsFinished: (a: number) => number;
+  readonly BrotliDecoderGetErrorCode: (a: number) => number;
+  readonly BrotliDecoderGetErrorString: (a: number) => number;
+  readonly BrotliDecoderErrorString: (a: number) => number;
+  readonly BrotliDecoderVersion: () => number;
+  readonly ring_core_0_17_8_bn_mul_mont: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+  readonly __wbindgen_malloc: (a: number, b: number) => number;
+  readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+  readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+  readonly __wbindgen_export_3: WebAssembly.Table;
+  readonly _dyn_core__ops__function__FnMut_____Output___R_as_wasm_bindgen__closure__WasmClosure___describe__invoke__hb1127ec8a5f76069: (a: number, b: number) => void;
+  readonly _dyn_core__ops__function__FnMut__A____Output___R_as_wasm_bindgen__closure__WasmClosure___describe__invoke__h7964ee7a46fd96a5: (a: number, b: number, c: number) => void;
+  readonly _dyn_core__ops__function__FnMut__A____Output___R_as_wasm_bindgen__closure__WasmClosure___describe__invoke__h6d1a6f0013d59045: (a: number, b: number, c: number) => void;
+  readonly _dyn_core__ops__function__FnMut_____Output___R_as_wasm_bindgen__closure__WasmClosure___describe__invoke__hdcedccdc30da04ac: (a: number, b: number) => void;
+  readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
+  readonly __wbindgen_exn_store: (a: number) => void;
+  readonly wasm_bindgen__convert__closures__invoke2_mut__h2d9c0b8c5965541d: (a: number, b: number, c: number, d: number) => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+/**
+* Instantiates the given `module`, which can either be bytes or
+* a precompiled `WebAssembly.Module`.
+*
+* @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+*
+* @returns {InitOutput}
+*/
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+* If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+* for everything else, calls `WebAssembly.instantiate` directly.
+*
+* @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+*
+* @returns {Promise<InitOutput>}
+*/
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;