Merge pull request #2050 from aeternity/snap-versioning

davidyuk · web-flow · commit 3b7853c505f1 · 2025-03-11T16:55:36.000+01:00
Implicitly connect to Aeternity snap, detect MetaMask over EIP-6963
diff --git a/docs/guides/metamask-snap.md b/docs/guides/metamask-snap.md
@@ -19,14 +19,6 @@ import { AccountMetamaskFactory } from '@aeternity/aepp-sdk';
 const accountFactory = new AccountMetamaskFactory();
 ```
 
-The next step is to install Aeternity snap to MetaMask. You can request installation by calling
-
-```js
-await accountFactory.installSnap();
-```
-
-If succeed it means that MetaMask is ready to provide access to accounts. Alternatively, you can call `ensureReady` instead of `installSnap`. The latter won't trigger a snap installation, it would just fall with the exception if not installed.
-
 Using the factory, you can create instances of specific accounts by providing an index
 
 ```js
@@ -69,4 +61,6 @@ console.log(accounts[0].address); // 'ak_2dA...'
 
 ## Error handling
 
-If the user rejects a transaction/message signing or address retrieving you will get an exception as a plain object with property `code` equals 4001, and `message` equals "User rejected the request.".
+If the user rejects an action (snap installation or connection, address retrieving or transaction/message signing) you will get an exception as a plain object with property `code` equals 4001, and `message` equals "User rejected the request.".
+
+If the snap downgrade is requested, the code will be -32602.
diff --git a/examples/browser/aepp/src/components/ConnectMetamask.vue b/examples/browser/aepp/src/components/ConnectMetamask.vue
@@ -3,7 +3,7 @@
     <button v-if="!accountFactory" @click="connect">Connect</button>
     <template v-else>
       <button @click="disconnect">Disconnect</button>
-      <button @click="installSnap">Install Aeternity Snap</button>
+      <button @click="requestSnap">Request Aeternity Snap</button>
       <button @click="addAccount">Add Account</button>
       <button v-if="accounts.length > 1" @click="switchAccount">Switch Account</button>
       <button @click="discoverAccounts">Discover Accounts</button>
@@ -54,10 +54,10 @@ export default {
       this.$store.commit('setAddress', undefined);
       if (Object.keys(this.aeSdk.accounts).length) this.aeSdk.removeAccount(this.aeSdk.address);
     },
