CORE-2034 add register and complete withdraw workflow

CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+
+## [3.5.0] - 2024-02-28
+
+### Added
+
+- Update `completeWithdrawal`:
+  - If the user has only v4 balance, `completeWithdrawal` will withdraw v4 balance.
+  - If the user has v3 balance, `completeWithdrawal` will try to withdraw both v3 and v4 balance.
+  - If the user has v3 balance, and is not registered on-chain, `completeWithdrawal` will try to register the user and then withdraw both v3 and v4 balance.
+  - If the v3 balance is not zero for an NFT, `completeWithdrawal` will only try to withdraw v3 balance.
+- v3 balance refers to withdrawal prepared using /v1/withdrawal API.
+- v4 balance refers to withdrawal prepared using /v2/withdrawal API.
+
 ## [3.4.0] - 2024-02-27
 
 ### Added

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imtbl/core-sdk",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "description": "Immutable Core SDK",
   "main": "dist/index.cjs.js",
   "module": "dist/index.es.js",

src/workflows/withdrawal/completeERC20Withdrawal.ts

@@ -10,10 +10,11 @@ import {
   Registration__factory,
   RegistrationV4__factory,
 } from '../../contracts';
-import { ERC20Token } from '../../types';
+import { ERC20Token, WalletConnection } from '../../types';
 import {
   getSignableRegistrationOnchain,
   isRegisteredOnChainWorkflow,
+  signRegisterEthAddress,
 } from '../registration';
 import { getEncodeAssetInfo } from './getEncodeAssetInfo';
 
@@ -153,3 +154,37 @@ export async function completeAllERC20WithdrawalWorkflow(
 
   return signer.sendTransaction(populatedTransaction);
 }
+
+export async function registerAndCompleteAllERC20WithdrawalWorkflow(
+  walletConnection: WalletConnection,
+  ethAddress: string,
+  starkPublicKey: string,
+  token: ERC20Token,
+  encodingApi: EncodingApi,
+  config: ImmutableXConfiguration,
+): Promise<TransactionResponse> {
+  const assetType = await getEncodeAssetInfo('asset', 'ERC20', encodingApi, {
+    token_address: token.tokenAddress,
+  });
+
+  const registrationContract = RegistrationV4__factory.connect(
+    config.ethConfiguration.registrationContractAddress,
+    walletConnection.ethSigner,
+  );
+
+  const starkSignature = await signRegisterEthAddress(
+    walletConnection.starkSigner,
+    ethAddress,
+    starkPublicKey,
+  );
+
+  const populatedTransaction =
+    await registrationContract.populateTransaction.registerAndWithdrawAll(
+      ethAddress,
+      starkPublicKey,
+      starkSignature,
+      assetType.asset_id,
+    );
+
+  return walletConnection.ethSigner.sendTransaction(populatedTransaction);
+}

src/workflows/withdrawal/completeERC721Withdrawal.ts

@@ -3,16 +3,18 @@ import { EncodingApi, MintsApi, UsersApi } from '../../api';
 import {
   Core,
   Core__factory,
+  CoreV4__factory,
   Registration,
   Registration__factory,
-  CoreV4__factory,
+  RegistrationV4__factory,
 } from '../../contracts';
 import * as encUtils from 'enc-utils';
-import { ERC721Token } from '../../types';
+import { ERC721Token, WalletConnection } from '../../types';
 import { getEncodeAssetInfo } from './getEncodeAssetInfo';
 import {
   getSignableRegistrationOnchain,
   isRegisteredOnChainWorkflow,
+  signRegisterEthAddress,
 } from '../registration';
 import { TransactionResponse } from '@ethersproject/providers';
 import { ImmutableXConfiguration } from '../../config';
@@ -330,6 +332,72 @@ async function completeERC721WithdrawalV2(
   return signer.sendTransaction(populatedTransaction);
 }
 
