@concordium/browser-wallet-api-helpers 2.4.0 → 2.6.0

package/README.md

@@ -51,14 +51,14 @@ declare global {
 
 ### connect
 
-To request a connection to the wallet from the user, the `connect` method has to be invoked. The method returns a `Promise` resolving with information related to the most recently selected account, which has whitelisted the dApp, or rejecting if the request is rejected in the wallet. If the wallet is locked, then this call prompts the user to first unlock the wallet before accepting or rejecting the connection request.
+To request a connection to the wallet from the user, the `connect` method has to be invoked. The method returns a `Promise` resolving with information related to the most recently selected account, which has allowlisted the dApp, or rejecting if the request is rejected in the wallet. If the wallet is locked, then this call prompts the user to first unlock the wallet before accepting or rejecting the connection request.
 
 ```typescript
 const provider = await detectConcordiumProvider();
 const accountAddress = await provider.connect();
 ```
 
-N.B. In the current version, if the dApp is already whitelisted, but not by the currently selected account, the returned account will not actually be the most recently selected account, but instead the oldest account that has whitelisted the dApp.
+N.B. In the current version, if the dApp is already allowlisted, but not by the currently selected account, the returned account will not actually be the most recently selected account, but instead the oldest account that has allowlisted the dApp.
 
 ### getMostRecentlySelectedAccount
 
@@ -74,13 +74,33 @@ if (accountAddress) {
 }
 ```
 
-N.B. In the current version, if the currently selected account has not whitelisted the dApp, the returned account will not actually be the most recently selected account, but instead the oldest account that has whitelisted the dApp.
+### requestAccounts
+
+To request a connection to the wallet from the user, the `requestAccounts` method has to be invoked. The method returns a `Promise` resolving with the list of accounts
+that the user has chosen to connect with. The list may be empty. Alternatively the promise will be rejecting if the request is rejected in the wallet. If the wallet is locked,
+then this call prompts the user to first unlock the wallet before accepting or rejecting the request.
+
+```typescript
+const provider = await detectConcordiumProvider();
+const accountAddresses = await provider.requestAccounts();
+```
+
+### getSelectedChain
+
+This can be invoked to get the genesis hash of the chain selected in the wallet. The method returns a `Promise`, resolving with the genesis hash (as a hex string) of the selected chain, or undefined if the wallet is locked or has not been set up by the user.
+
+```typescript
+const provider = await detectConcordiumProvider();
+const genesisHash = await provider.getSelectedChain();
+```
+
+N.B. In the current version, if the currently selected account has not allowlisted the dApp, the returned account will not actually be the most recently selected account, but instead the oldest account that has allowlisted the dApp.
 
 ### sendTransaction
 
 To send a transaction, three arguments need to be provided: The account address for the account in the wallet that should sign the transaction, a transaction type and a corresponding payload. Invoking `sendTransaction` returns a `Promise`, which resolves with the transaction hash for the submitted transaction.
 
-If the wallet is locked, or you have not connected with the wallet (or previously been whitelisted) or if the user rejects signing the transaction, the `Promise` will reject.
+If the wallet is locked, or you have not connected with the wallet (or previously been allowlisted) or if the user rejects signing the transaction, the `Promise` will reject.
 
 The following exemplifies how to create a simple transfer of funds from one account to another. Please note that [@concordium/web-sdk](https://github.com/Concordium/concordium-node-sdk-js/tree/main/packages/web) is used to provide the correct formats and types for the transaction payload.
 
@@ -140,12 +160,12 @@ const parameterSchema = {
 
 It is possible to sign arbitrary messages using the keys for an account stored in the wallet, by invoking the `signMessage` method. The first parameter is the account to be used for signing the message. This method returns a `Promise` resolving with a signature of the message.
 
-If the wallet is locked, or you have not connected with the wallet (or previously been whitelisted) or if the user rejects signing the meesage, the `Promise` will reject.
+If the wallet is locked, or you have not connected with the wallet (or previously been allowlisted) or if the user rejects signing the meesage, the `Promise` will reject.
 
-The message should either utf8 string or an object with the following fields:
+The message should be either a utf8 string or an object with the following fields:
 
 -   data: A hex string representing the bytes that should be signed.
--   schema: A base64 string that represents a schema for the data field, and which can be used to deserialize the data into a JSON format.
+-   schema: A base64 string that represents a schema for the data field, and which can be used to deserialize the data into a JSON format. (For reference, the type of schema used here is the same that is used for smart contract types)
 
 The following exemplifies requesting a signature of a message, where the message is a utf8 string:
 
@@ -186,7 +206,7 @@ In this example the user will be shown:
 
 It is possible to suggest CIS-2 tokens to be added to an account's display. This method returns a `Promise` resolving with a list containing the ids of the tokens that were added.
 
-If the wallet is locked, or you have not connected with the wallet (or previously been whitelisted) or if the user rejects signing the meesage, the `Promise` will reject.
+If the wallet is locked, or you have not connected with the wallet (or previously been allowlisted) or if the user rejects signing the meesage, the `Promise` will reject.
 
 The following exemplifies requesting tokens with id AA and BB from the contract on index 1399, and subindex 0 to the account `2za2yAXbFiaB151oYqTteZfqiBzibHXizwjNbpdU8hodq9SfEk`.
 
@@ -195,20 +215,36 @@ const provider = await detectConcordiumProvider();
 await provider.addCIS2Tokens('2za2yAXbFiaB151oYqTteZfqiBzibHXizwjNbpdU8hodq9SfEk', ['AA', 'BB'], '1399', '0');
 ```
 
-### Prove ID statement
+### Add Web3Id Credentials
+
+To add a Web3IdCredential, use the `addWeb3IdCredential` endpoint.
+The credential itself and the url for the metadata must be provided. In addition, the function takes a callback function that takes a DID for the credentialHolderId as input, and which should return the randomness used to create the commitments on the values/properties in the credential, and a proof (which can be a signature on the commitments and credentialHolderId) of the credential's validity. If the callback does not return a valid proof, the credential is not added to the wallet.
+
+Note that the id fields of the credential are omitted, and added by the wallet itself, as they require the credentialHolderId.
+
+// TODO link to help for how to create proof and randomness
+
+```typescript
+provider.addWeb3IdCredential(credential, metadataUrl, async (id) => {
+    const randomness = createRandomness(attributes); // Choose some randomness for the attribute commitments.
+    const proof = createCredentialProof(credential, id, randomness); // Create a proof to prove that the commitments are created by the issuer.
+    return { proof, randomness };
+});
+```
+
+### Request Verifiable Presentation for web3Id statements
 
-It is possible to request a proof for a given ID statement on a specific account. The function takes 3 arguments. The statement to be proved, a challenge to ensure that the proof was not generated for a different context, and the account that should prove that statement.
-This method returns a `Promise` resolving with an object containing the proof and the credential id (field name: credential) of the credential used to prove the statement.
+It is possible to request a verifiable presentation for a given set of web3Id statements. The function takes 2 arguments. A challenge to ensure that the proof was not generated for a different context, and the statements to be proven. This method returns a Promise resolving with the verifiable presentation for the statements.
 
-If the wallet is locked, or you have not connected with the wallet (or previously been whitelisted) or if the user rejects proving the statement, the `Promise` will reject.
+If the wallet is locked, or you have not connected with the wallet (or previously been allowlisted) or if the user rejects proving the statement, the Promise will reject.
 
-The following exemplifies requesting a proof for a statement name myIdStatement (To see how to create a statement check out [our documentation](https://developer.concordium.software/en/mainnet/net/guides/create-proofs.html)) with a challenge of "12346789ABCD" id, for the account `2za2yAXbFiaB151oYqTteZfqiBzibHXizwjNbpdU8hodq9SfEk`.
+The following exemplifies requesting a verifiable presentation for a statement named myIdStatement (To see how to create a statement check out our documentation) with a challenge of "12346789ABCD".
 
 ```typescript
 const statement = myIdStatement;
 const challenge = '12346789ABCD';
 const provider = await detectConcordiumProvider();
-await provider.requestIdProof('2za2yAXbFiaB151oYqTteZfqiBzibHXizwjNbpdU8hodq9SfEk', ['AA', 'BB'], '1399', '0');
+const verifiablePresentation = await provider.requestVerifiablePresentation(challenge, statement);
 ```
 
 ## Events
@@ -250,7 +286,7 @@ provider.connect().then((accountAddress) => (selectedAccountAddress = accountAdd
 The wallet API exposes access to a JSON-RPC client. This allows a dApp to communicate with the same node as the wallet is connected to, and enables dApps to access the JSON-RPC interface without being connected to a separate server itself. The client is accessed as shown in the example below.
 The dApp does not need to recreate the client again when the wallet changes node or network, the client will always use the wallet's current connected JSON-RPC server.
 
-If you have not connected with the wallet (or previously been whitelisted), the commands will not be executed and the method will throw an error.
+If you have not connected with the wallet (or previously been allowlisted), the commands will not be executed and the method will throw an error.
 
 ```typescript
 const provider = await detectConcordiumProvider();

package/lib/util.d.ts

@@ -0,0 +1,2 @@
+export declare type LaxStringEnumValue<E extends string> = `${E}`;
+export declare type LaxNumberEnumValue<E extends number> = `${E}` extends `${infer T extends number}` ? T : never;

package/lib/util.js

@@ -0,0 +1 @@
+export {};

package/lib/wallet-api-types.d.ts

@@ -1,4 +1,33 @@
-import type { AccountTransactionPayload, AccountTransactionSignature, AccountTransactionType, InitContractPayload, JsonRpcClient, SchemaVersion, UpdateContractPayload, IdStatement, IdProofOutput } from '@concordium/web-sdk';
+import type { AccountTransactionPayload, AccountTransactionSignature, AccountTransactionType, InitContractPayload, JsonRpcClient, SchemaVersion, UpdateContractPayload, IdStatement, IdProofOutput, ConcordiumGRPCClient, CredentialStatements, VerifiablePresentation, CredentialSubject, HexString } from '@concordium/web-sdk';
+import { LaxNumberEnumValue, LaxStringEnumValue } from './util';
+export interface MetadataUrl {
+    url: string;
+    hash?: string;
+}
+interface CredentialSchema {
+    id: string;
+    type: string;
+}
+/**
+ * The expected form of a Web3IdCredential, with the id fields omitted.
+ */
+export interface APIVerifiableCredential {
+    $schema: string;
+    type: string[];
+    issuer: string;
+    issuanceDate: string;
+    credentialSubject: Omit<CredentialSubject, 'id'>;
+    credentialSchema: CredentialSchema;
+}
+/**
+ * Expected format for the proof that the Web3IdCredential's attribute commitments are valid
+ */
+export interface CredentialProof {
+    proofPurpose: 'assertionMethod';
+    proofValue: HexString;
+    type: 'Ed25519Signature2020';
+    verificationMethod: string;
+}
 export declare type SendTransactionPayload = Exclude<AccountTransactionPayload, UpdateContractPayload | InitContractPayload> | Omit<UpdateContractPayload, 'message'> | Omit<InitContractPayload, 'param'>;
 export declare type SmartContractParameters = {
     [key: string]: SmartContractParameters;
@@ -22,7 +51,7 @@ export declare enum SchemaType {
     Parameter = "parameter"
 }
 export declare type SchemaWithContext = {
-    type: SchemaType;
+    type: LaxStringEnumValue<SchemaType>;
     value: string;
 };
 declare type EventListener<Args extends any[]> = (...args: Args) => void;
@@ -44,7 +73,7 @@ interface MainWalletApi {
      * @param schema schema used for the initContract and updateContract transactions to serialize the parameters. Should be base64 encoded.
      * @param schemaVersion version of the schema provided. Must be supplied for schemas that use version 0 or 1, as they don't have the version embedded.
      */
-    sendTransaction(accountAddress: string, type: AccountTransactionType.Update | AccountTransactionType.InitContract, payload: SendTransactionPayload, parameters: SmartContractParameters, schema: string | SchemaWithContext, schemaVersion?: SchemaVersion): Promise<string>;
+    sendTransaction(accountAddress: string, type: LaxNumberEnumValue<AccountTransactionType.Update | AccountTransactionType.InitContract>, payload: SendTransactionPayload, parameters: SmartContractParameters, schema: string | SchemaWithContext, schemaVersion?: SchemaVersion): Promise<string>;
     /**
      * Sends a transaction to the Concordium Wallet and awaits the users action. Note that a header is not sent, and will be constructed by the wallet itself.
      * Note that if the user rejects signing the transaction, this will throw an error.
@@ -52,7 +81,7 @@ interface MainWalletApi {
      * @param type the type of transaction that is to be signed and sent.
      * @param payload the payload of the transaction to be signed and sent. Note that for smart contract transactions, the payload should not contain the parameters, those should instead be provided in the subsequent argument instead.
      */
-    sendTransaction(accountAddress: string, type: AccountTransactionType, payload: SendTransactionPayload): Promise<string>;
+    sendTransaction(accountAddress: string, type: LaxNumberEnumValue<AccountTransactionType>, payload: SendTransactionPayload): Promise<string>;
     /**
      * Sends a message to the Concordium Wallet and awaits the users action. If the user signs the message, this will resolve to the signature.
      * Note that if the user rejects signing the message, this will throw an error.
@@ -63,14 +92,35 @@ interface MainWalletApi {
     /**
      * Requests a connection to the Concordium wallet, prompting the user to either accept or reject the request.
      * If a connection has already been accepted for the url once the returned promise will resolve without prompting the user.
+     * @deprecated use {@link requestAccounts} instead
      */
     connect(): Promise<string | undefined>;
+    /**
+     * Requests a connection to the Concordium wallet, prompting the user to either accept or reject the request. The
+     * user will be prompted to select which accounts should be connected. The list of connected accounts is returned
+     * to the caller. If a connection has already been accepted previously, then the returned promise will resolve
+     * with the list of connected accounts. Note that the list of accounts may be empty.
+     */
+    requestAccounts(): Promise<string[] | undefined>;
     /**
      * Returns some connected account, prioritizing the most recently selected. Resolves with account address or undefined if there are no connected account.
      */
     getMostRecentlySelectedAccount(): Promise<string | undefined>;
     removeAllListeners(event?: EventType | string | undefined): this;
+    /**
+     * @deprecated use { @link getGrpcClient} instead
+     */
     getJsonRpcClient(): JsonRpcClient;
+    /**
+     * Returns a gRPC client that is connected to the node that the wallet is.
+     * Note that any calls will throw an error, if the site is not connected with the wallet.
+     */
+    getGrpcClient(): ConcordiumGRPCClient;
+    /**
+     * Returns the genesis hash of the currently selected chain in the wallet.
+     * Returns undefined if the wallet is either locked or not set up by the user.
+     */
+    getSelectedChain(): Promise<string | undefined>;
     /**
      * Request that the user adds the specified tokens for a given contract to the wallet.
      * Returns which of the given tokens the user accepted to add the tokens into the wallet.
@@ -84,12 +134,32 @@ interface MainWalletApi {
     addCIS2Tokens(accountAddress: string, tokenIds: string[], contractIndex: bigint, contractSubindex?: bigint): Promise<string[]>;
     /**
      * Request that the user provides a proof for the given statement.
+     * @deprecated Please use { @link requestVerifiablePresentation} instead.
      * @param accountAddress the address of the account that should prove the statement.
      * @param statement the id statement that should be proven.
      * @param challenge bytes chosen by the verifier. Should be HEX encoded.
      * @returns The id proof and the id of the credential used to prove it.
      */
     requestIdProof(accountAddress: string, statement: IdStatement, challenge: string): Promise<IdProofOutput>;
+    /**
+     * Requests that a web3IdCredential is added to the wallet.
+     * Note that this will throw an error if the dApp is not allowlisted, locked, or if the user rejects adding the credential.
+     * @param credential the web3IdCredential that should be added to the wallet
+     * @param metadataUrl the url where the metadata, to display the credential, is located.
+     * @param createSignature a callback function, which takes a DID identifier for the credentialHolderId as input and must return the randomness used for the commitment of the values and signature on the commitments and credentialId.
+     * @returns the DID identifier for the credentialHolderId, i.e. the publicKey that will be associated with the credential.
+     */
+    addWeb3IdCredential(credential: APIVerifiableCredential, metadataUrl: MetadataUrl, generateProofAndRandomness: (credentialHolderIdDID: string) => Promise<{
+        randomness: Record<string, string>;
+        proof: CredentialProof;
+    }>): Promise<string>;
+    /**
+     * Request that the user provides a proof for the given statements.
+     * @param challenge bytes chosen by the verifier. Should be HEX encoded.
+     * @param statements the web3Id statements that should be proven. The promise rejects if the array of statements is empty.
+     * @returns The presentation for the statements.
+     */
+    requestVerifiablePresentation(challenge: string, statements: CredentialStatements): Promise<VerifiablePresentation>;
 }
 export declare type WalletApi = MainWalletApi & EventListeners;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@concordium/browser-wallet-api-helpers",
-    "version": "2.4.0",
+    "version": "2.6.0",
     "license": "Apache-2.0",
     "packageManager": "yarn@3.2.0",
     "main": "lib/index.js",
@@ -19,7 +19,7 @@
         "url": "https://concordium.com"
     },
     "dependencies": {
-        "@concordium/web-sdk": "^3.4.0"
+        "@concordium/web-sdk": "^6.1.1"
     },
     "devDependencies": {
         "@babel/core": "^7.17.10",
@@ -31,6 +31,7 @@
         "webpack-cli": "^4.9.2"
     },
     "scripts": {
-        "build": "tsc && webpack"
+        "build": "tsc && webpack",
+        "build:api-helpers": "yarn build"
     }
 }