Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(autonomi): add WASM docs #2341

Merged
merged 5 commits into from
Oct 28, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 1 addition & 5 deletions .github/workflows/merge.yml
Original file line number Diff line number Diff line change
@@ -110,10 +110,6 @@ jobs:

- uses: Swatinem/rust-cache@v2

- name: Run autonomi tests
timeout-minutes: 25
run: cargo test --release --package autonomi --lib --features="full,fs"

- name: Run node tests
timeout-minutes: 25
run: cargo test --release --package sn_node --lib
@@ -192,7 +188,7 @@ jobs:

# only these unit tests require a network, the rest are run above in unit test section
- name: Run autonomi --tests
run: cargo test --package autonomi --features="full,fs" --tests -- --nocapture
run: cargo test --package autonomi --tests -- --nocapture
env:
SN_LOG: "v"
# only set the target dir for windows to bypass the linker issue.
17 changes: 0 additions & 17 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

41 changes: 13 additions & 28 deletions autonomi-cli/src/utils.rs
Original file line number Diff line number Diff line change
@@ -6,40 +6,28 @@
// 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.

use autonomi::client::{Amount, ClientEvent};

/// Summary of the upload operation.
#[derive(Debug, Clone)]
pub struct CliUploadSummary {
/// Total tokens spent during the upload.
pub tokens_spent: Amount,
/// Total number of records uploaded.
pub record_count: usize,
}
use autonomi::client::{Amount, ClientEvent, UploadSummary};