+async function registerAndCompleteMintableERC721WithdrawalV2(
+  signer: Signer,
+  ethAddress: string,
+  starkPublicKey: string,
+  starkSignature: string,
+  token: MintableERC721Withdrawal,
+  encodingApi: EncodingApi,
+  config: ImmutableXConfiguration,
+) {
+  const assetType = await getEncodeAssetInfo(
+    'mintable-asset',
+    'ERC721',
+    encodingApi,
+    {
+      id: token.data.id,
+      token_address: token.data.tokenAddress,
+      ...(token.data.blueprint && { blueprint: token.data.blueprint }),
+    },
+  );
+  const mintingBlob = getMintingBlob(token);
+  const contract = RegistrationV4__factory.connect(
+    config.ethConfiguration.registrationContractAddress,
+    signer,
+  );
+
+  const populatedTransaction =
+    await contract.populateTransaction.registerWithdrawAndMint(
+      ethAddress,
+      starkPublicKey,
+      starkSignature,
+      assetType.asset_type,
+      mintingBlob,
+    );
+  return signer.sendTransaction(populatedTransaction);
+}
+
+async function registerAndCompleteERC721WithdrawalV2(
+  signer: Signer,
+  ethAddress: string,
+  starkPublicKey: string,
+  starkSignature: string,
+  token: ERC721Token,
+  encodingApi: EncodingApi,
+  config: ImmutableXConfiguration,
+) {
+  const assetType = await getEncodeAssetInfo('asset', 'ERC721', encodingApi, {
+    token_id: token.tokenId,
+    token_address: token.tokenAddress,
+  });
+
+  const contract = RegistrationV4__factory.connect(
+    config.ethConfiguration.registrationContractAddress,
+    signer,
+  );
+
+  const populatedTransaction =
+    await contract.populateTransaction.registerAndWithdrawNft(
+      ethAddress,
+      starkPublicKey,
+      starkSignature,
+      assetType.asset_type,
+      token.tokenId,
+    );
+  return signer.sendTransaction(populatedTransaction);
+}
+
 export async function completeERC721WithdrawalV2Workflow(
   signer: Signer,
   ownerKey: string,
@@ -375,3 +443,60 @@ export async function completeERC721WithdrawalV2Workflow(
       throw error; // unable to recover from any other kind of error
     });
 }
+
+export async function registerAndCompleteERC721WithdrawalWorkflow(
+  walletConnection: WalletConnection,
+  ethAddress: string,
+  starkPublicKey: string,
+  token: ERC721Token,
+  encodingApi: EncodingApi,
+  mintsApi: MintsApi,
+  config: ImmutableXConfiguration,
+): Promise<TransactionResponse> {
+  const starkSignature = await signRegisterEthAddress(
+    walletConnection.starkSigner,
+    ethAddress,
+    starkPublicKey,
+  );
+  const tokenAddress = token.tokenAddress;
+  const tokenId = token.tokenId;
+
+  return await mintsApi
+    .getMintableTokenDetailsByClientTokenId({
+      tokenAddress,
+      tokenId,
+    })
+    .then(async mintableToken =>
+      registerAndCompleteMintableERC721WithdrawalV2(
+        walletConnection.ethSigner,
+        ethAddress,
+        starkPublicKey,
+        starkSignature,
+        {
+          type: 'ERC721',
+          data: {
+            id: tokenId,
+            tokenAddress: tokenAddress,
+            blueprint: mintableToken.data.blueprint,
+          },
+        },
+        encodingApi,
+        config,
+      ),
+    )
+    .catch(error => {
+      if (error.response?.status === 404) {
+        // token is already minted on L1
+        return registerAndCompleteERC721WithdrawalV2(
+          walletConnection.ethSigner,
+          ethAddress,
+          starkPublicKey,
+          starkSignature,
+          token,
+          encodingApi,
+          config,
+        );
+      }
+      throw error; // unable to recover from any other kind of error
+    });
+}

src/workflows/withdrawal/completeEthWithdrawal.ts

