Use more wrappers in API

.github/workflows/pipeline.yml

@@ -3,15 +3,14 @@ name: Build, lint and typecheck examples
 on:
     # Triggers the workflow on push or pull request events but only for the main branch
     push:
-        branches: [ main, release** ]
+        branches: [main, release**]
     pull_request:
-        branches: [ main, release** ]
+        branches: [main, release**]
         # Don't run on draft PR's, see: https://github.com/orgs/community/discussions/25722#discussioncomment-3248917
-        types: [ opened, synchronize, reopened, ready_for_review ]
+        types: [opened, synchronize, reopened, ready_for_review]
     # Allows us to run the workflow manually from the Actions tab
     workflow_dispatch:
 
-
 env:
     DUMMY: 1 # For cache busting.
     NODE_VERSION: 18.16.0

docs/pages/misc-pages/upgrade-guide.md

@@ -1,5 +1,53 @@
 ## Common SDK version 10 (Web 7) (Node 10)
 
+### Common
+
+Several types have been replaced with a module containing the type itself together with functions for constructing and
+converting the type:
+
+- `AccountAddress` is now a module with functions related to account addresses:
+  - To refer to `AccountAddress` as a type use `AccountAddress.Type`.
+  - Constructing `new AccountAddress("<address>")` is now `AccountAddress.fromBase58("<address>")`.
+  - `isAlias` and `getAlias` are now accessable from `AccountAddress.isAlias` and `AccountAddress.getAlias`.
+- `ContractAddresss` is now a module with functions related to contract addresses:
+  - To refer to `ContractAddress` as a type use `ContractAddress.Type`.
+  - To construct the type use `ContractAddress.create(index, subindex)`.
+- `CredentialRegistrationId` is now a module with functions related to credential registration IDs:
+  - To refer to `CredentialRegistrationId` as a type use `CredentialRegistrationId.Type`.
+  - Constructing `new CredentialRegistrationId("<hex-string>")` is now
+    `CredentialRegistrationId.fromHexString("<hex-string>")`.
+- `Duration` is now a module with functions related to durations of time.
+  - To refer to `Duration` as a type use `Duration.Type`.
+- `Timestamp` is now a module with functions related to timestamps.
+  - To refer to `Timestamp` as a type use `Timestamp.Type`.
+
+The API now uses dedicated types instead of language primitives:
+
+- Uses `AccountAddress` instead of a string with base58 encoding.
+  Can be constructed using `AccountAddress.fromBase58('<base58>')`.
+- Uses `BlockHash` instead of a string with hex encoding.
+  Can be constructed using `BlockHash.fromHexString('<hex>')`.
+- Uses `TranactionHash` instead of a string with hex encoding.
+  Can be constructed using `TransactionHash.fromHexString('<hex>')`.
+- Uses `Energy` instead of a bigint.
+  Can be constructed using `Energy.create(<integer>)`.
+- Uses `ReceiveName` instead of a string.
+  Can be constructed using `ReceiveName.fromString('<contract>.<function>')`.
+- Uses `InitName` instead of a string.
+  Can be constructed using `Init.fromString('init_<contract>')`.
+- Uses `ContractName` instead of a string.
+  Can be constructed using `ContractName.fromString('<contract>')`.
+- Uses `EntrypointName` instead of a string.
+  Can be constructed using `EntrypointName.fromString('<function>')`.
+- Uses `Parameter` instead of a string with hex encoding.
+  Can be constructed using `Parameter.fromHexString('<hex>')`.
+- Uses `SequenceNumber` (formerly called nonce) instead of a bigint.
+  Can be constructed using  `SequenceNumber.create(<integer>)`.
+- Uses `Timestamp` instead of a bigint.
+  Can be constructed using `Timestamp.fromMillis(<integer>)`.
+- Uses `Duration` instead of a bigint.
+  Can be constructed using `Duration.fromMillis(<integer>)`.
+
 ### Web
 
 The `@concordium/web-sdk` now requires bundlers to respect `exports` field of

examples/ccd-js-gen/wCCD/client-tokenMetadata.ts

@@ -6,7 +6,7 @@ import { parseEndpoint } from '../../shared/util.js';
 // The generated module could be imported directly like below,
 // but for this example it is imported dynamicly to improve
 // the error message when not generated.
