WIP: Release/sdk/11

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

@@ -1,3 +1,79 @@
+## web SDK version 11
+
+This version of the web SDK focuses on forward compatibility, i.e. making it easier to keep applications and services
+running through updates to the integration point (Concordium nodes).
+
+### Motivation
+
+Up until this release, certain extensions to the Concordium Node API have resulted in the SDK failing to parse query
+responses, resulting in the entire query failing. This is the case even for the larger queries where the unknown/missing
+information is only a small part of the response preventing the application to access the entire response.
+Usually the fix was to update the SDK to a newer version which know how to parse the new information, but this imposes
+work for the ecosystem for every change in the API (usually part of protocol version updates).
+
+This major release introduces `Upward<A>` a type wrapper representing information which might be extended in future version
+of the API, providing a variant representing unknown information such that queries can provide partial information.
+It makes potentially extended information explicit in the types and allows each application to decide how to handle the
+case of new unknown data on a case by case basis.
+
+### Handling `Upward`
+
+Handling upward depends on what you want to achieve. If you're running a service that integrates with a Concordium node,
+you might want to fail safely by handling unknown variants gracefully. If you're writing a script it's probably easier
+to fail fast.
+
+#### Fail safe
+
+```ts
+import { isKnown, type TransactionHash } from '@concordium/web-sdk';
+...
+
+const transactionSummary: Upward<BlockItemSummary> = ...
+
+// branch on unknown
+if (isKnown(transactionSummary)) {
+    // transactionSummary is statically known at this point
+} else {
+    // handle the unknown case
+    console.warn('Encountered unknown transaction type.');
+}
+
+// Handle as optional
+// `Unknown` variant is simply represented as `null` underneath.
+const transactionHash: TransactionHash.Type | undefined = transactionSummary?.hash;
+```
+
+#### Fail fast
+
+```ts
+import { assertError, type TransactionHash } from '@concordium/web-sdk';
+...
+
+const transactionSummary: Upward<BlockItemSummary> = ...
+
+// fail with an error message in case of the unexpected happening.
+assertKnown(transctionSummary, 'Expected transaction type to be known');
+// transactionSummary is known at this point on.
+
+// or handle by simple null assertion, e.g. in the case where you just sent
+// the transaction to a node.
+handleKnownTransaction(transactionSummary!);
+```
+
+#### Optional + Unknown values
+
+In the SDK, `undefined` is used to represent when an optional value is _not_ present and `null` is used to represent
+unknown values. If you want to branch on these different cases, it can be handled by targeting thesee specific types:
+
+```ts
+const optionalUnknown: Upward<Value> | undefined = ...
+switch (optionalUnknown) {
+    case undefined: ... // handle optionality
+    case null: ... // handle unknown variant
+    default: ... // at this point, we know the type is `Value`
+}
+```
+
 ## web SDK version 7
 
 Several types have been replaced with a module containing the type itself together with functions for constructing and

examples/nodejs/client/getBlockItemStatus.ts

@@ -1,4 +1,4 @@
-import { BlockItemStatus, CcdAmount, TransactionHash } from '@concordium/web-sdk';
+import { BlockItemStatus, CcdAmount, TransactionHash, knownOrError } from '@concordium/web-sdk';
 import { ConcordiumGRPCNodeClient } from '@concordium/web-sdk/nodejs';
 import { credentials } from '@grpc/grpc-js';
 import meow from 'meow';