@@ -13,8 +13,10 @@ import {
 import {
   getSignableRegistrationOnchain,
   isRegisteredOnChainWorkflow,
+  signRegisterEthAddress,
 } from '../registration';
 import { getEncodeAssetInfo } from './getEncodeAssetInfo';
+import { WalletConnection } from 'src/types';
 
 async function executeRegisterAndWithdrawEth(
   signer: Signer,
@@ -143,3 +145,34 @@ export async function completeAllEthWithdrawalWorkflow(
 
   return signer.sendTransaction(populatedTransaction);
 }
+
+export async function registerAndCompleteAllEthWithdrawalWorkflow(
+  walletConnection: WalletConnection,
+  ethAddress: string,
+  starkPublicKey: string,
+  encodingApi: EncodingApi,
+  config: ImmutableXConfiguration,
+): Promise<TransactionResponse> {
+  const assetType = await getEncodeAssetInfo('asset', 'ETH', encodingApi);
+
+  const registrationContract = RegistrationV4__factory.connect(
+    config.ethConfiguration.registrationContractAddress,
+    walletConnection.ethSigner,
+  );
+
+  const starkSignature = await signRegisterEthAddress(
+    walletConnection.starkSigner,
+    ethAddress,
+    starkPublicKey,
+  );
+
+  const populatedTransaction =
+    await registrationContract.populateTransaction.registerAndWithdrawAll(
+      ethAddress,
+      starkPublicKey,
+      starkSignature,
+      assetType.asset_id,
+    );
+
+  return walletConnection.ethSigner.sendTransaction(populatedTransaction);
+}

src/workflows/withdrawal/completeWithdrawal.ts

@@ -1,21 +1,24 @@
 import { Signer } from '@ethersproject/abstract-signer';
 import { TransactionResponse } from '@ethersproject/providers';
-import { AnyToken } from 'src/types';
+import { AnyToken, WalletConnection } from 'src/types';
 import { EncodingApi, MintsApi, UsersApi } from 'src/api';
 import { ImmutableXConfiguration } from 'src/config';
 import {
   completeAllEthWithdrawalWorkflow,
   completeEthWithdrawalV1Workflow,
   completeEthWithdrawalV2Workflow,
+  registerAndCompleteAllEthWithdrawalWorkflow,
 } from './completeEthWithdrawal';
 import {
   completeAllERC20WithdrawalWorkflow,
   completeERC20WithdrawalV1Workflow,
   completeERC20WithdrawalV2Workflow,
+  registerAndCompleteAllERC20WithdrawalWorkflow,
 } from './completeERC20Withdrawal';
 import {
   completeERC721WithdrawalV1Workflow,
   completeERC721WithdrawalV2Workflow,
+  registerAndCompleteERC721WithdrawalWorkflow,
 } from './completeERC721Withdrawal';
 
 export async function completeWithdrawalV1Workflow(
@@ -124,3 +127,44 @@ export async function completeAllWithdrawalWorkflow(
       );
   }
 }
+
+export async function registerAndCompleteAllWithdrawalWorkflow(
+  walletConnection: WalletConnection,
+  ethAddress: string,
+  starkPublicKey: string,
+  token: AnyToken,
+  encodingApi: EncodingApi,
+  mintsApi: MintsApi,
+  config: ImmutableXConfiguration,
+): Promise<TransactionResponse> {
+  switch (token.type) {
+    case 'ETH':
+      return registerAndCompleteAllEthWithdrawalWorkflow(
+        walletConnection,
+        ethAddress,
+        starkPublicKey,
+        encodingApi,
+        config,
+      );
+    case 'ERC20':
+      return registerAndCompleteAllERC20WithdrawalWorkflow(
+        walletConnection,
+        ethAddress,
+        starkPublicKey,
+        token,
+        encodingApi,
+        config,
+      );
+    case 'ERC721':
+      // for ERC721, if the v3 balance > 0, then the v4 balance is 0
+      return registerAndCompleteERC721WithdrawalWorkflow(
+        walletConnection,
+        ethAddress,
+        starkPublicKey,
+        token,
+        encodingApi,
+        mintsApi,
+        config,
+      );
+  }
+}

src/workflows/withdrawal/index.ts

@@ -1,4 +1,6 @@
 export * from './prepareWithdrawal';
+export * from './completeWithdrawal';
 export * from './completeERC20Withdrawal';
 export * from './completeERC721Withdrawal';
 export * from './completeEthWithdrawal';
+export * from './getWithdrawalBalance';

src/workflows/workflows.ts

@@ -72,6 +72,7 @@ import {
   completeAllWithdrawalWorkflow,
   completeWithdrawalV1Workflow,
   completeWithdrawalV2Workflow,
+  registerAndCompleteAllWithdrawalWorkflow,
 } from './withdrawal/completeWithdrawal';
 import { BigNumber } from 'ethers';
 import { getWithdrawalBalanceWorkflow } from './withdrawal/getWithdrawalBalance';
@@ -311,7 +312,6 @@ export class Workflows {
     const starkPublicKey = await walletConnection.starkSigner.getAddress();
 
     if (majorContractVersion === 3) {
-      const starkPublicKey = await walletConnection.starkSigner.getAddress();
       return completeWithdrawalV1Workflow(
         walletConnection.ethSigner,
         starkPublicKey,
@@ -359,7 +359,15 @@ export class Workflows {
           this.config,
         );
       }
-      throw new Error('User unregistered');
+      return registerAndCompleteAllWithdrawalWorkflow(
+        walletConnection,
+        ethAddress,
+        starkPublicKey,
+        token,
+        this.encodingApi,
+        this.mintsApi,
+        this.config,
+      );
     }
     if (v4Balance.gt(0)) {
       return completeWithdrawalV2Workflow(