-// import * as wCCDModule from './lib/wCCD';
+// import * as wCCDContractClient from './lib/cis2_wCCD';
 
 const cli = meow(
     `
@@ -51,10 +51,10 @@ const grpcClient = SDK.createConcordiumClient(
     scheme === 'https' ? credentials.createSsl() : credentials.createInsecure()
 );
 
-const contractAddress: SDK.ContractAddress = {
-    index: BigInt(cli.flags.index),
-    subindex: BigInt(cli.flags.subindex),
-};
+const contractAddress = SDK.ContractAddress.create(
+    cli.flags.index,
+    cli.flags.subindex
+);
 
 (async () => {
     // Importing the generated smart contract module client.
@@ -69,15 +69,16 @@ const contractAddress: SDK.ContractAddress = {
         throw e;
     });
 
-    const parameter = SDK.Parameter.fromHexString('010000'); // First 2 bytes for number of tokens to query, 1 byte for the token ID.
+    const wCCDTokenId = '';
+    const parameter = [wCCDTokenId];
     const contract = await wCCDContractClient.create(
         grpcClient,
         contractAddress
     );
 
     const result = await wCCDContractClient.dryRunTokenMetadata(
         contract,
-        new SDK.AccountAddress(
+        SDK.AccountAddress.fromBase58(
             '357EYHqrmMiJBmUZTVG5FuaMq4soAhgtgz6XNEAJaXHW3NHaUf'
         ),
         parameter

examples/cis2/balanceOf.ts

@@ -1,4 +1,8 @@
-import { createConcordiumClient, CIS2Contract } from '@concordium/node-sdk';
+import {
+    createConcordiumClient,
+    CIS2Contract,
+    ContractAddress,
+} from '@concordium/node-sdk';
 import { credentials } from '@grpc/grpc-js';
 import meow from 'meow';
 import { parseAddress, parseEndpoint } from '../shared/util.js';
@@ -57,10 +61,10 @@ const client = createConcordiumClient(
 );
 
 (async () => {
-    const contract = await CIS2Contract.create(client, {
-        index: BigInt(cli.flags.index),
-        subindex: BigInt(cli.flags.subindex),
-    });
+    const contract = await CIS2Contract.create(
+        client,
+        ContractAddress.create(cli.flags.index, cli.flags.subindex)
+    );
 
     const accountBalance = await contract.balanceOf({
         address: parseAddress(cli.flags.address),

examples/cis2/dryRun.transfer.ts

@@ -2,6 +2,9 @@ import {
     createConcordiumClient,
     CIS2,
     CIS2Contract,
+    ContractAddress,
+    AccountAddress,
+    EntrypointName,
 } from '@concordium/node-sdk';
 import { credentials } from '@grpc/grpc-js';
 import meow from 'meow';
@@ -74,21 +77,22 @@ const client = createConcordiumClient(
 );
 
 (async () => {
-    const contract = await CIS2Contract.create(client, {
-        index: BigInt(cli.flags.index),
-        subindex: BigInt(cli.flags.subindex),
-    });
+    const contract = await CIS2Contract.create(
+        client,
+        ContractAddress.create(cli.flags.index, cli.flags.subindex)
+    );
 
     const tokenId = cli.flags.tokenId;
-    const from = cli.flags.from;
+    const from = AccountAddress.fromBase58(cli.flags.from);
     const toAddress = parseAddress(cli.flags.to);
-    const to: CIS2.Receiver =
-        typeof toAddress === 'string'
-            ? toAddress
-            : {
-                  address: toAddress,
-                  hookName: cli.flags.receiveHookName ?? '',
-              };
+    const to: CIS2.Receiver = AccountAddress.isAccountAddress(toAddress)
+        ? toAddress
+        : {
+              address: toAddress,
+              hookName: EntrypointName.fromString(
+                  cli.flags.receiveHookName ?? ''
+              ),
+          };
 
     const result = await contract.dryRun.transfer(from, {
         from,

examples/cis2/dryRun.updateOperator.ts

@@ -1,4 +1,8 @@
-import { createConcordiumClient, CIS2Contract } from '@concordium/node-sdk';
+import {
+    createConcordiumClient,
+    CIS2Contract,
+    ContractAddress,
+} from '@concordium/node-sdk';
 import { credentials } from '@grpc/grpc-js';
 import meow from 'meow';
 import { parseAddress, parseEndpoint } from '../shared/util.js';
@@ -57,10 +61,10 @@ const client = createConcordiumClient(
 );
 
 (async () => {
-    const contract = await CIS2Contract.create(client, {
-        index: BigInt(cli.flags.index),
-        subindex: BigInt(cli.flags.subindex),
-    });
+    const contract = await CIS2Contract.create(
+        client,
+        ContractAddress.create(cli.flags.index, cli.flags.subindex)
+    );
 
     const owner = parseAddress(cli.flags.owner);
     const address = parseAddress(cli.flags.address);

examples/cis2/operatorOf.ts

@@ -1,4 +1,8 @@
-import { createConcordiumClient, CIS2Contract } from '@concordium/node-sdk';
+import {
+    createConcordiumClient,
+    CIS2Contract,
+    ContractAddress,
+} from '@concordium/node-sdk';
 import { credentials } from '@grpc/grpc-js';
 import meow from 'meow';
 import { parseAddress, parseEndpoint } from '../shared/util.js';
@@ -57,10 +61,10 @@ const client = createConcordiumClient(
 );
 
 (async () => {
-    const contract = await CIS2Contract.create(client, {
-        index: BigInt(cli.flags.index),
-        subindex: BigInt(cli.flags.subindex),
-    });
+    const contract = await CIS2Contract.create(
+        client,
+        ContractAddress.create(cli.flags.index, cli.flags.subindex)
+    );
 
     const owner = parseAddress(cli.flags.owner);
     const address = parseAddress(cli.flags.address);

examples/cis2/tokenMetadata.ts

@@ -1,4 +1,8 @@
-import { createConcordiumClient, CIS2Contract } from '@concordium/node-sdk';
+import {
+    createConcordiumClient,
+    CIS2Contract,
+    ContractAddress,
+} from '@concordium/node-sdk';
 import { credentials } from '@grpc/grpc-js';
 import meow from 'meow';
 
@@ -54,10 +58,10 @@ if (cli.flags.h) {
 }
 
 (async () => {
-    const contract = await CIS2Contract.create(client, {
-        index: BigInt(cli.flags.index),
-        subindex: BigInt(cli.flags.subindex),
-    });
+    const contract = await CIS2Contract.create(
+        client,
+        ContractAddress.create(cli.flags.index, cli.flags.subindex)
+    );
 
     const url = await contract.tokenMetadata(cli.flags.tokenId);
     console.log('url object:', url);

examples/cis2/transfer.ts

@@ -3,6 +3,10 @@ import {
     CIS2,
     CIS2Contract,
     buildBasicAccountSigner,
+    ContractAddress,
+    AccountAddress,
+    EntrypointName,
+    Energy,
 } from '@concordium/node-sdk';
 import { credentials } from '@grpc/grpc-js';
 import meow from 'meow';
@@ -81,27 +85,28 @@ const client = createConcordiumClient(
 );
 
 (async () => {
-    const contract = await CIS2Contract.create(client, {
-        index: BigInt(cli.flags.index),
-        subindex: BigInt(cli.flags.subindex),
-    });
+    const contract = await CIS2Contract.create(
+        client,
+        ContractAddress.create(cli.flags.index, cli.flags.subindex)
+    );
 
     const signer = buildBasicAccountSigner(cli.flags.privateKey);
     const tokenId = cli.flags.tokenId;
-    const from = cli.flags.from;
+    const from = AccountAddress.fromBase58(cli.flags.from);
     const toAddress = parseAddress(cli.flags.to);
-    const to: CIS2.Receiver =
-        typeof toAddress === 'string'
-            ? toAddress
-            : {
-                  address: toAddress,
-                  hookName: cli.flags.receiveHookName ?? '',
-              };
+    const to: CIS2.Receiver = AccountAddress.isAccountAddress(toAddress)
+        ? toAddress
+        : {
+              address: toAddress,
+              hookName: EntrypointName.fromString(
+                  cli.flags.receiveHookName ?? ''
+              ),
+          };
 
     const txHash = await contract.transfer(
         {
             senderAddress: from,
-            energy: 10000n,
+            energy: Energy.create(10000),
         },
         {
             from,

examples/cis2/updateOperator.ts

@@ -2,6 +2,9 @@ import {
     createConcordiumClient,
     CIS2Contract,
     buildBasicAccountSigner,
+    ContractAddress,
+    AccountAddress,
+    Energy,
 } from '@concordium/node-sdk';
 import { credentials } from '@grpc/grpc-js';
 import meow from 'meow';
@@ -71,19 +74,19 @@ const client = createConcordiumClient(
 );
 
 (async () => {
-    const contract = await CIS2Contract.create(client, {
-        index: BigInt(cli.flags.index),
-        subindex: BigInt(cli.flags.subindex),
-    });
+    const contract = await CIS2Contract.create(
+        client,
+        ContractAddress.create(cli.flags.index, cli.flags.subindex)
+    );
 
     const signer = buildBasicAccountSigner(cli.flags.privateKey);
-    const owner = cli.flags.owner;
+    const owner = AccountAddress.fromBase58(cli.flags.owner);
     const address = parseAddress(cli.flags.address);
 
     const txHash = await contract.updateOperator(
         {
             senderAddress: owner,
-            energy: 10000n,
+            energy: Energy.create(10000),
         },
         {
             type: cli.flags.updateType as 'add' | 'remove',

examples/cis4/credentialEntry.ts

@@ -1,7 +1,11 @@
 import meow from 'meow';
 import { credentials } from '@grpc/grpc-js';
 
-import { CIS4Contract, createConcordiumClient } from '@concordium/node-sdk';
+import {
+    CIS4Contract,
+    ContractAddress,
+    createConcordiumClient,
+} from '@concordium/node-sdk';
 import { parseEndpoint } from '../shared/util.js';
 
 const cli = meow(
@@ -52,10 +56,10 @@ const client = createConcordiumClient(
 );
 
 (async () => {
-    const contract = await CIS4Contract.create(client, {
-        index: BigInt(cli.flags.index),
-        subindex: BigInt(cli.flags.subindex),
-    });
+    const contract = await CIS4Contract.create(
+        client,
+        ContractAddress.create(cli.flags.index, cli.flags.subindex)
+    );
 
     const credentialEntry = await contract.credentialEntry(cli.flags.credId);
     console.log('Credential entry:', credentialEntry);