@@ -77,8 +77,7 @@ const client = new ConcordiumGRPCNodeClient(
     if (blockItemStatus.status === 'finalized') {
         console.log('blockItemStatus is "finalized" and therefore there is exactly one outcome \n');
 
-        const { summary } = blockItemStatus.outcome;
-
+        const summary = knownOrError(blockItemStatus.outcome.summary, 'unknown outcome encountered');
         if (summary.type === 'accountTransaction') {
             console.log('The block item is an account transaction');
 
@@ -95,7 +94,7 @@ const client = new ConcordiumGRPCNodeClient(
                     const { failedTransactionType, rejectReason } = summary;
                     console.log(
                         'Transaction of type "' + failedTransactionType + '" failed because:',
-                        rejectReason.tag
+                        rejectReason?.tag ?? 'unknown'
                     );
                     break;
                 default:

examples/nodejs/client/getBlockSpecialEvents.ts

@@ -1,4 +1,4 @@
-import { BlockHash, BlockSpecialEvent } from '@concordium/web-sdk';
+import { BlockHash, BlockSpecialEvent, Upward, isKnown } from '@concordium/web-sdk';
 import { ConcordiumGRPCNodeClient } from '@concordium/web-sdk/nodejs';
 import { credentials } from '@grpc/grpc-js';
 import meow from 'meow';
@@ -50,10 +50,14 @@ const client = new ConcordiumGRPCNodeClient(address, Number(port), credentials.c
 (async () => {
     // #region documentation-snippet
     const blockHash = cli.flags.block === undefined ? undefined : BlockHash.fromHexString(cli.flags.block);
-    const events: AsyncIterable<BlockSpecialEvent> = client.getBlockSpecialEvents(blockHash);
+    const events: AsyncIterable<Upward<BlockSpecialEvent>> = client.getBlockSpecialEvents(blockHash);
     // #endregion documentation-snippet
 
     for await (const event of events) {
-        console.dir(event, { depth: null, colors: true });
+        if (!isKnown(event)) {
+            console.warn('Unknown event encountered');
+        } else {
+            console.dir(event, { depth: null, colors: true });
+        }
     }
 })();

examples/nodejs/client/getBlockTransactionEvents.ts

@@ -1,4 +1,4 @@
-import { BlockHash, BlockItemSummary } from '@concordium/web-sdk';
+import { BlockHash, BlockItemSummary, Upward, isKnown } from '@concordium/web-sdk';
 import { ConcordiumGRPCNodeClient } from '@concordium/web-sdk/nodejs';
 import { credentials } from '@grpc/grpc-js';
 import meow from 'meow';
@@ -48,10 +48,14 @@ const client = new ConcordiumGRPCNodeClient(address, Number(port), credentials.c
 (async () => {
     // #region documentation-snippet
     const blockHash = cli.flags.block === undefined ? undefined : BlockHash.fromHexString(cli.flags.block);
-    const events: AsyncIterable<BlockItemSummary> = client.getBlockTransactionEvents(blockHash);
+    const events: AsyncIterable<Upward<BlockItemSummary>> = client.getBlockTransactionEvents(blockHash);
     // #endregion documentation-snippet
 
     for await (const event of events) {
-        console.dir(event, { depth: null, colors: true });
+        if (isKnown(event)) {
+            console.dir(event, { depth: null, colors: true });
+        } else {
+            console.warn('Encountered unknown event');
+        }
     }
 })();

examples/nodejs/client/getTokenomicsInfo.ts

@@ -1,4 +1,4 @@
-import { BlockHash } from '@concordium/web-sdk';
+import { BlockHash, isKnown } from '@concordium/web-sdk';
 import { ConcordiumGRPCNodeClient } from '@concordium/web-sdk/nodejs';
 import { credentials } from '@grpc/grpc-js';
 import meow from 'meow';
@@ -55,6 +55,11 @@ const client = new ConcordiumGRPCNodeClient(address, Number(port), credentials.c
 
     // Protocol version 4 expanded the amount of information in the response, so one should check the type to access that.
     // This information includes information about the payday and total amount of funds staked.
+    if (!isKnown(tokenomics)) {
+        console.warn('Unknown tokenomics version found');
+        return;
+    }
+
     if (tokenomics.version === 1) {
         console.log('Next payday time:', tokenomics.nextPaydayTime);
         console.log('Total staked amount by bakers and delegators', tokenomics.totalStakedCapital);

examples/nodejs/client/invokeContract.ts

@@ -9,6 +9,7 @@ import {
     Parameter,
     ReceiveName,
     ReturnValue,
+    Upward,
 } from '@concordium/web-sdk';
 import { ConcordiumGRPCNodeClient } from '@concordium/web-sdk/nodejs';
 import { credentials } from '@grpc/grpc-js';
@@ -124,7 +125,7 @@ const client = new ConcordiumGRPCNodeClient(address, Number(port), credentials.c
             console.log('The return value of the invoked method:', ReturnValue.toHexString(returnValue));
         }
 
-        const events: ContractTraceEvent[] = result.events;
+        const events: Upward<ContractTraceEvent>[] = result.events;
         console.log('A list of effects that the update would have:');
         console.dir(events, { depth: null, colors: true });
     }

examples/nodejs/composed-examples/findAccountCreationBlock.ts

@@ -1,4 +1,4 @@
-import { AccountAddress, isRpcError } from '@concordium/web-sdk';
+import { AccountAddress, isKnown, isRpcError } from '@concordium/web-sdk';
 import { ConcordiumGRPCNodeClient } from '@concordium/web-sdk/nodejs';
 import { credentials } from '@grpc/grpc-js';
 import meow from 'meow';
@@ -75,6 +75,9 @@ const client = new ConcordiumGRPCNodeClient(address, Number(port), credentials.c
 
     // If account is not a genesis account print account creation transaction hash
     for await (const summary of summaries) {
+        if (!isKnown(summary)) {
+            continue;
+        }
         if (summary.type === 'accountCreation' && AccountAddress.equals(summary.address, account)) {
             console.log('Hash of transaction that created the account:', summary.hash);
         }

examples/nodejs/composed-examples/initAndUpdateContract.ts

@@ -17,6 +17,8 @@ import {
     affectedContracts,
     buildAccountSigner,
     deserializeReceiveReturnValue,
+    isKnown,
+    knownOrError,
     parseWallet,
     serializeInitContractParameters,
     serializeUpdateContractParameters,
@@ -118,7 +120,14 @@ const client = new ConcordiumGRPCNodeClient(address, Number(port), credentials.c
     const initStatus = await client.waitForTransactionFinalization(initTrxHash);
     console.dir(initStatus, { depth: null, colors: true });
 
-    const contractAddress = affectedContracts(initStatus.summary)[0];
+    if (!isKnown(initStatus.summary)) {
+        throw new Error('Unexpected transaction outcome');
+    }
+
+    const contractAddress = knownOrError(
+        affectedContracts(initStatus.summary)[0],
+        'Expected contract init event to be known'
+    );
 
     // #endregion documentation-snippet-init-contract
 

examples/nodejs/composed-examples/listInitialAccounts.ts

@@ -1,4 +1,4 @@
-import { unwrap } from '@concordium/web-sdk';
+import { isKnown, unwrap } from '@concordium/web-sdk';
 import { ConcordiumGRPCNodeClient } from '@concordium/web-sdk/nodejs';
 import { credentials } from '@grpc/grpc-js';
 import meow from 'meow';
@@ -71,6 +71,9 @@ const client = new ConcordiumGRPCNodeClient(address, Number(port), credentials.c
         // Get transactions for block
         const trxStream = client.getBlockTransactionEvents(block.hash);
         for await (const trx of trxStream) {
+            if (!isKnown(trx)) {
+                continue;
+            }
             if (trx.type === 'accountCreation' && trx.credentialType === 'initial') {
                 initAccounts.push(trx.address);
             }

examples/nodejs/composed-examples/listNumberAccountTransactions.ts

@@ -1,4 +1,4 @@
-import { AccountAddress, isTransferLikeSummary, unwrap } from '@concordium/web-sdk';
+import { AccountAddress, isKnown, isTransferLikeSummary, unwrap } from '@concordium/web-sdk';
 import { ConcordiumGRPCNodeClient } from '@concordium/web-sdk/nodejs';
 import { credentials } from '@grpc/grpc-js';
 import meow from 'meow';
@@ -75,6 +75,9 @@ const client = new ConcordiumGRPCNodeClient(address, Number(port), credentials.c
 
         // For each transaction in the block:
         trxLoop: for await (const trx of trxStream) {
+            if (!isKnown(trx)) {
+                continue;
+            }
             if (isTransferLikeSummary(trx)) {
                 const trxAcc = trx.sender;
 

examples/nodejs/plt/modify-list.ts

@@ -5,18 +5,20 @@ import {
     TransactionEventTag,
     TransactionKindString,
     TransactionSummaryType,
+    isKnown,
     serializeAccountTransactionPayload,
 } from '@concordium/web-sdk';
 import { ConcordiumGRPCNodeClient } from '@concordium/web-sdk/nodejs';
 import {
     Cbor,
+    CborAccountAddress,
     Token,
-    TokenHolder,
     TokenId,
     TokenListUpdate,
     TokenOperation,
     TokenOperationType,
     createTokenUpdatePayload,
+    parseTokenModuleEvent,
 } from '@concordium/web-sdk/plt';
 import { credentials } from '@grpc/grpc-js';
 import meow from 'meow';
@@ -105,7 +107,7 @@ const client = new ConcordiumGRPCNodeClient(
 
     // parse the arguments
     const tokenId = TokenId.fromString(id);
-    const targetAddress = TokenHolder.fromAccountAddress(AccountAddress.fromBase58(address));
+    const targetAddress = AccountAddress.fromBase58(address);
 
     if (walletFile !== undefined) {
         // Read wallet-file
@@ -137,22 +139,26 @@ const client = new ConcordiumGRPCNodeClient(
             const result = await client.waitForTransactionFinalization(transaction);
             console.log('Transaction finalized:', result);
 
+            if (!isKnown(result.summary)) {
+                throw new Error('Unexpected transaction outcome');
+            }
+
             if (result.summary.type !== TransactionSummaryType.AccountTransaction) {
                 throw new Error('Unexpected transaction type: ' + result.summary.type);
             }
 
             switch (result.summary.transactionType) {
                 case TransactionKindString.TokenUpdate:
-                    result.summary.events.forEach((e) => {
+                    result.summary.events.filter(isKnown).forEach((e) => {
                         if (e.tag !== TransactionEventTag.TokenModuleEvent) {
                             throw new Error('Unexpected event type: ' + e.tag);
                         }
-                        console.log('Token module event:', e, Cbor.decode(e.details, 'TokenListUpdateEventDetails'));
+                        console.log('Token module event:', parseTokenModuleEvent(e));
                     });
                     break;
                 case TransactionKindString.Failed:
-                    if (result.summary.rejectReason.tag !== RejectReasonTag.TokenUpdateTransactionFailed) {
-                        throw new Error('Unexpected reject reason tag: ' + result.summary.rejectReason.tag);
+                    if (result.summary.rejectReason?.tag !== RejectReasonTag.TokenUpdateTransactionFailed) {
+                        throw new Error('Unexpected reject reason tag: ' + result.summary.rejectReason?.tag);
                     }
                     const details = Cbor.decode(result.summary.rejectReason.contents.details);
                     console.error(result.summary.rejectReason.contents, details);
@@ -167,7 +173,7 @@ const client = new ConcordiumGRPCNodeClient(
         const operationType = `${action}-${list}-list` as TokenOperationType;
         // Or from a wallet perspective:
         // Create list payload. The payload is the same for both add and remove operations on all lists.
-        const listPayload: TokenListUpdate = { target: targetAddress };
+        const listPayload: TokenListUpdate = { target: CborAccountAddress.fromAccountAddress(targetAddress) };
         const listOperation = {
             [operationType]: listPayload,
         } as TokenOperation; // Normally the cast is not necessary unless done in the same dynamic way as here.

examples/nodejs/plt/pause.ts

@@ -4,10 +4,18 @@ import {
     TransactionEventTag,
     TransactionKindString,
     TransactionSummaryType,
+    isKnown,
     serializeAccountTransactionPayload,
 } from '@concordium/web-sdk';
 import { ConcordiumGRPCNodeClient } from '@concordium/web-sdk/nodejs';
-import { Cbor, Token, TokenId, TokenOperation, createTokenUpdatePayload } from '@concordium/web-sdk/plt';
+import {
+    Cbor,
+    Token,
+    TokenId,
+    TokenOperation,
+    createTokenUpdatePayload,
+    parseTokenModuleEvent,
+} from '@concordium/web-sdk/plt';
 import { credentials } from '@grpc/grpc-js';
 import meow from 'meow';
 
@@ -102,22 +110,26 @@ const client = new ConcordiumGRPCNodeClient(
             const result = await client.waitForTransactionFinalization(transaction);
             console.log('Transaction finalized:', result);
 
+            if (!isKnown(result.summary)) {
+                throw new Error('Unexpected transaction outcome');
+            }
+
             if (result.summary.type !== TransactionSummaryType.AccountTransaction) {
                 throw new Error('Unexpected transaction type: ' + result.summary.type);
             }
 
             switch (result.summary.transactionType) {
                 case TransactionKindString.TokenUpdate:
-                    result.summary.events.forEach((e) => {
+                    result.summary.events.filter(isKnown).forEach((e) => {
                         if (e.tag !== TransactionEventTag.TokenModuleEvent) {
                             throw new Error('Unexpected event type: ' + e.tag);
                         }
-                        console.log('Token module event:', e, Cbor.decode(e.details, 'TokenPauseEventDetails'));
+                        console.log('Token module event:', parseTokenModuleEvent(e));
                     });
                     break;
                 case TransactionKindString.Failed:
-                    if (result.summary.rejectReason.tag !== RejectReasonTag.TokenUpdateTransactionFailed) {
-                        throw new Error('Unexpected reject reason tag: ' + result.summary.rejectReason.tag);
+                    if (result.summary.rejectReason?.tag !== RejectReasonTag.TokenUpdateTransactionFailed) {
+                        throw new Error('Unexpected reject reason tag: ' + result.summary.rejectReason?.tag);
                     }
                     const details = Cbor.decode(result.summary.rejectReason.contents.details);
                     console.error(result.summary.rejectReason.contents, details);