Merge pull request #47 from sarcophagus-org/docs

Fix docs

README.md

@@ -8,69 +8,45 @@ The Sarcophagus V2 SDK is a TypeScript library designed to simplify the interact
 - Supports custom signer and provider configurations
 - Provides utility functions for common tasks
 
-## Documentation
-Read more about how to use the Sarcophagus V2 SDK [here](https://sarcophagus-org.github.io/sarcophagus-v2-sdk/index.html).
-
 ## Installation
 
 To install the SDK, run the following command in your project directory:
 
-```
-npm install @sarcophagus-org/sarcophagus-v2-sdk
-```
-
-## Usage
-
-Here's a basic example of using the Sarcophagus V2 SDK in a TypeScript or JavaScript project:
-
-```typescript
-import { SarcoClient } from '@sarcophagus-org/sarcophagus-v2-sdk';
-
-// Initialize the client with a custom provider and signer
-const sarco = new SarcoClient({
-  signer: yourSignerInstance,
-  provider: yourProviderInstance,
-});
+For web environments:
 
-// Call the helloWorld method
-console.log(sarco.helloWorld());
+```
+npm install @sarcophagus-org/sarcophagus-v2-sdk-client
 ```
 
-## Configuration
-The SarcoClient constructor accepts an object with the following properties:
+For Node.js environments:
 
 ```
-signer (optional): An ethers Signer instance.
-privateKey (optional): A private key string.
-mnemonic (optional): A mnemonic phrase string.
-provider (optional): An ethers Provider instance. If not provided, a default provider will be used.
+npm install @sarcophagus-org/sarcophagus-v2-sdk
 ```
-At least one of signer, privateKey, or mnemonic must be provided when creating a new SarcoClient instance.
 
-## Methods
-### helloWorld
-A sample method that returns "Hello World".
+## Documentation
 
-```typescript
-helloWorld(): string;
-```
+Read more about how to use the Sarcophagus V2 SDK [here](https://sarcophagus-org.github.io/sarcophagus-v2-sdk/index.html).
 
 ## Local Development
-The SDK may be tested locally by cloning the SDK repository and linking it to your project. 
+
+The SDK may be tested locally by cloning the SDK repository and linking it to your project.
+
 ```
 git clone [email protected]:sarcophagus-org/sarcophagus-v2-sdk.git
 cd sarcophagus-v2-sdk
 npm run build
-npm link 
+npm link
 cd path/to/your/project
 npm link sarcophagus-v2-sdk
 ```
 
 Then it may be imported as if it were added to the package.json.
 
 ## Contributing
+
 We welcome contributions to the SDK. If you'd like to contribute, please submit an issue or open a pull request.
 
 ## License
-This project is licensed under The Unlicense license.
 
+This project is licensed under The Unlicense license.

docs.md

@@ -0,0 +1,189 @@
+##
+
+The Sarcophagus V2 SDK is a TypeScript library designed to simplify the interaction with the Sarcophagus V2 protocol. This SDK provides a high-level interface for developers to easily interact with the protocol's smart contracts and related services.
+
+## Installation
+
+To install the SDK, run the following command in your project directory:
+
+For web environments:
+
+```
+npm install @sarcophagus-org/sarcophagus-v2-sdk-client
+```
+
+For Node.js environments:
+
+```
+npm install @sarcophagus-org/sarcophagus-v2-sdk
+```
+
+<br>
+<br>
+
+# Typical Usage
+
+The Sarcophagus V2 SDK is designed to be used in both Web browser and Node.js environments, so initializing the sdk in either
+environment differs slightly, however, the usage of the sdk is the same in both environments.
+
+## Web Browser Environment
+
+The sdk exposes a [singleton](./variables/sarco.html) that you can import and use in your application:
+
+```typescript
+import { sarco } from '@sarcophagus-org/sarcophagus-v2-sdk-client';
+```
+
+## Node.js Environment
+
+The SDK exposes a [`NodeSarcoClient`](./classes/NodeSarcoClient.html) class that should be instantiated to use in your NodeJS application:
+
+```typescript
+import { NodeSarcoClient } from '@sarcophagus-org/sarcophagus-v2-sdk';
+// `privateKey` is the private key of the wallet you will use to interact with the Sarcophagus protocol
+const sarco = new NodeSarcoClient({ chainId, privateKey, providerUrl });
+```
+
+Before you can call any methods on the sdk, you must initialize it with a provider and signer.
+This will also boot up a LibP2P node that will be used to communicate with archaeologists registered on the Sarcophagus network.
+
+```typescript
+sarco
+  .init({
+    chainId: 1,
+    etherscanApiKey: 'etherscanApiKey', // not required
+    polygonScanApiKey: 'polygonScanApiKey', // not required
+    basescanApiKey: 'basescanApiKey', // not required
+    zeroExApiKey: 'zeroExApiKey', // only required if you want to use `swapEthForSarco` or `getSarcoQuote`
+  })
+  .then(networkConfig => {
+    console.log('SDK initialized!');
+    console.log('Network:', networkConfig.networkName);
+  });
+
+// Just `sarco.init()` for `NodeSarcoClient`
+```
+
+<br>
+
+The most common use, and the most complex part, of the Sarcophagus V2 SDK is [creating a sarcophagus](./classes/SarcophagusApi.html#createSarcophagus):
+
+```typescript
+// Prepare your Sarcophagus
+const name = 'My Sarcophagus';
+const recipientAddress = '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266';
+const resurrectionTimestamp = 1620000000;
+const file = new File(['sarcophagus file'], 'sarcophagus.txt', {
+  type: 'text/plain',
+});
+
+// Select the archaeologists you want to use
+const registeredArchaeologists = await sarco.archaeologist.getFullArchProfiles();
+const selectedArchaeologists = registeredArchaeologists.slice(0, 3);
+
+// Dial the selected archaeologists
+for await (const arch of selectedArchaeologists) {
+  const peerIdString = arch.profile.peerId;
+  try {
+    const connection = await sarco.archaeologist.dialArchaeologist(arch);
+    if (!connection) throw Error('No connection obtained from dial');
+    arch.connection = connection;
+  } catch (e) {
+    throw Error('Could not establish a connection');
+  }
+}
+
+// Request signatures and public keys from the selected archaeologists. This effectively establishes an agreement between each
+// archaeologist and the embalmer. The archaeologist agrees to resurrect the sarcophagus at the specified time
+// from `negotiationTimestamp`, and you agree to pay them their fee as specified in their profile.
+const [negotiationResult, negotiationTimestamp] = await sarco.archaeologist.initiateSarcophagusNegotiation(
+  selectedArchaeologists,
+  Math.floor(resurrectionTimestamp / 1000)
+);
+
+const archaeologistSignatures = new Map<`0x${string}` string>([]);
+const archaeologistPublicKeys = new Map<`0x${string}` string>([]);
+
+selectedArchaeologists.forEach(arch => {
+  const res = negotiationResult.get(arch.profile.peerId)!;
+  if (res.exception) {
+    console.log('arch exception:', arch.profile.archAddress, res.exception);
+  } else {
+    archaeologistPublicKeys.set(arch.profile.archAddress, res.publicKey!);
+    archaeologistSignatures.set(arch.profile.archAddress, res.signature!);
+  }
+});
+
+if (archaeologistPublicKeys.size !== selectedArchaeologists.length) {
+  throw Error('Not enough public keys');
+}
+
+if (archaeologistSignatures.size !== selectedArchaeologists.length) {
+  throw Error('Not enough signatures');
+}
+
+// At least this many archaeologists must be present in order to resurrect the sarcophagus.
+// Generally, the more archaeologists you select, the more secure your sarcophagus will be.
+// But keep in mind that the more archaeologists you select, the more expensive it will be to resurrect the sarcophagus,
+// and the more chance there will be that one of the archaeologists will be unavailable to resurrect the sarcophagus.
+// Try to choose archaeologists that you can be confident will be available at the time of resurrection.
+const requiredArchaeologists = selectedArchaeologists.length;
+
+// Upload the file to Arweave
+const { publicKey, privateKey } = sarco.utils.generateKeyPair();
+ const uploadPromise = sarco.api.uploadFileToArweave({
+    file,
+    archaeologistPublicKeys: Array.from(archaeologistPublicKeys.values()),
+    recipientPublicKey,
+    shares: selectedArchaeologists.length,
+    threshold: requiredArchaeologists,
+    onStep: (step: string) => {
+        console.log('Processing step: ', step);
+    },
+    onUploadChunk: (chunkedUploader: any, chunkedUploadProgress: number) => {
+        console.log('Uploading chunk: ', chunkedUploadProgress);
+    },
+    onUploadChunkError: (msg: string) => {
+        console.error(msg);
+    },
+    onUploadComplete: (uploadId: string) => {
+        console.log('Upload complete. `arweaveTxId`: ', uploadId);
+        // As this is a callback, you will need to persist `arweaveTxId` somewhere so that you can use it later
+        // in `formatSubmitSarcophagusArgs`
+    },
+    payloadPrivateKey: privateKey,
+    payloadPublicKey: publicKey,
+});
+
+// Process and format the arguments for the `createSarcophagus` method
+const { submitSarcophagusArgs } = sarco.api.formatSubmitSarcophagusArgs({
+    name,
+    recipientAddress,
+    resurrectionTimestamp,
+    selectedArchaeologists,
+    requiredArchaeologists,
+    negotiationTimestamp,
+    archaeologistPublicKeys,
+    archaeologistSignatures,
+    arweaveTxId,
+});
+
+const tx = await sarco.api.createSarcophagus(...submitSarcophagusArgs);
+console.log('Sarcophagus created!! Transaction hash: ', tx.hash);
+```
+
+## <br>
+
+<br>
+
+# API Reference
+
+Use the links on the left panel to navigate the API reference.
+Some tips on where to start looking:
+
+- [SarcophagusApi](./classes/SarcophagusApi.html) - The class that exposes functionality for interacting with the Sarcophagi on the Sarcophagus protocol.
+- [ArchaeologistApi](./classes/ArchaeologistApi.html) - The class that exposes functionality for interacting with registered Archaeologists on the Sarcophagus network.
+- [Token](./classes/Token.html) - The class that exposes functionality for interacting with the `$SARCO` ERC20 token.
+- [SarcoWebBundlr](./classes/SarcoWebBundlr.html) - The class that exposes functionality for interacting with the Sarcophagus Web Bundlr service
+  (The NodeJS SDK does not use this class -- it exposes `Bundlr` from `@bundlr-network/client/build/cjs/node/bundlr` directly).
+- [Utils](./classes/Utils.html) - The class that exposes a variety of useful utility functions.

docs/assets/highlight.css

@@ -15,6 +15,10 @@
     --dark-hl-6: #4FC1FF;
     --light-hl-7: #795E26;
     --dark-hl-7: #DCDCAA;
+    --light-hl-8: #098658;
+    --dark-hl-8: #B5CEA8;
+    --light-hl-9: #267F99;
+    --dark-hl-9: #4EC9B0;
     --light-code-background: #FFFFFF;
     --dark-code-background: #1E1E1E;
 }
@@ -28,6 +32,8 @@
     --hl-5: var(--light-hl-5);
     --hl-6: var(--light-hl-6);
     --hl-7: var(--light-hl-7);
+    --hl-8: var(--light-hl-8);
+    --hl-9: var(--light-hl-9);
     --code-background: var(--light-code-background);
 } }
 
@@ -40,6 +46,8 @@
     --hl-5: var(--dark-hl-5);
     --hl-6: var(--dark-hl-6);
     --hl-7: var(--dark-hl-7);
+    --hl-8: var(--dark-hl-8);
+    --hl-9: var(--dark-hl-9);
     --code-background: var(--dark-code-background);
 } }
 
@@ -52,6 +60,8 @@
     --hl-5: var(--light-hl-5);
     --hl-6: var(--light-hl-6);
     --hl-7: var(--light-hl-7);
+    --hl-8: var(--light-hl-8);
+    --hl-9: var(--light-hl-9);
     --code-background: var(--light-code-background);
 }
 
@@ -64,6 +74,8 @@
     --hl-5: var(--dark-hl-5);
     --hl-6: var(--dark-hl-6);
     --hl-7: var(--dark-hl-7);
+    --hl-8: var(--dark-hl-8);
+    --hl-9: var(--dark-hl-9);
     --code-background: var(--dark-code-background);
 }
 
@@ -75,4 +87,6 @@
 .hl-5 { color: var(--hl-5); }
 .hl-6 { color: var(--hl-6); }
 .hl-7 { color: var(--hl-7); }
+.hl-8 { color: var(--hl-8); }
+.hl-9 { color: var(--hl-9); }
 pre, code { background: var(--code-background); }