@concordium/browser-wallet-api-helpers 0.1.0

package/README.md

@@ -0,0 +1,116 @@
+# browser-wallet-api-helpers
+
+This package includes the types for the API to be used in web applications for communicating with the Concordium browser wallet. The API is injected into `window.concordium` when it is ready.
+
+The actual implementation of the wallet API can be found in the [in the Concordium browser wallet repository.](https://github.com/Concordium/concordium-browser-wallet/tree/main/packages/browser-wallet-api)
+
+## Development
+
+### Installing
+
+See [installing](../../README.md#installing) in repository root.
+
+### Building
+
+-   Run `yarn build` in the package root, which will output into the folder "lib".
+
+## Using the API
+
+The API is automatically injected into web applications if the Concordium browser wallet extension is installed in the browser. To get access to the API a helper function is provided by this package which can be used as follows:
+
+```typescript
+import { detectConcordiumProvider } from '@concordium/browser-wallet-api-helpers';
+
+detectConcordiumProvider()
+    .then((provider) => {
+        // The API is ready for use.
+        provider
+            .connect()
+            .then((accountAddress) => {
+                // The wallet is connected to the dApp.
+            })
+            .catch(() => console.log('Connection to the Concordium browser wallet was rejected.'));
+    })
+    .catch(() => console.log('Connection to the Concordium browser wallet timed out.'));
+```
+
+### Custom method for accessing the API
+
+If you do not wish to use the provided utility function, then it is also possible to access the API directly on `window.concordium`. If you do this, then it is your responsibility to make the necessary checks to determine if the API is ready to use. To get proper typing for this you need to update your global definitions for `Window`.
+
+```typescript
+import { WalletApi } from '@concordium/browser-wallet-api-helpers';
+declare global {
+    interface Window {
+        concordium: WalletApi | undefined;
+    }
+}
+```
+
+## API instance methods
+
+### 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 currently selected account in the wallet, or rejecting if the request is rejected in the wallet. If this is not called, it will be called as part of any other request (f.x. `sendTransaction` or `signMessage`) made by the API.
+
+```typescript
+const provider = await detectConcordiumProvider();
+const accountAddress = await provider.connect();
+```
+
+### sendTransaction
+
+To send a transaction, two arguments need to be provided: A transaction type and a corresponding payload. Invoking `sendTransaction` returns a `Promise`, which resolves with the transaction hash for the submitted transaction.
+
+The following exemplifies how to create a simple transfer of funds from one account (selected account in the wallet) 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.
+
+```typescript
+const provider = await detectConcordiumProvider();
+const txHash = await provider.sendTransaction(concordiumSDK.AccountTransactionType.SimpleTransfer, {
+    amount: new concordiumSDK.GtuAmount(1n),
+    toAddress: new concordiumSDK.AccountAddress('39bKAuC7sXCZQfo7DmVQTMbiUuBMQJ5bCfsS7sva1HvDnUXp13'),
+});
+```
+
+In the case of a smart contract init/update, parameters for the specific function and a corresponding schema for serializing the parameters can be defined.
+
+```typescript
+const provider = await detectConcordiumProvider();
+const txHash = await provider.sendTransaction(
+    concordiumSDK.AccountTransactionType.UpdateSmartContractInstance,
+    {
+        amount: new concordiumSDK.GtuAmount(1n),
+        contractAddress: {
+            index: 11n,
+            subindex: 0n,
+        },
+        receiveName: 'two-step-transfer.receive',
+        maxContractExecutionEnergy: 30000n,
+    },
+    {
+        RequestTransfer: ['1000', '1', '3Y1RLgi5pW3x96xZ7CiDiKsTL9huU92qn6mfxpebwmtkeku8ry'],
+    },
+    'AQAAABEAAAB0d28tc3RlcC10cmFuc2ZlcgEUAAIAAAALAAAAaW5pdF9wYXJhbXMUAAMAAAAPAAAAYWNjb3VudF9ob2xkZXJzEQALHAAAAHRyYW5zZmVyX2FncmVlbWVudF90aHJlc2hvbGQCFAAAAHRyYW5zZmVyX3JlcXVlc3RfdHRsDggAAAByZXF1ZXN0cxIBBRQABAAAAA8AAAB0cmFuc2Zlcl9hbW91bnQKDgAAAHRhcmdldF9hY2NvdW50CwwAAAB0aW1lc19vdXRfYXQNCgAAAHN1cHBvcnRlcnMRAgsBFAADAAAADwAAAGFjY291bnRfaG9sZGVycxEACxwAAAB0cmFuc2Zlcl9hZ3JlZW1lbnRfdGhyZXNob2xkAhQAAAB0cmFuc2Zlcl9yZXF1ZXN0X3R0bA4BAAAABwAAAHJlY2VpdmUVAgAAAA8AAABSZXF1ZXN0VHJhbnNmZXIBAwAAAAUKCw8AAABTdXBwb3J0VHJhbnNmZXIBAwAAAAUKCw=='
+);
+```
+
+### signMessage
+
+It is possible to sign arbitrary messages using the keys for an account stored in the wallet, by invoking the `signMessage` method. This method returns a `Promise` resolving with a signature of the message.
+
+The following exemplifies requesting a signature of a message:
+
+```typescript
+const provider = await detectConcordiumProvider();
+const signature = await provider.signMessage('This is a message to be signed');
+```
+
+### addChangeAccountListener
+
+To react when the selected account in the wallet changes, a handler function can be assigned through `addChangeAccountListener`. This does **not** return the currently selected account when the handler is initially assigned. This can be obtained by invoking the `connect` method.
+
+```typescript
+const provider = await detectConcordiumProvider();
+let selectedAccountAddress: string | undefined = undefined;
+provider.addChangeAccountListener((address) => (selectedAccountAddress = address));
+```

package/lib/concordiumHelpers.min.js

@@ -0,0 +1,2 @@
+!function(e,o){"object"==typeof exports&&"object"==typeof module?module.exports=o():"function"==typeof define&&define.amd?define([],o):"object"==typeof exports?exports.concordiumHelpers=o():e.concordiumHelpers=o()}(self,(()=>(()=>{"use strict";var e={611:(e,o)=>{Object.defineProperty(o,"__esModule",{value:!0}),o.detectConcordiumProvider=async function(e=5e3){return new Promise(((o,r)=>{if(window.concordium)o(window.concordium);else{const t=setTimeout((()=>{window.concordium?o(window.concordium):r()}),e);window.addEventListener("concordium#initialized",(()=>{window.concordium&&(clearTimeout(t),o(window.concordium))}),{once:!0})}}))}},685:(e,o,r)=>{Object.defineProperty(o,"__esModule",{value:!0});var t={detectConcordiumProvider:!0};Object.defineProperty(o,"detectConcordiumProvider",{enumerable:!0,get:function(){return i.detectConcordiumProvider}});var n=r(740);Object.keys(n).forEach((function(e){"default"!==e&&"__esModule"!==e&&(Object.prototype.hasOwnProperty.call(t,e)||e in o&&o[e]===n[e]||Object.defineProperty(o,e,{enumerable:!0,get:function(){return n[e]}}))}));var i=r(611)},740:(e,o)=>{Object.defineProperty(o,"__esModule",{value:!0})}},o={};return function r(t){var n=o[t];if(void 0!==n)return n.exports;var i=o[t]={exports:{}};return e[t](i,i.exports,r),i.exports}(685)})()));
+//# sourceMappingURL=concordiumHelpers.min.js.map

package/lib/concordiumHelpers.min.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"concordiumHelpers.min.js","mappings":"CAAA,SAA2CA,EAAMC,GAC1B,iBAAZC,SAA0C,iBAAXC,OACxCA,OAAOD,QAAUD,IACQ,mBAAXG,QAAyBA,OAAOC,IAC9CD,OAAO,GAAIH,GACe,iBAAZC,QACdA,QAA2B,kBAAID,IAE/BD,EAAwB,kBAAIC,IAR9B,CASGK,MAAM,I,kHCHFC,eAAwCC,EAAU,KACrD,OAAO,IAAIC,SAAQ,CAACC,EAASC,KACzB,GAAIC,OAAOC,WACPH,EAAQE,OAAOC,gBAEd,CACD,MAAMC,EAAIC,YAAW,KACbH,OAAOC,WACPH,EAAQE,OAAOC,YAGfF,MAELH,GACHI,OAAOI,iBAAiB,0BAA0B,KAC1CJ,OAAOC,aACPI,aAAaH,GACbJ,EAAQE,OAAOC,eAEpB,CAAEK,MAAM,U,yNCzBvB,8NACA,c,+DCAIC,EAA2B,G,OAG/B,SAASC,EAAoBC,GAE5B,IAAIC,EAAeH,EAAyBE,GAC5C,QAAqBE,IAAjBD,EACH,OAAOA,EAAapB,QAGrB,IAAIC,EAASgB,EAAyBE,GAAY,CAGjDnB,QAAS,IAOV,OAHAsB,EAAoBH,GAAUlB,EAAQA,EAAOD,QAASkB,GAG/CjB,EAAOD,QClBWkB,CAAoB,M","sources":["webpack:///webpack/universalModuleDefinition","webpack:///./lib/detector.js","webpack:///./lib/index.js","webpack:///webpack/bootstrap","webpack:///webpack/startup"],"sourcesContent":["(function webpackUniversalModuleDefinition(root, factory) {\n\tif(typeof exports === 'object' && typeof module === 'object')\n\t\tmodule.exports = factory();\n\telse if(typeof define === 'function' && define.amd)\n\t\tdefine([], factory);\n\telse if(typeof exports === 'object')\n\t\texports[\"concordiumHelpers\"] = factory();\n\telse\n\t\troot[\"concordiumHelpers\"] = factory();\n})(self, () => {\nreturn ","/**\n * Detect the Concordium browser wallet API by waiting for it to have been successfully injected\n * into the window so that it is ready for use.\n * @param timeout determines how long to wait before rejecting if the Concordium provider is not available, in milliseconds.\n * @returns a promise containing the Concordium Wallet provider API.\n */\nexport async function detectConcordiumProvider(timeout = 5000) {\n    return new Promise((resolve, reject) => {\n        if (window.concordium) {\n            resolve(window.concordium);\n        }\n        else {\n            const t = setTimeout(() => {\n                if (window.concordium) {\n                    resolve(window.concordium);\n                }\n                else {\n                    reject();\n                }\n            }, timeout);\n            window.addEventListener('concordium#initialized', () => {\n                if (window.concordium) {\n                    clearTimeout(t);\n                    resolve(window.concordium);\n                }\n            }, { once: true });\n        }\n    });\n}\n","export * from './wallet-api-types';\nexport { detectConcordiumProvider } from './detector';\n","// The module cache\nvar __webpack_module_cache__ = {};\n\n// The require function\nfunction __webpack_require__(moduleId) {\n\t// Check if module is in cache\n\tvar cachedModule = __webpack_module_cache__[moduleId];\n\tif (cachedModule !== undefined) {\n\t\treturn cachedModule.exports;\n\t}\n\t// Create a new module (and put it into the cache)\n\tvar module = __webpack_module_cache__[moduleId] = {\n\t\t// no module.id needed\n\t\t// no module.loaded needed\n\t\texports: {}\n\t};\n\n\t// Execute the module function\n\t__webpack_modules__[moduleId](module, module.exports, __webpack_require__);\n\n\t// Return the exports of the module\n\treturn module.exports;\n}\n\n","// startup\n// Load entry module and return exports\n// This entry module is referenced by other modules so it can't be inlined\nvar __webpack_exports__ = __webpack_require__(685);\n"],"names":["root","factory","exports","module","define","amd","self","async","timeout","Promise","resolve","reject","window","concordium","t","setTimeout","addEventListener","clearTimeout","once","__webpack_module_cache__","__webpack_require__","moduleId","cachedModule","undefined","__webpack_modules__"],"sourceRoot":""}

package/lib/detector.d.ts

@@ -0,0 +1,8 @@
+import { WalletApi } from './wallet-api-types';
+/**
+ * Detect the Concordium browser wallet API by waiting for it to have been successfully injected
+ * into the window so that it is ready for use.
+ * @param timeout determines how long to wait before rejecting if the Concordium provider is not available, in milliseconds.
+ * @returns a promise containing the Concordium Wallet provider API.
+ */
+export declare function detectConcordiumProvider(timeout?: number): Promise<WalletApi>;

package/lib/detector.js

@@ -0,0 +1,29 @@
+/**
+ * Detect the Concordium browser wallet API by waiting for it to have been successfully injected
+ * into the window so that it is ready for use.
+ * @param timeout determines how long to wait before rejecting if the Concordium provider is not available, in milliseconds.
+ * @returns a promise containing the Concordium Wallet provider API.
+ */
+export async function detectConcordiumProvider(timeout = 5000) {
+    return new Promise((resolve, reject) => {
+        if (window.concordium) {
+            resolve(window.concordium);
+        }
+        else {
+            const t = setTimeout(() => {
+                if (window.concordium) {
+                    resolve(window.concordium);
+                }
+                else {
+                    reject();
+                }
+            }, timeout);
+            window.addEventListener('concordium#initialized', () => {
+                if (window.concordium) {
+                    clearTimeout(t);
+                    resolve(window.concordium);
+                }
+            }, { once: true });
+        }
+    });
+}

package/lib/extend-window.d.ts

@@ -0,0 +1,6 @@
+import { WalletApi } from './wallet-api-types';
+declare global {
+    interface Window {
+        concordium: WalletApi | undefined;
+    }
+}

package/lib/extend-window.js

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

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+export * from './wallet-api-types';
+export { detectConcordiumProvider } from './detector';

package/lib/index.js

@@ -0,0 +1,2 @@
+export * from './wallet-api-types';
+export { detectConcordiumProvider } from './detector';

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

@@ -0,0 +1,36 @@
+import type { AccountTransactionPayload, AccountTransactionSignature, AccountTransactionType } from '@concordium/web-sdk';
+export declare type WalletEventHandler<T = any> = (payload: T) => void;
+export interface WalletApi {
+    /**
+     * React to changes to the selected account in the Concordium Wallet. Note that to get the initially selected account on load, the "connect" method should be used.
+     * @param handler a handler function called with the account address of the selected account.
+     */
+    addChangeAccountListener(handler: WalletEventHandler<string>): void;
+    /**
+     * 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.
+     * @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.
+     * @param parameters parameters for the initContract and updateContract transactions in JSON-like format.
+     * @param schema schema used for the initContract and updateContract transactions to serialize the parameters. Should be base64 encoded.
+     */
+    sendTransaction(type: AccountTransactionType.UpdateSmartContractInstance | AccountTransactionType.InitializeSmartContractInstance, payload: AccountTransactionPayload, parameters: Record<string, unknown>, schema: string): 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.
+     * @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.
+     */
+    sendTransaction(type: AccountTransactionType, payload: AccountTransactionPayload): 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.
+     * @param message message to be signed. Note that the wallet will prepend some bytes to ensure the message cannot be a transaction
+     */
+    signMessage(message: string): Promise<AccountTransactionSignature>;
+    /**
+     * 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.
+     */
+    connect(): Promise<string | undefined>;
+}

package/lib/wallet-api-types.js

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

package/package.json

@@ -0,0 +1,36 @@
+{
+    "name": "@concordium/browser-wallet-api-helpers",
+    "version": "0.1.0",
+    "license": "Apache-2.0",
+    "packageManager": "yarn@3.2.0",
+    "main": "lib/index.js",
+    "browser": "lib/concordiumHelpers.min.js",
+    "types": "lib/index.d.ts",
+    "files": [
+        "/lib/**/*"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/Concordium/concordium-browser-wallet"
+    },
+    "author": {
+        "name": "Concordium Software",
+        "email": "support@concordium.software",
+        "url": "https://concordium.com"
+    },
+    "dependencies": {
+        "@concordium/web-sdk": "^0.1.2"
+    },
+    "devDependencies": {
+        "@babel/core": "^7.17.10",
+        "@babel/plugin-transform-modules-commonjs": "^7.12.1",
+        "@babel/plugin-transform-runtime": "^7.12.1",
+        "@babel/preset-env": "^7.12.1",
+        "typescript": "^4.3.5",
+        "webpack": "^5.72.0",
+        "webpack-cli": "^4.9.2"
+    },
+    "scripts": {
+        "build": "tsc && webpack"
+    }
+}