Development/alex/dag4 v1.2.0 (#4)

* Refactored tx handling to use Transaction class * Migrated repo to use npm workspaces * Added block explorer V2 methods + types * Added L0 +L1 API methods + types * Updated endpoints to new plural standard * moved dag4 source into src dir * Switched curve lib to noble/secp256k1 to fix sporadic invalid sig issue * Added additional V2 network endpoints * Added default network config to wallet * Added personalSign method * Return null instead of throwing when txns not found * Updated README for 1.2.0 * Deprecated dag4-xchains * v1.2.0
StardustCollective · Jul 22, 2022 · c72fb38 · c72fb38
1 parent af6f9e2
commit c72fb38
Show file tree

Hide file tree

Showing 74 changed files with 19,943 additions and 11,035 deletions.
diff --git a/.gitignore b/.gitignore
@@ -7,4 +7,6 @@ bak/
 # dependencies
 node_modules/
 
+# local files
+.DS_Store
 scratch/
diff --git a/README.md b/README.md
@@ -1,7 +1,7 @@
 
-# DAG4 - DAG JavaScript API
+# DAG4 - DAG JavaScript SDK
 
-This is the DAG [JavaScript API][docs] for Constellation Network.
+This is the DAG [JavaScript SDK][docs] for Constellation Network.
 
 Please read the [documentation][docs] for more detailed instructions. The following includes basic install and configuration.
 
@@ -21,78 +21,167 @@ yarn add @stardust-collective/dag4
 
 ## Usage
 
+### Interacting with wallets
+
+Create a private key
 ```js
-// In Node.js
-const fetch = require('node-fetch');
-const { dag4 } = require("@stardust-collective/dag4");
-
-dag4.di.useFetchHttpClient(fetch);
-dag4.network.config({
-    beUrl: 'https://block-explorer.constellationnetwork.io',
-    lbUrl: 'http://lb.constellationnetwork.io:9000'
-})
+const pk = dag4.keyStore.generatePrivateKey();
 ```
 
-Now you can use it to:
+Login with the private key
+```js
+dag4.account.loginPrivateKey(pk);
+```
 
-```ts
-// Get latest snapshot from the block explorer
-dag4.network.blockExplorerApi.getLatestSnapshot();
+Check DAG address
+```js
+const address = dag4.account.address;
+```
+
+### Connecting to the network
+```js
+import { dag4 } from '@stardust-collective/dag4';
+
+// Connect to default network endpoints
+dag4.account.connect({
+    networkVersion: '2.0',
+    testnet: true
+})
 
-// Get the total supply from a validator node
-dag4.network.loadBalancerApi.getTotalSupply();
+// Or provide specific configuration
+// L0/L1 urls can point to a specific node
+dag4.account.connect({
+    networkVersion: '2.0',
+    beUrl: 'https://be-testnet.constellationnetwork.io',
+    l0Url: 'http://13.52.246.74:9000',
+    l1Url: 'http://13.52.246.74:9010'
+})
+```
+
+Check address balance
+```js
+// Get an address balance
+const balance = await dag4.network.getAddressBalance('DAGabc123...');
+```
+
+Get address last reference
+```js
+dag4.network.getAddressLastAcceptedTransactionRef('DAGabc123...');
 ```
 
-### Usage with TypeScript
 
-We support types within the repo itself. Please open an issue here if you find any wrong types.
+### Sending transactions
+Dag4.js supports both online and offline transaction signing as well as bulk transaction sending. You must be logged in with a pk and connected to the network to send transactions. 
 
-You can use `dag4.js` as follows:
+Send a single transaction
+```js
+const toAddress = 'DAGabc123...';
+const amount = 25.551;
+const fee = 0;
 
-import dag4
+dag4.account.transferDag(toAddress, amount, fee);
+```
 
-```typescript
-import { dag4 } from '@stardust-collective/dag4';
+Send bulk transactions
+```js
+const transfers = [
+    {address: 'DAGabc123...', amount: 0.000123, fee: 0},
+    {address: 'DAGabc124...', amount: 0.000124, fee: 0},
+    {address: 'DAGabc125...', amount: 0.000125, fee: 0},
+    {address: 'DAGabc126...', amount: 0.000126, fee: 0},
+    {address: 'DAGabc127...', amount: 0.000127, fee: 0},
+    {address: 'DAGabc128...', amount: 0.000128, fee: 0.00000001}
+];
+
+  const hashes = await dag4.account.transferDagBatch(transfers);
 ```
 
-Configure Network
-```ts
-import fetch from 'node-fetch';
+Sign transactions offline, then send online
+```js
+// First get the last txn reference, this can also be retrieved from an offline source
+const lastRef = await dag4.network.getAddressLastAcceptedTransactionRef('DAGWalletSendingAddress');
 
-dag4.di.useFetchHttpClient(fetch);
-dag4.network.config({
-   beUrl: 'https://block-explorer.constellationnetwork.io',
-   lbUrl: 'http://lb.constellationnetwork.io:9000'
-})
+const transfers = [
+    {address: 'DAGabc123...', amount: 0.000123, fee: 0},
+    {address: 'DAGabc124...', amount: 0.000124, fee: 0}
+];
+
+const txns = await dag4.account.generateBatchTransactions(transfers, lastRef);
+
+// Send online when ready
+const hashes = await dag4.account.sendBatchTransactions(txns);
 ```
 
-If you are using the types in a `commonjs` module, like in a Node app, you have to enable `esModuleInterop` and `allowSyntheticDefaultImports` in your `tsconfig` for typesystem compatibility:
+### Checking transaction status
+When a transaction is sent to the network and is accepted, the response will return a hash that can be used to monitor the status of the transaction.
+
+The transaction will initially be in a "waiting" state before it's included in a block and sent to a snapshot. While in this state you can check its status with the L1 API. Once processed by the network, the transaction will no longer be found via the L1 API and will be found in the block explorer API. At this point the transaction is considered final.
+
+The following process can be used to confirm a transaction has been processed and reached a successful final state.
 
 ```js
-"compilerOptions": {
-    "allowSyntheticDefaultImports": true,
-    "esModuleInterop": true,
-    ....
+// Send transaction
+const hash = await dag4.network.postTransaction(txn);
+
+// Keep checking the transaction status until this returns null
+const pendingTx = await dag4.network.getPendingTransaction(txHash);
+
+// Check that the transaction has registered on the block explore API
+if (pendingTx === null) {
+  const confirmedTx = await dag4.network.getTransaction(txHash);
+
+  if (confirmedTx) {
+    // Txn is confirmed - from this point the state cannot be changed
+    console.log('Transaction confirmed');
+  } else {
+    // The txn cannot be found on block explorer. It's a good idea to wait several seconds and try again to confirm the txn has actually been dropped
+    console.log('Transaction dropped - not confirmed');
+  }
+}
 ```
 
-## Documentation
+### Upgrading from networkVersion 1.0
+v1.2.0 of the dag4 package introduces support for Constellation mainnet 2.0 and a number of new features 
+specific to the new network version. It is also 100% backwards compatible with existing mainnet 1.0 
+integrations from earlier versions (1.1.x) of the package. Not all endpoints relevant to mainnet 1.0 
+are used in 2.0 though so there is a migration process to prepare for the switchover in networks. 
 
-Documentation can be found at [Wiki][docs].
+Migrate all calls to specific APIs to use dag4.network
+```js
+// Mainnet 1.0
+await dag4.network.loadBalancerApi.getAddressLastAcceptedTransactionRef('DAGabc123');
 
-## Building
+// Mainnet 1.0 and 2.0 support based on configured network version
+await dag4.network.getAddressLastAcceptedTransactionRef('DAGabc123');
+```
 
-### Requirements
+Use dag4.account as much as possible
+```js
+// mainnet 1.0
+await dag4.keyStore.generateTransaction(...);
 
--   [Node.js](https://nodejs.org)
--   [npm](https://www.npmjs.com/)
+// mainnet 1.0 and 2.0 support based on configured network version
+await dag4.account.generateSignedTransaction(...);
+```
 
-```bash
-sudo apt-get update
-sudo apt-get install nodejs
-sudo apt-get install npm
+After the above changes, both versions of the network are supported with a configuration change
+```js
+// mainnent 1.0 support
+dag4.account.connect({
+    networkVersion: '1.0'
+});
+
+// mainnet 2.0 support
+dag4.account.connect({
+    networkVersion: '2.0'
+});
 ```
 
-### Building (DAG4)
+## Documentation
+
+Documentation can be found at [Wiki][docs].
+
+## Building
 
 Build the dag4.js package:
 
@@ -103,21 +192,17 @@ npm run build
 ### Testing (mocha)
 
 ```bash
-npm test
+npm test --workspaces
 ```
 
 ### Community
 
--   [Discord][discord-url]
--   [Telegram][telegram-url]
+-   [Discord](https://discord.gg/bb8SCX9sWk)
+-   [Constellation Telegram](https://t.me/constellationcommunity)]
+-   [Stardust Telegram](https://t.me/StardustSupport)]
 
 ---
 ### License
 [![License: GPL v3](https://img.shields.io/badge/License-MIT-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
 This project is licensed under the terms of the **MIT** license.
 
-[repo]: https://github.com/StardustCollective/dag4.js
-[npm-url]: https://npmjs.org/package/dag4
-[docs]: https://github.com/StardustCollective/dag4.js/wiki
-[discord-url]: https://discord.gg/bb8SCX9sWk
-[telegram-url]: https://t.me/StardustSupport