Additional Creditcoin js examples

creditcoin-js/README.md

@@ -1,6 +1,150 @@
 # creditcoin-js
 
-**WARNING**: This is an alpha version of creditcoin-js. It is not ready for production use. It will have breaking changes often.
+## Getting started
+
+### Preqrequisites
+
+Creditcoin-js requires the following to be installed:
+
+-   [Node.js](https://nodejs.org/en/)
+-   [TypeScript](https://www.typescriptlang.org/)
+
+### Install
+
+Adding Creditcoin-JS to your project is easy. Install it by using your favorite package manager:
+
+```shell
+yarn add creditcoin-js
+```
+
+This will install the latest release version, which should allow you to interact with Creditcoin's main network and your own local chains that use the latest Creditcoin binaries.
+
+## Usage
+
+### Import
+
+Importing the library into your project:
+
+```typescript
+import { creditcoinApi } from 'creditcoin-js';
+
+const { api } = await CreditcoinApi('ws://localhost:9944');
+
+// don't forget to disconnect when you are done
+await api.disconnect();
+```
+
+### Using the API
+
+The API is a collection of modules that provide access to the various functions of the Creditcoin blockchain.
+
+```typescript
+const { api, extrinsics, utils } = await CreditcoinApi('ws://localhost:9944');
+```
+
+### Creating transactions
+
+```typescript
+const { api } = await CreditcoinApi('ws://localhost:9944');
+
+const tx = api.
+    .tx
+    .balances
+    .transfer(
+        "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY",
+        "1000000000000000"  // CTC amount in microunits
+                            // (1 CTC = 1e18 microunits)
+    )
+```
+
+### Signing & sending
+
+```typescript
+import { Keyring } from 'creditcoin-js';
+
+const keyring = new Keyring({ type: 'sr25519' });
+const alice = keyring.addFromUri('//Alice');
+
+await tx.signAndSend(alice);
+```
+
+### Batching transactions
+
+```typescript
+const tx1 = api.tx.balances.transfer(addrBob, 10);
+const tx2 = api.tx.balances.transfer(addrCharlie, 10);
+const txs = [tx1, tx2];
+
+const batch_tx = api.tx.utility.batch(txs);
+
+await batch_tx.signAndSend(alice);
+```
+
+### Registering External Addresses
+See `src/examples/register-address-v2.ts` for an example or the integration test at `../integration-tests/src/test/register-address-v2.test.s`.
+
+### Swap GCRE -> CTC
+See `src/examples/collect-coins-v2.ts` for an example or the integration test at `../integration-tests/src/test/gate-token.test.ts`.
+
+### Reading Runtime Constants
+```typescript
+import { U64, U32 } from "@polkadot/types-codec";
+
+const { api } = ccApi;
+
+const expectedBlockTime = (api.consts.babe.expectedBlockTime as U64).toNumber()
+const unverifiedTaskTimeout = (api.consts.creditcoin.unverifiedTaskTimeout as u32).toNumber();
+
+const taskTimeout = expectedBlockTime * unverifiedTaskTimeout;
+```
+
+
+### Setting Offchain Local Storage (Ethereum RPC URI)
+```typescript
+function u8aToHex = (bytes: Uint8Array): string {
+    return bytes.reduce((str, byte) => str + byte.toString(16).padStart(2, '0'), '0x');
+};
+
+const rpcUri = u8aToHex(api.createType('String', 'http://localhost:8545').toU8a());
+await api.rpc.offchain.localStorageSet('PERSISTENT', 'ethereum-rpc-uri', rpcUri);
+```
+
+### Submitting Sudo Calls (Set CollectCoins Contract)
+See `src/examples/set-collect-coins-contract.ts` for an example or the integration test at `../integration-tests/src/test/set-collect-coins-contract.test.ts`.
+
+## Development
+
+### Build
+
+To build the project, run the following command from the root directory:
+
+```shell
+yarn build
+```
+
+### Updating Type definitions
+
+Creditcoin-JS uses actual chain metadata to generate the API types and augmented endpoints. When the Creditcoin blockchain gets updated and includes new extrinsics or storage fields in it’s pallets, Creditcoin-JS must regenerate its types to include the newly available methods.
+
+1. Fetch Chain Metadata
+
+This process begins with pulling the current metadata from a running creditcoin-node by making an RPC call:
+
+```shell
+curl -H "Content-Type: application/json" -d '{"id":"1", "jsonrpc":"2.0", "method": "state_getMetadata", "params":[]}' http://localhost:9933
+```
+
+2. Add Metadata to creditcoin.json
+
+The full JSON output must be saved into a creditcoin.json file as specified by the generation scripts included in package.json.
+
+3. Generate Types
+
+The types can be generated by running the following command:
+
+```shell
+yarn build:types
+```
 
 ## Errors & Troubleshooting
 

creditcoin-js/src/examples/collect-coins-v2.ts

@@ -0,0 +1,21 @@
+import { CreditcoinApi } from '../types';
+import { CollectCoinsContract } from '../model';
+import { KeyringPair } from '@polkadot/keyring/types';
+
+export async function collectCoinsV2Example(
+    ccApi: CreditcoinApi,
+    burnDetails: CollectCoinsContract,
+    creditcoinSigner: KeyringPair,
+) {
+    const {
+        extrinsics: { requestCollectCoinsV2 },
+    } = ccApi;
+
+    // Submit the swap request, adding it to the task queue of the off chain worker
+    const collectCoins = await requestCollectCoinsV2(burnDetails, creditcoinSigner);
+
+    // Wait for the offchain worker to finish processing this request
+    // Under the hood waitForVerification tracks CollectedCoinsMinted and CollectedCoinsFailedVerification events using the TaskId as a unique key
+    // 900_000 (milliseconds) comes from an assumed 60 block task timeout deadline and assumed 15 second blocktime (check the constants provided by the runtime in production code)
+    return await collectCoins.waitForVerification(900_000);
+}

creditcoin-js/src/examples/register-address-v2.ts

@@ -0,0 +1,26 @@
+import { CreditcoinApi } from '../types';
+import { Wallet } from 'ethers';
+import { Blockchain } from '../model';
+import { personalSignAccountId } from '../utils';
+import { KeyringPair } from '@polkadot/keyring/types';
+import { personalSignSignature } from '../extrinsics/register-address-v2';
+
+export async function registerAddressV2Example(
+    ccApi: CreditcoinApi,
+    ethSigner: Wallet,
+    creditcoinAddress: KeyringPair,
+    blockchain: Blockchain,
+) {
+    const {
+        api,
+        extrinsics: { registerAddressV2 },
+    } = ccApi;
+
+    const accountId = creditcoinAddress.addressRaw;
+    const externalAddress = ethSigner.address;
+
+    const signature = await personalSignAccountId(api, ethSigner, accountId);
+    const proof = personalSignSignature(signature);
+
+    return registerAddressV2(externalAddress, blockchain, proof, creditcoinAddress);
+}

creditcoin-js/src/examples/set-collect-coins-contract.ts

@@ -0,0 +1,19 @@
+import { KeyringPair } from '@polkadot/keyring/types';
+import { Blockchain } from 'src/model';
+import { CreditcoinApi } from 'src/types';
+
+export async function setCollectCoinsContractExample(
+    ccApi: CreditcoinApi,
+    contractAddress: string,
+    blockchain: Blockchain,
+    sudoSigner: KeyringPair,
+) {
+    const { api } = ccApi;
+
+    const contract = api.createType('PalletCreditcoinOcwTasksCollectCoinsDeployedContract', {
+        address: contractAddress,
+        chain: blockchain,
+    });
+
+    await api.tx.sudo.sudo(api.tx.creditcoin.setCollectCoinsContract(contract)).signAndSend(sudoSigner, { nonce: -1 });
+}

integration-tests/src/test/gate-token.test.ts

@@ -10,6 +10,7 @@ import { mnemonicGenerate } from '@polkadot/util-crypto';
 import { signAccountId } from 'creditcoin-js/lib/utils';
 import { GATEContract } from 'creditcoin-js/lib/extrinsics/request-collect-coins-v2';
 import { testIf } from '../utils';
+import { collectCoinsV2Example } from 'creditcoin-js/lib/examples/collect-coins-v2';
 
 describe('Test GATE Token', (): void => {
     let ccApi: CreditcoinApi;
@@ -37,7 +38,20 @@ describe('Test GATE Token', (): void => {
         if ((global as any).CREDITCOIN_EXECUTE_SETUP_AUTHORITY) {
             sudoSigner = (global as any).CREDITCOIN_CREATE_SIGNER(keyring, 'lender');
         }
-    });
+
+        const { api } = ccApi;
+
+        await api.tx.sudo
+            .sudo(api.tx.balances.setBalance(gateFaucet.address, 1000, 0))
+            .signAndSend(sudoSigner, { nonce: -1 });
+
+        // Set the on chain location for the burn contract to be the address of the deployer wallet
+        const contract = api.createType('PalletCreditcoinOcwTasksCollectCoinsDeployedContract', {
+            address: gateToken.address,
+            chain: testingData.blockchain,
+        });
+        await api.tx.sudo.sudo(api.tx.creditcoin.setGateContract(contract)).signAndSend(sudoSigner, { nonce: -1 });
+    }, 900_000);
 
     afterAll(async () => {
         await ccApi.api.disconnect();
@@ -52,17 +66,6 @@ describe('Test GATE Token', (): void => {
                 extrinsics: { requestCollectCoinsV2 },
             } = ccApi;
 
-            await api.tx.sudo
-                .sudo(api.tx.balances.setBalance(gateFaucet.address, 1000, 0))
-                .signAndSend(sudoSigner, { nonce: -1 });
-
-            // Set the on chain location for the burn contract to be the address of the deployer wallet
-            const contract = api.createType('PalletCreditcoinOcwTasksCollectCoinsDeployedContract', {
-                address: gateToken.address,
-                chain: testingData.blockchain,
-            });
-            await api.tx.sudo.sudo(api.tx.creditcoin.setGateContract(contract)).signAndSend(sudoSigner, { nonce: -1 });
-
             const mintTx = await gateToken.mint(deployer.address, 2500);
             await mintTx.wait(3);
             const balance = await gateToken.balanceOf(deployer.address);
@@ -91,8 +94,9 @@ describe('Test GATE Token', (): void => {
                 .sudo(api.tx.creditcoin.setGateFaucet(gateFaucet.address))
                 .signAndSend(sudoSigner, { nonce: -1 });
 
-            const swapGATEEvent = await requestCollectCoinsV2(gateContract, sudoSigner);
-            const swapGATEVerified = await swapGATEEvent.waitForVerification(800_000).catch();
+
+            const swapGATE = await requestCollectCoinsV2(gateContract, sudoSigner);
+            const swapGATEVerified = await swapGATE.waitForVerification(900_000);
 
             // Test #2: This is a successful transfer and should proceed normally
             expect(swapGATEVerified).toBeTruthy();
@@ -107,4 +111,39 @@ describe('Test GATE Token', (): void => {
         },
         900_000,
     );
+
+    // This test must run after the end to end test
+    // We are relying on the gate contract already being set, acceptable assumption since we run tests with --runInBand
+    testIf(
+        (global as any).CREDITCOIN_EXECUTE_SETUP_AUTHORITY,
+        'collectCoinsV2Example',
+        async () => {
+            const {
+                api,
+            } = ccApi;
+
+            const mintTx = await gateToken.mint(deployer.address, 2500);
+            await mintTx.wait(3);
+
+            const burnTx = await gateToken.burn(burnAmount);
+            await burnTx.wait(3);
+
+            // We are using the same deployer address as GCRE so the address may already be registered
+            await tryRegisterAddress(
+                ccApi,
+                deployer.address,
+                testingData.blockchain,
+                signAccountId(api, deployer, sudoSigner.address),
+                sudoSigner,
+                (global as any).CREDITCOIN_REUSE_EXISTING_ADDRESSES,
+            );
+
+            const gateContract = GATEContract(deployer.address, burnTx.hash);
+            const swapGATEVerified = await collectCoinsV2Example(ccApi, gateContract, sudoSigner);
+
+            expect(swapGATEVerified).toBeTruthy();
+            expect(swapGATEVerified.amount.toNumber()).toEqual(burnAmount / 2);
+        },
+        900_000,
+    );
 });

integration-tests/src/test/register-address-v2.test.ts

@@ -2,13 +2,14 @@ import { Blockchain, KeyringPair, Wallet, creditcoinApi } from 'creditcoin-js';
 import {
     createAddressId,
     ethSignSignature,
-    personalSignSignature,
     createCreditCoinOwnershipProof,
+    personalSignSignature,
 } from 'creditcoin-js/lib/extrinsics/register-address-v2';
 import { checkAddress, testData } from 'creditcoin-js/lib/testUtils';
 import { CreditcoinApi } from 'creditcoin-js/lib/types';
-import { signAccountId, personalSignAccountId } from 'creditcoin-js/lib/utils';
+import { personalSignAccountId, signAccountId } from 'creditcoin-js/lib/utils';
 import { extractFee } from '../utils';
+import { registerAddressV2Example } from 'creditcoin-js/lib/examples/register-address-v2';
 
 describe('RegisterAddressV2', () => {
     let ccApi: CreditcoinApi;
@@ -68,16 +69,17 @@ describe('RegisterAddressV2', () => {
     });
 
     it('registerAddressV2 PersonalSign works as expected', async (): Promise<void> => {
-        const {
-            api,
-            extrinsics: { registerAddressV2 },
-        } = ccApi;
-
         const lenderWallet = Wallet.createRandom();
-        const accountId = await personalSignAccountId(api, lenderWallet, lender.addressRaw);
-        const proof = personalSignSignature(accountId);
 
-        const lenderRegAddr = await registerAddressV2(lenderWallet.address, blockchain, proof, lender);
+        const { api, extrinsics: { registerAddressV2 } } = ccApi;
+
+        const accountId = lender.addressRaw;
+        const externalAddress = lenderWallet.address;
+
+        const signature = await personalSignAccountId(api, lenderWallet, accountId);
+        const proof = personalSignSignature(signature);
+
+        const lenderRegAddr = await registerAddressV2(externalAddress, blockchain, proof, lender);
 
         // manually constructed address is the same as returned by Creditcoin
         const addressId = createAddressId(blockchain, lenderWallet.address);
@@ -87,4 +89,17 @@ describe('RegisterAddressV2', () => {
         const result = await checkAddress(ccApi, addressId);
         expect(result).toBeDefined();
     });
+
+    it('registerAddressV2Example works as expected', async () => {
+        const ethSigner = Wallet.createRandom();
+        const lenderRegAddr = await registerAddressV2Example(ccApi, ethSigner, lender, blockchain);
+
+        // manually constructed address is the same as returned by Creditcoin
+        const addressId = createAddressId(blockchain, ethSigner.address);
+        expect(addressId).toBe(lenderRegAddr.itemId);
+
+        // manually constructed address should be reported as registered
+        const result = await checkAddress(ccApi, addressId);
+        expect(result).toBeDefined();
+    });
 });