/// Collects upload summary from the event receiver.
/// Send a signal to the returned sender to stop collecting and to return the result via the join handle.
pub fn collect_upload_summary(
mut event_receiver: tokio::sync::mpsc::Receiver<ClientEvent>,
) -> (
tokio::task::JoinHandle<CliUploadSummary>,
tokio::task::JoinHandle<UploadSummary>,
tokio::sync::oneshot::Sender<()>,
) {
let (upload_completed_tx, mut upload_completed_rx) = tokio::sync::oneshot::channel::<()>();
let stats_thread = tokio::spawn(async move {
let mut tokens: Amount = Amount::from(0);
let mut records = 0;
let mut tokens_spent: Amount = Amount::from(0);
let mut record_count = 0;

loop {
tokio::select! {
event = event_receiver.recv() => {
match event {
Some(ClientEvent::UploadComplete {
tokens_spent,
record_count
}) => {
tokens += tokens_spent;
records += record_count;
Some(ClientEvent::UploadComplete(upload_summary)) => {
tokens_spent += upload_summary.tokens_spent;
record_count += upload_summary.record_count;
}
None => break,
}
@@ -51,19 +39,16 @@ pub fn collect_upload_summary(
// try to drain the event receiver in case there are any more events
while let Ok(event) = event_receiver.try_recv() {
match event {
ClientEvent::UploadComplete {
tokens_spent,
record_count,
} => {
tokens += tokens_spent;
records += record_count;
ClientEvent::UploadComplete(upload_summary) => {
tokens_spent += upload_summary.tokens_spent;
record_count += upload_summary.record_count;
}
}
}

CliUploadSummary {
tokens_spent: tokens,
record_count: records,
UploadSummary {
tokens_spent,
record_count,
}
});

5 changes: 0 additions & 5 deletions autonomi/Cargo.toml
Original file line number Diff line number Diff line change
@@ -30,11 +30,9 @@ bytes = { version = "1.0.1", features = ["serde"] }
curv = { version = "0.10.1", package = "sn_curv", default-features = false, features = [
"num-bigint",
] }
custom_debug = "~0.6.1"
eip2333 = { version = "0.2.1", package = "sn_bls_ckd" }
const-hex = "1.12.0"
hex = "~0.4.3"
itertools = "~0.12.1"
libp2p = "0.54.1"
rand = "0.8.5"
rmp-serde = "1.1.1"
@@ -60,13 +58,10 @@ blstrs = "0.7.1"

[dev-dependencies]
alloy = { version = "0.5.3", default-features = false, features = ["std", "reqwest-rustls-tls", "provider-anvil-node", "sol-types", "json", "signers", "contract", "signer-local", "network"] }
assert_matches = "1.5.0"
eyre = "0.6.5"
sha2 = "0.10.6"
sn_logging = { path = "../sn_logging", version = "0.2.37" }
sn_peers_acquisition = { path = "../sn_peers_acquisition", version = "0.5.4" }
sn_registers = { path = "../sn_registers", version = "0.4.0", features = ["test-utils"] }
tempfile = "3.6.0"
# Do not specify the version field. Release process expects even the local dev deps to be published.
# Removing the version field is a workaround.
test_utils = { path = "../test_utils" }
156 changes: 8 additions & 148 deletions autonomi/WASM_docs.md
Original file line number Diff line number Diff line change
@@ -1,160 +1,24 @@
## JavaScript Autonomi API Documentation
# JavaScript Autonomi API Documentation

Note that this is a first version and will be subject to change.

### **Client**
The entry point for connecting to the network is {@link Client.connect}.

The `Client` object allows interaction with the network to store and retrieve data. Below are the available methods for the `Client` class.
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.

#### **Constructor**
## Addresses

```javascript
let client = await new Client([multiaddress]);
```

- **multiaddress** (Array of Strings): A list of network addresses for the client to connect to.

Example:
```javascript
let client = await new Client(["/ip4/127.0.0.1/tcp/36075/ws/p2p/12D3KooWALb...BhDAfJY"]);
```

#### **Methods**

##### **put(data, wallet)**

Uploads a piece of encrypted data to the network.

```javascript
let result = await client.put(data, wallet);
```

- **data** (Uint8Array): The data to be stored.
- **wallet** (Wallet): The wallet used to pay for the storage.

Returns:
- **result** (XorName): The XOR address of the stored data.

Example:
```javascript
let wallet = getFundedWallet();
let data = new Uint8Array([1, 2, 3]);
let result = await client.put(data, wallet);
```

##### **get(data_map_addr)**

Fetches encrypted data from the network using its XOR address.

```javascript
let data = await client.get(data_map_addr);
```

- **data_map_addr** (XorName): The XOR address of the data to fetch.

Returns:
- **data** (Uint8Array): The fetched data.

Example:
```javascript
let data = await client.get(result);
```

##### **cost(data)**

Gets the cost of storing the provided data on the network.

```javascript
let cost = await client.cost(data);
```

- **data** (Uint8Array): The data whose storage cost you want to calculate.

Returns:
- **cost** (AttoTokens): The calculated cost for storing the data.

Example:
```javascript
let cost = await client.cost(new Uint8Array([1, 2, 3]));
```

---

### **Wallet**

The `Wallet` object represents an Ethereum wallet used for data payments.

#### **Methods**

##### **new_from_private_key(network, private_key)**

Creates a new wallet using the given private key.

```javascript
let wallet = Wallet.new_from_private_key(network, private_key);
```
For addresses (chunk, data, archives, etc) we're using hex-encoded strings containing a 256-bit XOR addresse. For example: `abcdefg012345678900000000000000000000000000000000000000000000000`.

- **network** (EvmNetwork): The network to which the wallet connects.
- **private_key** (String): The private key of the wallet.

Returns:
- **wallet** (Wallet): The created wallet.

Example:
```javascript
let wallet = Wallet.new_from_private_key(EvmNetwork.default(), "your_private_key_here");
```

##### **address()**

Gets the wallet’s address.
## Example

```javascript
let address = wallet.address();
```

Returns:
- **address** (Address): The wallet's address.
import init, { Client, Wallet, getEvmNetwork } from 'autonomi';

Example:
```javascript
let wallet = Wallet.new_from_private_key(EvmNetwork.default(), "your_private_key_here");
let address = wallet.address();
```

---

### **EvmNetwork**

The `EvmNetwork` object represents the blockchain network.

#### **Methods**

##### **default()**

Connects to the default network.

```javascript
let network = EvmNetwork.default();
```

Returns:
- **network** (EvmNetwork): The default network.

Example:
```javascript
let network = EvmNetwork.default();
```

---

### Example Usage:

```javascript
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(EvmNetwork.default(), "your_private_key_here");
let wallet = Wallet.new_from_private_key(getEvmNetwork, "your_private_key_here");
console.log("wallet retrieved");

let data = new Uint8Array([1, 2, 3]);
@@ -164,7 +28,3 @@ console.log("Data stored at:", result);
let fetchedData = await client.get(result);
console.log("Data retrieved:", fetchedData);
```

---

This documentation covers the basic usage of `Client`, `Wallet`, and `EvmNetwork` types in the JavaScript API.
Loading
Loading