-    async installSnap() {
+    async requestSnap() {
       try {
         this.status = 'Waiting for MetaMask response';
-        this.status = await this.accountFactory.installSnap();
+        this.status = await this.accountFactory.requestSnap();
       } catch (error) {
         if (error instanceof UnsupportedPlatformError) {
           this.status = error.message;
diff --git a/src/account/Metamask.ts b/src/account/Metamask.ts
@@ -27,6 +27,9 @@ export async function invokeSnap<R>(
  * https://www.npmjs.com/package/\@aeternity-snap/plugin
  */
 export default class AccountMetamask extends AccountBase {
+  /**
+   * @deprecated this class is not intended to provide raw access to the provider
+   */
   readonly provider: BaseProvider;
 
   readonly index: number;
diff --git a/src/account/MetamaskFactory.ts b/src/account/MetamaskFactory.ts
@@ -11,6 +11,7 @@ import AccountMetamask, { invokeSnap, snapId } from './Metamask.js';
 
 const snapMinVersion = '0.0.9';
 const snapMaxVersion = '0.1.0';
+const metamaskVersionPrefix = 'MetaMask/v';
 
 interface SnapDetails {
   blocked: boolean;
@@ -22,90 +23,138 @@ interface SnapDetails {
 
 /**
  * A factory class that generates instances of AccountMetamask.
+ * @see {@link https://www.npmjs.com/package/@aeternity-snap/plugin | Aeternity snap}
  */
 export default class AccountMetamaskFactory extends AccountBaseFactory {
-  readonly provider: BaseProvider;
+  // TODO: remove after removing `provider`
+  #provider: BaseProvider | undefined;
+
+  /**
+   * @deprecated this class is not intended to provide raw access to the provider
+   */
+  get provider(): BaseProvider {
+    if (this.#provider == null) throw new UnsupportedPlatformError('Metamask is not detected yet');
+    return this.#provider;
+  }
+
+  async #getMetamaskAsInjected(): Promise<BaseProvider | undefined> {
+    if (!('ethereum' in window) || window.ethereum == null) return;
+    const provider = window.ethereum as BaseProvider;
+    const version = await provider.request<string>({ method: 'web3_clientVersion' });
+    if (version == null) throw new InternalError("Can't get Ethereum Provider version");
+    if (!version.startsWith(metamaskVersionPrefix)) return;
+    return provider;
+  }
+
+  async #getMetamaskOverEip6963(): Promise<BaseProvider | undefined> {
+    setTimeout(() => window.dispatchEvent(new Event('eip6963:requestProvider')));
+    return new Promise<BaseProvider | undefined>((resolve) => {
+      const handler = (
+        event: CustomEvent<{ info: { rdns: string }; provider: BaseProvider }>,
+      ): void => {
+        if (event.detail.info.rdns !== 'io.metamask') return;
+        window.removeEventListener('eip6963:announceProvider', handler);
+        resolve(event.detail.provider);
+      };
+      window.addEventListener('eip6963:announceProvider', handler);
+      setTimeout(() => {
+        window.removeEventListener('eip6963:announceProvider', handler);
+        resolve(undefined);
+      }, 500);
+    });
+  }
+
+  #providerPromise: Promise<BaseProvider> | undefined;
+
+  async #getProvider(): Promise<BaseProvider> {
+    this.#providerPromise ??= (async () => {
+      this.#provider ??=
+        (await this.#getMetamaskAsInjected()) ?? (await this.#getMetamaskOverEip6963());
+      if (this.#provider == null) {
+        throw new UnsupportedPlatformError(
+          "Can't find a Metamask extension as an injected provider and over EIP-6963. Ensure that Metamask is installed or setup a provider.",
+        );
+      }
+      const version = await this.#provider.request<string>({ method: 'web3_clientVersion' });
+      if (version == null) throw new InternalError("Can't get Ethereum Provider version");
+      const args = [version.slice(metamaskVersionPrefix.length), '12.2.4'] as const;
+      if (!semverSatisfies(...args)) throw new UnsupportedVersionError('Metamask', ...args);
+      return this.#provider;
+    })();
+    return this.#providerPromise;
+  }
 
   /**
    * @param provider - Connection to MetaMask to use
    */
   constructor(provider?: BaseProvider) {
     super();
-    if (provider != null) {
-      this.provider = provider;
-      return;
-    }
-    if (window == null) {
+    this.#provider = provider;
+    if (this.#provider == null && window == null) {
       throw new UnsupportedPlatformError(
         'Window object not found, you can run AccountMetamaskFactory only in browser or setup a provider',
       );
     }
-    if (!('ethereum' in window) || window.ethereum == null) {
-      throw new UnsupportedPlatformError(
-        '`ethereum` object not found, you can run AccountMetamaskFactory only with Metamask enabled or setup a provider',
-      );
-    }
-    this.provider = window.ethereum as BaseProvider;
   }
 
   /**
-   * It throws an exception if MetaMask has an incompatible version.
+   * Request MetaMask to install Aeternity snap.
+   * @deprecated use `requestSnap` instead
    */
-  async #ensureMetamaskSupported(): Promise<void> {
-    const version = await this.provider.request<string>({ method: 'web3_clientVersion' });
-    if (version == null) throw new InternalError("Can't get Ethereum Provider version");
-    const metamaskPrefix = 'MetaMask/v';
-    if (!version.startsWith(metamaskPrefix)) {
-      throw new UnsupportedPlatformError(`Expected Metamask, got ${version} instead`);
-    }
-    const args = [version.slice(metamaskPrefix.length), '12.2.4'] as const;
-    if (!semverSatisfies(...args)) throw new UnsupportedVersionError('Metamask', ...args);
+  async installSnap(): Promise<SnapDetails> {
+    const provider = await this.#getProvider();
+    const details = (await provider.request({
+      method: 'wallet_requestSnaps',
+      params: { [snapId]: { version: snapMinVersion } },
+    })) as { [key in typeof snapId]: SnapDetails };
+    return details[snapId];
   }
 
-  #ensureReadyPromise?: Promise<void>;
-
   /**
-   * Request MetaMask to install Aeternity snap.
+   * Request MetaMask to install Aeternity snap or connect it to the current aepp.
+   * MetaMask can have only one Aeternity snap version installed at a time.
+   * This method is intended to upgrade the snap to a specified version if needed by the aepp.
+   * If Aeternity snap is installed but wasn't used by the aepp, then the user still needs to approve the connection.
+   * If the currently installed version corresponds to the version range, then the snap won't be upgraded.
+   * To downgrade the snap, the user must manually uninstall the current version.
+   * @param version - Snap version range (e.g. `1`, `0.1.*`, `^0.0.9`, `~0.0.9`; `>=0.0.9 <0.1.0`)
+   * (default: a version range supported by sdk)
    */
-  async installSnap(): Promise<SnapDetails> {
-    await this.#ensureMetamaskSupported();
-    const details = (await this.provider.request({
+  async requestSnap(version = `>=${snapMinVersion} <${snapMaxVersion}`): Promise<SnapDetails> {
+    const provider = await this.#getProvider();
+    const details = (await provider.request({
       method: 'wallet_requestSnaps',
-      params: { [snapId]: { version: snapMinVersion } },
+      params: { [snapId]: { version } },
     })) as { [key in typeof snapId]: SnapDetails };
-    this.#ensureReadyPromise = Promise.resolve();
     return details[snapId];
   }
 
   /**
    * It throws an exception if MetaMask or Aeternity snap has an incompatible version or is not
-   * installed.
+   * installed or is not connected to the aepp.
+   * @deprecated use `requestSnap` instead
    */
   async ensureReady(): Promise<void> {
     const snapVersion = await this.getSnapVersion();
     const args = [snapVersion, snapMinVersion, snapMaxVersion] as const;
     if (!semverSatisfies(...args))
       throw new UnsupportedVersionError('Aeternity snap in MetaMask', ...args);
-    this.#ensureReadyPromise = Promise.resolve();
-  }
-
-  async #ensureReady(): Promise<void> {
-    this.#ensureReadyPromise ??= this.ensureReady();
-    return this.#ensureReadyPromise;
   }
 
   /**
    * @returns the version of snap installed in MetaMask
    */
   async getSnapVersion(): Promise<string> {
-    await this.#ensureMetamaskSupported();
-    const snaps = (await this.provider.request({ method: 'wallet_getSnaps' })) as Record<
+    const provider = await this.#getProvider();
+    const snaps = (await provider.request({ method: 'wallet_getSnaps' })) as Record<
       string,
       { version: string }
     >;
     const version = snaps[snapId]?.version;
     if (version == null)
-      throw new UnsupportedPlatformError('Aeternity snap is not installed to MetaMask');
+      throw new UnsupportedPlatformError(
+        'Aeternity snap is not installed to MetaMask or not connected to this aepp',
+      );
     return version;
   }
 
@@ -114,13 +163,14 @@ export default class AccountMetamaskFactory extends AccountBaseFactory {
    * @param accountIndex - Index of account
    */
   async initialize(accountIndex: number): Promise<AccountMetamask> {
-    await this.#ensureReady();
+    await this.requestSnap();
+    const provider = await this.#getProvider();
     const address = await invokeSnap<Encoded.AccountAddress>(
-      this.provider,
+      provider,
       'getPublicKey',
       { derivationPath: [`${accountIndex}'`, "0'", "0'"] },
       'publicKey',
     );
-    return new AccountMetamask(this.provider, accountIndex, address);
+    return new AccountMetamask(provider, accountIndex, address);
   }
 }
diff --git a/test/unit/metamask.ts b/test/unit/metamask.ts
@@ -107,16 +107,14 @@ describe('Aeternity Snap for MetaMask', function () {
       version: '0.0.9',
     };
 
-    const versionChecks = [
+    const metamaskVersionCheck = [
       { request: { method: 'web3_clientVersion' } },
       { resolve: 'MetaMask/v12.3.1' },
-      { request: { method: 'wallet_getSnaps' } },
-      { resolve: { 'npm:@aeternity-snap/plugin': snapDetails } },
     ];
 
     it('installs snap', async () => {
       const provider = await initProvider([
-        ...versionChecks.slice(0, 2),
+        ...metamaskVersionCheck,
         {
           request: {
             method: 'wallet_requestSnaps',
@@ -133,23 +131,68 @@ describe('Aeternity Snap for MetaMask', function () {
       expect(await factory.installSnap()).to.eql(snapDetails);
     });
 
+    it('requests snap', async () => {
+      const provider = await initProvider([
+        ...metamaskVersionCheck,
+        {
+          request: {
+            method: 'wallet_requestSnaps',
+            params: { 'npm:@aeternity-snap/plugin': { version: '>=0.0.9 <0.1.0' } },
+          },
+        },
+        {
+          resolve: {
+            'npm:@aeternity-snap/plugin': snapDetails,
+          },
+        },
+      ]);
+      const factory = new AccountMetamaskFactory(provider);
+      expect(await factory.requestSnap()).to.eql(snapDetails);
+    });
+
+    const snapVersionCheck = [
+      { request: { method: 'wallet_getSnaps' } },
+      { resolve: { 'npm:@aeternity-snap/plugin': snapDetails } },
+    ];
+
     it('gets snap version', async () => {
-      const provider = await initProvider([...versionChecks, ...versionChecks.slice(2, 2)]);
+      const provider = await initProvider([...metamaskVersionCheck, ...snapVersionCheck]);
       const factory = new AccountMetamaskFactory(provider);
       expect(await factory.getSnapVersion()).to.equal('0.0.9');
     });
 
+    const requestSnaps = [
+      {
+        request: {
+          method: 'wallet_requestSnaps',
+          params: {
+            'npm:@aeternity-snap/plugin': {
+              version: '>=0.0.9 <0.1.0',
+            },
+          },
+        },
+      },
+      { resolve: { 'npm:@aeternity-snap/plugin': snapDetails } },
+    ];
+
     it('ensures that snap version is compatible', async () => {
       const provider = await initProvider(
         [
-          ...versionChecks.slice(0, 3),
-          { resolve: { 'npm:@aeternity-snap/plugin': { ...snapDetails, version: '1.0.0' } } },
+          ...metamaskVersionCheck,
+          requestSnaps[0],
+          {
+            reject: {
+              code: -32602,
+              message:
+                'Snap "npm:@aeternity-snap/plugin@<>" is already installed. Couldn\'t update to a version inside requested "<>" range.',
+            },
+          },
         ],
         true,
       );
       const factory = new AccountMetamaskFactory(provider);
       await expect(factory.initialize(42)).to.be.rejectedWith(
-        'Unsupported Aeternity snap in MetaMask version 1.0.0. Supported: >= 0.0.9 < 0.1.0',
+        'Snap "npm:@aeternity-snap/plugin@<>" is already installed. Couldn\'t update to a version inside requested "<>" range.',
       );
     });
 
@@ -165,7 +208,8 @@ describe('Aeternity Snap for MetaMask', function () {
 
     it('initializes an account', async () => {
       const provider = await initProvider([
-        ...versionChecks,
+        ...metamaskVersionCheck,
+        ...requestSnaps,
         getPublicKeyRequest,
         { resolve: { publicKey: 'ak_2HteeujaJzutKeFZiAmYTzcagSoRErSXpBFV179xYgqT4teakv' } },
       ]);
@@ -179,7 +223,8 @@ describe('Aeternity Snap for MetaMask', function () {
 
     it('initializes an account rejected', async () => {
       const provider = await initProvider([
-        ...versionChecks,
+        ...metamaskVersionCheck,
+        ...requestSnaps,
         getPublicKeyRequest,
         { reject: { code: 4001, message: 'User rejected the request.' } },
       ]);
