@silencelaboratories/walletprovider-sdk 0.0.5 → 0.0.7

package/README.md

@@ -1,5 +1,129 @@
 # walletprovider-sdk
 
+The frontend library for Silent Network.
+
+# Demo
+
+Under the [demo](./demo) directory we provide the sample webpage that shows example usage of the library.
+In order to run it execute the following:
+
+1. Build the library
+
+```
+bun install
+bun run build
+```
+
+2. Run the demo
+
+```
+cd demo
+npm install
+npm run dev
+```
+
+The demo fetches configuration from the `.env` file. We provided example `.env` [here](./demo/.env).
+
+The demo communicates with [backend service](#the-backend). Run it before using the demo page.
+
+# Using the library
+
+The library is published on [npmjs](https://www.npmjs.com/package/@silencelaboratories/walletprovider-sdk) registry.
+
+Install it in your project as usual:
+
+```
+npm i @silencelaboratories/walletprovider-sdk
+```
+
+## The backend
+
+The library communicates with backend service. The example implementation of such service is accessible [here](https://shipyard.rs/silencelaboratories/crates/wallet-provider-service). Please refer to backend documentation in order to run the service.
+
+Frontend uses [WalletProviderServiceClient](./docs/walletprovider-sdk.walletproviderserviceclient.md) object in order to connect to the backend and send requests.
+
+# Documentation
+
+For description of classes, interfaces, types, please refer to [documentation](./docs/walletprovider-sdk.md).
+
+## Keygen
+
+The full working example is in the [demo](./demo/src/routes/%2Bpage.svelte#L87).
+The core object to use is the [NetworkSigner](./docs/walletprovider-sdk.networksigner.md).
+
+It allows to generate keys and do signatures. In order to create, you need two other components. The [WalletProviderServiceClient](./docs/walletprovider-sdk.walletproviderserviceclient.md) that connects to the Backend part of the SDK, and the authentication module. Currently we provide EOA authentication via [EOAAuth](./docs/walletprovider-sdk.eoaauth.md).
+
+Let's create the `NetworkSigner`
+
+```ts
+const wpClient = await createWalletProviderService(clusterConfig);
+// Authenticate using EOA
+const eoaAuth = new EOAAuth(accountsFromBrowserWallet[0], new BrowserWallet());
+
+// Create a new signer instance
+const sdk = new NetworkSigner(wpClient, threshold, partiesNumber, eoaAuth);
+```
+
+Now you can generate a key, using the [authenticateAndCreateKey](./docs/walletprovider-sdk.networksigner.authenticateandcreatekey.md) method. The method accepts optional permissions. No permissions means _allow all operations_.
+
+```ts
+const permissions = {
+  permissions: [
+    {
+      type: 'erc20',
+      method: 'approve',
+      to: '0x1234567890123456789012345678901234567890',
+      args: {
+        spender: '0x1234567890123456789012345678901234567890',
+        value: 10000,
+        eq: '<',
+      },
+    },
+  ],
+};
+
+// Generate a new key
+let resp: KeygenResponse = await sdk.authenticateAndCreateKey(JSON.stringify(permissions));
+```
+
+Calling this method will cause to the Browser Wallet window to pop up, requesting the User to sign the request. After execution [KeygenResponse](./docs/walletprovider-sdk.keygenresponse.md) is returned.
+
+The [KeygenResponse](./docs/walletprovider-sdk.keygenresponse.md) contains `keyId` and `publicKey`. The `publicKey` is the public part of the key generated by Silent Network. Use the `keyId` in subsequent calls to sign.
+
+## Signing
+
+The full signing example is [here](./demo/src/routes/%2Bpage.svelte#L158).
+
+Use the [NetworkSigner.authenticateAndSign](./docs/walletprovider-sdk.networksigner.authenticateandsign.md) method in order to generate a signature.
+
+```ts
+let signMessage = JSON.stringify({
+  userOperation: {
+    sender: '0x8d4cb2540d993fe34c646299f1ab4af3012ff34c',
+    nonce: '0x7',
+    initCode: '',
+    callData: '0000189a...',
+    callGasLimit: '123130',
+    verificationGasLimit: '153427',
+    preVerificationGas: '66768',
+    maxFeePerGas: '',
+    maxPriorityFeePerGas: '',
+    paymasterAndData: '',
+  },
+  entryPointVersion: 'v0.6.0',
+  entryPointAddress: '0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789',
+  chainId: 80002,
+});
+
+let resp = await sdk.authenticateAndSign(selectedKeyId, signMessage);
+```
+
+The [SignResponse](./docs/walletprovider-sdk.signresponse.md) contains the signature `sign` and the recovery ID `recid`.
+
+# Developing the library
+
+Audience of this section are library developers.
+
 ## Bun runtime is required
 
 Install bun from https://bun.sh
@@ -31,5 +155,11 @@ bun run test:watch
 ## Format the code
 
 ```bash
-npx prettier . --write
+bun run format
+```
+
+## Generate the documentation
+
+```bash
+bun run docs
 ```

package/dist/EOAauthentication.d.ts

@@ -1,3 +1,6 @@
+/** Externally Owned Account (EOA) atuhentication. Uses secret key stored on a wallet to sign requests.
+ * The requests are presented to the user in a readable form by using TypedData (EIP712).
+ */
 import { KeygenSetupOpts, type SignSetupOpts } from './networkSigner.ts';
 import { type UserAuthentication } from './authentication.ts';
 import type { TypedDataDomain } from 'viem';
@@ -5,15 +8,45 @@ export type FieldDefinition = {
     name: string;
     type: string;
 };
+/** EIP-712 Typed data struct definition.
+ * @alpha
+ * */
 export type TypedData<T> = {
+    /** contains the schema definition of the types that are in `msg` */
     types: Record<string, Array<FieldDefinition>>;
+    /** is the signature domain separator */
     domain: TypedDataDomain;
+    /** points to the type from `types`. It's the root object of `message` */
     primaryType: string;
+    /** the request that User is asked to sign */
     message: T;
 };
+/**
+ * Interface to implement communication between this library, and a Browser Wallet. In order to
+ * request the signature from the User.
+ * @alpha
+ */
 export interface IBrowserWallet {
+    /** Sign data using the secret key stored on Browser Wallet
+     * It creates a popup window, presenting the human readable form of `request`
+     * @param from - the address used to sign the request
+     * @param request - the request to sign by the User in the form of EIP712 typed data.
+     * @throws Throws an error if User rejected signature
+     * @example The example implementation:
+     * ```ts
+     * async signTypedData<T>(from: string, request: TypedData<T>): Promise<unknown> {
+     *   return await browserWallet.request({
+     *     method: 'eth_signTypedData_v4',
+     *     params: [from, JSON.stringify(request)],
+     *   });
+     * }
+     * ```
+     */
     signTypedData<T>(from: string, request: TypedData<T>): Promise<unknown>;
 }
+/** Present the request to the User using wallet UI, and ask for sign.
+ * The signature is the authorization for the operation
+ */
 export declare function authenticateUsingEOA({ setup, user_id, challenge, browserWallet, }: {
     setup: KeygenSetupOpts | SignSetupOpts;
     user_id: string;

package/dist/EOAauthentication.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EOAauthentication.d.ts","sourceRoot":"","sources":["../src/EOAauthentication.ts"],"names":[],"mappings":"AAGA,OAAO,EAAmB,eAAe,EAAE,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAC1F,OAAO,EAAE,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,MAAM,CAAC;AAE5C,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAOF,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI;IACzB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC,CAAC;IAC9C,MAAM,EAAE,eAAe,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,CAAC,CAAC;CACZ,CAAC;AAEF,MAAM,WAAW,cAAc;IAa7B,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACzE;AAkJD,wBAAsB,oBAAoB,CAAC,EACzC,KAAK,EACL,OAAO,EACP,SAAS,EACT,aAAa,GACd,EAAE;IACD,KAAK,EAAE,eAAe,GAAG,aAAa,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,cAAc,CAAC;CAC/B,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA4B9B"}
+{"version":3,"file":"EOAauthentication.d.ts","sourceRoot":"","sources":["../src/EOAauthentication.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAmB,eAAe,EAAE,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAC1F,OAAO,EAAE,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,MAAM,CAAC;AAE5C,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;KAEK;AACL,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI;IACzB,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC,CAAC;IAC9C,wCAAwC;IACxC,MAAM,EAAE,eAAe,CAAC;IACxB,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,OAAO,EAAE,CAAC,CAAC;CACZ,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;;;;;;;;;OAcG;IACH,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACzE;AAgJD;;GAEG;AACH,wBAAsB,oBAAoB,CAAC,EACzC,KAAK,EACL,OAAO,EACP,SAAS,EACT,aAAa,GACd,EAAE;IACD,KAAK,EAAE,eAAe,GAAG,aAAa,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,cAAc,CAAC;CAC/B,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA4B9B"}

package/dist/authentication.d.ts

@@ -1,8 +1,12 @@
 import { KeygenSetupOpts, SignSetupOpts } from './networkSigner';
 import { IBrowserWallet } from './EOAauthentication';
-import { IWalletProviderServiceClient } from './walletProviderServiceClientInterface';
+/** Type of the request authentication
+ * @alpha
+ */
 export declare enum AuthMethod {
+    /** Authentication using Externally Owned Account */
     EOA = 0,
+    /** No authentication */
     NONE = 1
 }
 export type UserCredentials = {
@@ -20,11 +24,22 @@ export interface AuthModule {
         challenge: string;
     }): Promise<UserAuthentication>;
 }
+/** The `AuthModule` implementing Externally Owned Account authentication.
+ * @alpha
+ */
 export declare class EOAAuth implements AuthModule {
+    /** User ID, typically the ETH address that is used to do authentication */
     userId: string;
+    /** An interface to the wallet, like MetaMask, that is used to sign the requests */
     browserWallet: IBrowserWallet;
-    wpClient: IWalletProviderServiceClient;
-    constructor(userId: string, browserWallet: IBrowserWallet, wpClient: IWalletProviderServiceClient);
+    constructor(userId: string, browserWallet: IBrowserWallet);
+    /**
+     * Prepares a message to present on the Browser Wallet window and requests to sign it.
+     * @param setup - either Keygen or Sign setup options
+     * @param challenge - the challenge received from the backend
+     *
+     * @public
+     */
     authenticate({ setup, challenge, }: {
         setup: KeygenSetupOpts | SignSetupOpts;
         challenge: string;

package/dist/authentication.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"authentication.d.ts","sourceRoot":"","sources":["../src/authentication.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACjE,OAAO,EAAE,cAAc,EAAwB,MAAM,qBAAqB,CAAC;AAC3E,OAAO,EAAE,4BAA4B,EAAE,MAAM,wCAAwC,CAAC;AAEtF,oBAAY,UAAU;IACpB,GAAG,IAAA;IACH,IAAI,IAAA;CACL;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,MAAM,CAAC;IAEX,MAAM,EAAE,MAAM,CAAC;IAEf,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,WAAW,EAAE,eAAe,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,WAAW,UAAU;IACzB,YAAY,CAAC,EACX,KAAK,EACL,SAAS,GACV,EAAE;QACD,KAAK,EAAE,eAAe,GAAG,aAAa,CAAC;QACvC,SAAS,EAAE,MAAM,CAAC;KACnB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACjC;AAED,qBAAa,OAAQ,YAAW,UAAU;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,cAAc,CAAC;IAC9B,QAAQ,EAAE,4BAA4B,CAAC;gBAE3B,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,cAAc,EAAE,QAAQ,EAAE,4BAA4B;IAM3F,YAAY,CAAC,EACjB,KAAK,EACL,SAAS,GACV,EAAE;QACD,KAAK,EAAE,eAAe,GAAG,aAAa,CAAC;QACvC,SAAS,EAAE,MAAM,CAAC;KACnB,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAQhC"}
+{"version":3,"file":"authentication.d.ts","sourceRoot":"","sources":["../src/authentication.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACjE,OAAO,EAAE,cAAc,EAAwB,MAAM,qBAAqB,CAAC;AAE3E;;GAEG;AACH,oBAAY,UAAU;IACpB,oDAAoD;IACpD,GAAG,IAAA;IACH,wBAAwB;IACxB,IAAI,IAAA;CACL;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,MAAM,CAAC;IAEX,MAAM,EAAE,MAAM,CAAC;IAEf,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,WAAW,EAAE,eAAe,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,WAAW,UAAU;IACzB,YAAY,CAAC,EACX,KAAK,EACL,SAAS,GACV,EAAE;QACD,KAAK,EAAE,eAAe,GAAG,aAAa,CAAC;QACvC,SAAS,EAAE,MAAM,CAAC;KACnB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACjC;AAED;;GAEG;AACH,qBAAa,OAAQ,YAAW,UAAU;IACxC,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,mFAAmF;IACnF,aAAa,EAAE,cAAc,CAAC;gBAElB,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,cAAc;IAKzD;;;;;;OAMG;IACG,YAAY,CAAC,EACjB,KAAK,EACL,SAAS,GACV,EAAE;QACD,KAAK,EAAE,eAAe,GAAG,aAAa,CAAC;QACvC,SAAS,EAAE,MAAM,CAAC;KACnB,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAQhC"}

package/dist/index.d.ts

@@ -1,8 +1,6 @@
-export { KeygenSetupOpts, NetworkSigner } from './networkSigner.ts';
-export { createViemAccount } from './viemSigner.ts';
+export { NetworkSigner, SignResponse, KeygenResponse } from './networkSigner.ts';
 export { AuthMethod, EOAAuth } from './authentication.ts';
-export type { TypedData } from './EOAauthentication.ts';
-export type { UserAuthenticatedRequest, KeygenResponse, SignSetupOpts, SignResponse } from './networkSigner.ts';
-export type { IWalletProviderServiceClient } from './walletProviderServiceClientInterface.ts';
+export type { IBrowserWallet, TypedData } from './EOAauthentication.ts';
+export type { ClientConfig, IWalletProviderServiceClient } from './walletProviderServiceClientInterface.ts';
 export { WalletProviderServiceClient } from './walletProviderServiceClient.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAE1D,YAAY,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,YAAY,EAAE,wBAAwB,EAAE,cAAc,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEhH,YAAY,EAAE,4BAA4B,EAAE,MAAM,2CAA2C,CAAC;AAC9F,OAAO,EAAE,2BAA2B,EAAE,MAAM,kCAAkC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAE1D,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAExE,YAAY,EAAE,YAAY,EAAE,4BAA4B,EAAE,MAAM,2CAA2C,CAAC;AAC5G,OAAO,EAAE,2BAA2B,EAAE,MAAM,kCAAkC,CAAC"}