Improve docs (#211)

* Remove abstract provider plugin logic

* Remove types and move a few files

* Better wallet docs and fix imports

* Big pass on jsdoc improvements

* Fix some imports not specifying `.js` file extension

* remove duplicated code on HDWallet and QiHDWallet

* FIX: bug in getOutpointsByAddress()

* remove _accounts map from AbstractHDWallet

* rewrite 'deriveAddressNode' method

* simplify logic on 'scan' and 'nextAddress' methods

* add JSDOC comments to methods

* extend sync method to sync all accounts

* rename method for clarity

* Improve comments for wallets

* Move type to types export

---------

Co-authored-by: Alejo Acosta <[email protected]>

src/_tests/test-abi.ts

@@ -3,7 +3,7 @@ import { loadTests } from './utils.js';
 
 import type { TestCaseAbi, TestCaseAbiVerbose } from './types.js';
 
-import { AbiCoder, Interface, decodeBytes32String, encodeBytes32String } from '../index.js';
+import { AbiCoder, Interface, decodeBytes32, encodeBytes32 } from '../index.js';
 
 function equal(actual: any, expected: TestCaseAbiVerbose): void {
     switch (expected.type) {
@@ -62,8 +62,8 @@ describe('Test Bytes32 strings', function () {
 
     for (const { name, str, expected } of tests) {
         it(`encodes and decodes Bytes32 strings: ${name}`, function () {
-            const bytes32 = encodeBytes32String(str);
-            const decoded = decodeBytes32String(bytes32);
+            const bytes32 = encodeBytes32(str);
+            const decoded = decodeBytes32(bytes32);
             assert.equal(bytes32, expected, 'formatted correctly');
             assert.equal(decoded, str, 'parsed correctly');
         });

src/_tests/test-providers-data.ts

@@ -123,7 +123,7 @@ async function sendTransaction(to: string) {
             } = {
                 from: wallet.address,
                 to,
-                value: quais.parseEther('0.1'), // Sending 0.1 ether
+                value: quais.parseQuai('0.1'), // Sending 0.1 ether
                 gasPrice: gas * 2,
                 maxFeePerGas: quais.parseUnits('20', 'gwei'),
                 maxPriorityFeePerGas: quais.parseUnits('20', 'gwei'),

src/_tests/test-utils-misc.ts

@@ -1,6 +1,7 @@
 import assert from 'assert';
 
-import { decodeBase64, encodeBase64, defineProperties, isError, toUtf8Bytes } from '../index.js';
+import { decodeBase64, encodeBase64, isError, toUtf8Bytes } from '../index.js';
+import { defineProperties } from '../utils/index.js';
 
 describe('Base64 Coding', function () {
     const tests = [

src/_tests/test-utils-units.ts

@@ -2,7 +2,7 @@ import assert from 'assert';
 
 import { loadTests } from './utils.js';
 
-import { formatEther, formatUnits, parseEther, parseUnits } from '../index.js';
+import { formatQuai, formatUnits, parseQuai, parseUnits } from '../index.js';
 
 import type { TestCaseUnit } from './types.js';
 
@@ -28,7 +28,7 @@ describe('Tests unit conversion', function () {
             it(`converts wei to ${unit} string: ${test.name}`, function () {
                 const wei = BigInt(test.wei);
                 if (decimals === 18) {
-                    assert.equal(formatEther(wei), str, 'formatEther');
+                    assert.equal(formatQuai(wei), str, 'formatQuai');
                     assert.equal(formatUnits(wei), str, 'formatUnits');
                 }
                 assert.equal(formatUnits(wei, unit), str, `formatUnits(${unit})`);
@@ -45,7 +45,7 @@ describe('Tests unit conversion', function () {
             it(`converts ${format} string to wei: ${test.name}`, function () {
                 const wei = BigInt(test.wei);
                 if (decimals === 18) {
-                    assert.equal(parseEther(str), wei, 'parseEther');
+                    assert.equal(parseQuai(str), wei, 'parseQuai');
                     assert.equal(parseUnits(str), wei, 'parseUnits');
                 }
                 assert.equal(parseUnits(str, unit), wei, `parseUnits(${unit})`);

src/_tests/test-utils-utf8.ts

@@ -1,6 +1,7 @@
 import assert from 'assert';
 
-import { toUtf8Bytes, toUtf8CodePoints, toUtf8String, Utf8ErrorFuncs } from '../index.js';
+import { toUtf8Bytes, toUtf8CodePoints, toUtf8String } from '../index.js';
+import { Utf8ErrorFuncs } from '../encoding/index.js';
 
 export type TestCaseBadString = {
     name: string;

src/abi/index.ts

@@ -9,8 +9,6 @@
 
 export { AbiCoder } from './abi-coder.js';
 
-export { decodeBytes32String, encodeBytes32String } from './bytes32.js';
-
 export {
     ConstructorFragment,
     ErrorFragment,

src/address/checks.ts

@@ -127,3 +127,31 @@ export function validateAddress(address: string): void {
     );
     assertArgument(formatMixedCaseChecksumAddress(address) === address, 'invalid address checksum', 'address', address);
 }
+
+/**
+ * Checks whether a given address is in the Qi ledger scope by checking the 9th bit of the address.
+ *
+ * @category Address
+ * @param {string} address - The address to check
+ *
+ * @returns {boolean} True if the address is in the Qi ledger scope, false otherwise.
+ */
+export function isQiAddress(address: string): boolean {
+    const secondByte = address.substring(4, 6);
+    const binaryString = parseInt(secondByte, 16).toString(2).padStart(8, '0');
+    const isUTXO = binaryString[0] === '1';
+
+    return isUTXO;
+}
+
+/**
+ * Checks whether a given address is in the Quai ledger scope by checking the 9th bit of the address.
+ *
+ * @category Address
+ * @param {string} address - The address to check
+ *
+ * @returns {boolean} True if the address is in the Quai ledger scope, false otherwise.
+ */
+export function isQuaiAddress(address: string): boolean {
+    return !isQiAddress(address);
+}

src/address/index.ts

@@ -31,8 +31,8 @@ export interface Addressable {
  */
 export type AddressLike = string | Promise<string> | Addressable;
 
-export { getAddress, computeAddress, recoverAddress, formatMixedCaseChecksumAddress } from './address.js';
+export { getAddress, computeAddress, recoverAddress, formatMixedCaseChecksumAddress, getContractAddress } from './address.js';
 
 export { getCreateAddress, getCreate2Address } from './contract-address.js';
 
-export { isAddressable, isAddress, resolveAddress, validateAddress } from './checks.js';
+export { isAddressable, isAddress, resolveAddress, validateAddress, isQuaiAddress, isQiAddress } from './checks.js';

src/constants/shards.ts

@@ -1,5 +1,12 @@
 import { ZoneData } from './zones.js';
 
+/**
+ * A shard represents a chain within the Quai network hierarchy. A shard refer to the Prime chain, a region under the
+ * Prime chain, or a Zone within a region. The value is a hexadecimal string representing the encoded value of the
+ * shard. Read more [here](https://github.com/quai-network/qips/blob/master/qip-0002.md).
+ *
+ * @category Constants
+ */
 export enum Shard {
     Cyprus = '0x0',
     Cyprus1 = '0x00',

src/constants/zones.ts

@@ -1,3 +1,10 @@
+/**
+ * A zone is the lowest level shard within the Quai network hierarchy. Zones are the only shards in the network that
+ * accept user transactions. The value is a hexadecimal string representing the encoded value of the zone. Read more
+ * [here](https://github.com/quai-network/qips/blob/master/qip-0002.md).
+ *
+ * @category Constants
+ */
 export enum Zone {
     Cyprus1 = '0x00',
     Cyprus2 = '0x01',