@msafe/sui3-sdk 0.0.2-pre-9f39791.0

package/src/backend/interface.ts

@@ -0,0 +1,57 @@
+import { PublicKey, SerializedSignature } from '@mysten/sui.js/cryptography';
+
+import { CreateMSafeParams, JWTToken, UserWithOwnedMSafe } from '@/backend/types';
+import { TxIntention } from '@/transactions/intention';
+import { FutureIntention, HistorySendTx, MSafeAccountInfo, PendingTx } from '@/types/msafe';
+
+export interface IBackend {
+  isJWTTokenValid(jwt: JWTToken): Promise<boolean>;
+  authSign(input: {
+    address: string;
+    message: string;
+    signature: SerializedSignature;
+    walletType: string;
+  }): Promise<JWTToken>;
+  setJWTToken(token: JWTToken): void;
+
+  getPublicKey(address: string): Promise<PublicKey | undefined>;
+  getPublicKeyBatch(addresses: string[]): Promise<(PublicKey | undefined)[]>;
+  getMSafeAccountInfo(msafeAddress: string): Promise<MSafeAccountInfo>;
+  getUserInfo(userAddress: string): Promise<UserWithOwnedMSafe>;
+  getPendingTransactions(msafeAddress: string): Promise<PendingTx[]>;
+  getHistoryTransactions(msafeAddress: string): Promise<HistorySendTx[]>;
+  getFutureIntentions(msafeAddress: string): Promise<FutureIntention[]>;
+  getCurrentSequenceNumber(msafeAddress: string): Promise<number>;
+  getNextSequenceNumber(msafeAddress: string): Promise<number>;
+
+  createMSafeAccount(input: CreateMSafeParams): Promise<void>;
+  proposeIntention(input: {
+    intention: TxIntention;
+    sequenceNumber: number;
+    userAddress: string;
+    msafeAddress: string;
+    signature: SerializedSignature;
+  }): Promise<void>;
+  proposePendingTransaction(input: {
+    intention: TxIntention;
+    userAddress: string;
+    msafeAddress: string;
+    digest: string;
+    signature: SerializedSignature;
+  }): Promise<void>;
+  rejectCurrentTx(input: {
+    userAddress: string;
+    msafeAddress: string;
+    digest: string;
+    signature: SerializedSignature;
+  }): Promise<void>;
+  voteForTransaction(input: {
+    txDigest: string;
+    msafeAddress: string;
+    userAddress: string;
+    signature: SerializedSignature;
+  }): Promise<void>;
+  buildNextIntentionAndAddToPending(input: { msafeAddress: string }): Promise<void>;
+  skipNextFailedIntention(input: { msafeAddress: string; userAddress: string }): Promise<void>;
+  processExecutedTransaction(digest: string): Promise<void>;
+}

package/src/backend/types.ts

@@ -0,0 +1,22 @@
+import { SerializedSignature } from '@mysten/sui.js/cryptography';
+
+import { MSafeAccountInfo, OwnerWithWeightPK } from '@/types/msafe';
+
+export type JWTToken = string;
+
+export interface CreateMSafeParams {
+  ownerWithWeight: OwnerWithWeightPK[];
+  threshold: number;
+  name: string;
+  description?: string;
+  creationNonce: number;
+  signature: SerializedSignature;
+}
+
+export interface UserWithOwnedMSafe {
+  address: string;
+  publicKey: string;
+  schema: string;
+  creationNonce: number;
+  ownedMSafe: MSafeAccountInfo[];
+}

package/src/core/CreateHelper.ts

@@ -0,0 +1,76 @@
+import { PublicKey, SerializedSignature } from '@mysten/sui.js/cryptography';
+
+import { MessageHelper } from '@/core/MessageHelper';
+import { PublicKeyHelper } from '@/core/PublicKeyHelper';
+import { MSafeGlobals } from '@/globals/MSafeGlobals';
+import { CreateMSafeAccountInfo, CreatePermissionInfo } from '@/types/creation';
+import { MultiSigConfig, RawMultiSig, validateMultiSigConfig } from '@/utils/multi-sig';
+
+export class CreateHelper {
+  constructor(
+    public readonly globals: MSafeGlobals,
+    public readonly pkHelper: PublicKeyHelper,
+  ) {}
+
+  async getPublicKeyBatch(addresses: string[]) {
+    return this.pkHelper.getPublicKeyBatch(addresses);
+  }
+
+  async calculateMSafeAddress(info: CreatePermissionInfo) {
+    const msConfig = await this.reduceCreationInfoToRawConfig(info);
+    const ms = new RawMultiSig(msConfig);
+    return ms.suiAddress;
+  }
+
+  // Validate the create info and return the msafe address.
+  async validateCreateInfo(createInfo: CreateMSafeAccountInfo) {
+    const rawConfig = await this.reduceCreationInfoToRawConfig(createInfo);
+    validateMultiSigConfig(rawConfig);
+
+    // Calculate the sui address will check the multi-sig
+    return this.calculateMSafeAddress(createInfo);
+  }
+
+  async submitMSafeCreation(creationInfo: CreateMSafeAccountInfo) {
+    const msafeAddress = await this.validateCreateInfo(creationInfo);
+
+    const signingMessage = MessageHelper.createMSafeMessage(msafeAddress);
+    const signature = await this.globals.wallet.signPersonalMessage({ messageStr: signingMessage });
+
+    await this.submitToBackend(creationInfo, signature.signature);
+    return msafeAddress;
+  }
+
+  private async reduceCreationInfoToRawConfig(info: CreatePermissionInfo): Promise<MultiSigConfig> {
+    const publicKeys = await this.getPublicKeyBatch(info.ownerWithWeight.map((oww) => oww.address));
+    publicKeys.forEach((pk, i) => {
+      if (pk === undefined) {
+        throw new Error(`Unknown public key for address: ${info.ownerWithWeight[i].address}`);
+      }
+    });
+    return {
+      threshold: info.threshold,
+      ownerWithWeight: info.ownerWithWeight.map((owner, i) => ({
+        publicKey: publicKeys[i] as PublicKey,
+        weight: owner.weight,
+      })),
+      creationNonce: info.creationNonce,
+    };
+  }
+
+  private async submitToBackend(createInfo: CreateMSafeAccountInfo, signature: SerializedSignature) {
+    const pks = await this.pkHelper.getPublicKeyBatch(createInfo.ownerWithWeight.map((owner) => owner.address));
+    await this.globals.backend.createMSafeAccount({
+      ownerWithWeight: createInfo.ownerWithWeight.map((owner, i) => ({
+        address: owner.address,
+        weight: owner.weight,
+        publicKey: pks[i] as PublicKey, // PublicKey has been verified.
+      })),
+      threshold: createInfo.threshold,
+      name: createInfo.name, // name validation is deferred to backend
+      description: createInfo.description, // description validation is deferred to backend
+      creationNonce: createInfo.creationNonce,
+      signature,
+    });
+  }
+}

package/src/core/MSafeAccount.ts

@@ -0,0 +1,167 @@
+import { SerializedSignature } from '@mysten/sui.js/cryptography';
+
+import { MessageHelper } from '@/core/MessageHelper';
+import { MSafeGlobals } from '@/globals/MSafeGlobals';
+import { IntentionHelper, TxIntention } from '@/transactions/intention';
+import { MSafeAccountInfo, PendingTx } from '@/types/msafe';
+import { HexToUint8Array } from '@/utils/buffer';
+import { RawMultiSig } from '@/utils/multi-sig';
+
+export class MSafeAccount {
+  public rawMultiSig: RawMultiSig;
+
+  constructor(
+    public readonly globals: MSafeGlobals,
+    public readonly info: MSafeAccountInfo,
+  ) {
+    this.rawMultiSig = RawMultiSig.fromMSafeAccountInfo(info);
+  }
+
+  static async new(globals: MSafeGlobals, address: string) {
+    const info = await globals.backend.getMSafeAccountInfo(address);
+    return new MSafeAccount(globals, info);
+  }
+
+  async pendingTransactions() {
+    return this.backend.getPendingTransactions(this.address);
+  }
+
+  async historyTransaction() {
+    return this.backend.getHistoryTransactions(this.address);
+  }
+
+  async futureIntentions() {
+    return this.backend.getFutureIntentions(this.address);
+  }
+
+  async currentSequenceNumber() {
+    return this.backend.getCurrentSequenceNumber(this.address);
+  }
+
+  async nextSequenceNumber() {
+    return this.backend.getNextSequenceNumber(this.address);
+  }
+
+  async proposeIntention(intention: TxIntention, sequenceNumber: number) {
+    const message = MessageHelper.proposeIntentionMessage({ intention, sn: sequenceNumber });
+    const signature = await this.wallet.signPersonalMessage({
+      messageStr: message,
+    });
+    await this.backend.proposeIntention({
+      intention,
+      sequenceNumber,
+      msafeAddress: this.address,
+      userAddress: await this.userAddress(),
+      signature: signature.signature,
+    });
+  }
+
+  async voteForTransaction(digest: string, payload: string) {
+    const payloadBytes = HexToUint8Array(payload);
+    const signature = await this.wallet.signTransactionBlock({ transactionBlock: payloadBytes });
+    return this.backend.voteForTransaction({
+      msafeAddress: this.address,
+      userAddress: await this.userAddress(),
+      txDigest: digest,
+      signature: signature.signature,
+    });
+  }
+
+  // Shortcut for proposing a transaction to be a pending transaction, and add user vote to it.
+  // Requires the multi-sig to be empty in pending transaction.
+  async proposePendingTransaction(intention: TxIntention) {
+    const txb = await IntentionHelper.buildTxb({
+      suiClient: this.suiClient,
+      intention,
+      sender: this.address,
+    });
+    const payload = await txb.build({ client: this.suiClient });
+    const digest = await txb.getDigest({ client: this.suiClient });
+    const signature = await this.wallet.signTransactionBlock({ transactionBlock: payload });
+    return this.backend.proposePendingTransaction({
+      msafeAddress: this.address,
+      userAddress: await this.userAddress(),
+      intention,
+      digest,
+      signature: signature.signature,
+    });
+  }
+
+  async rejectCurrentTx(pending?: PendingTx) {
+    let payloadToReject: string;
+    if (pending) {
+      if (pending.isRejectTx) {
+        throw new Error('Pending not reject transaction');
+      }
+      payloadToReject = pending.payload;
+    } else {
+      const pendings = await this.pendingTransactions();
+      if (pendings.length !== 1 || pendings[0].isRejectTx) {
+        throw new Error('Already rejected');
+      }
+      payloadToReject = pendings[0].payload;
+    }
+    const rejectTxb = await IntentionHelper.buildRejectTransaction({
+      msafeAddress: this.address,
+      payloadToReject,
+    });
+    const digest = await rejectTxb.getDigest({ client: this.suiClient });
+    const payload = await rejectTxb.build({ client: this.suiClient });
+    const signature = await this.wallet.signTransactionBlock({ transactionBlock: payload });
+    return this.backend.rejectCurrentTx({
+      msafeAddress: this.address,
+      userAddress: await this.userAddress(),
+      digest,
+      signature: signature.signature,
+    });
+  }
+
+  async buildNextIntentionAndAddToPending() {
+    return this.backend.buildNextIntentionAndAddToPending({ msafeAddress: this.address });
+  }
+
+  async skipNextFailedIntention() {
+    return this.backend.skipNextFailedIntention({ msafeAddress: this.address, userAddress: await this.userAddress() });
+  }
+
+  async executePendingTx(pending: PendingTx) {
+    if (pending.votes.length < this.info.threshold) {
+      throw new Error('Not enough signatures');
+    }
+    const sigs: SerializedSignature[] = [];
+    const gotSigs = new Map(pending.votes.map((vote) => [vote.userAddress, vote.signature]));
+    for (let i = 0; i < this.info.ownersWithWeightPK.length; i++) {
+      const owner = this.info.ownersWithWeightPK[i];
+      const signature = gotSigs.get(owner.publicKey.toSuiAddress());
+      if (signature) {
+        sigs.push(signature);
+      }
+    }
+    const multiSignature = this.rawMultiSig.combinePartialSignatures(sigs);
+    return this.suiClient.executeTransactionBlock({
+      transactionBlock: HexToUint8Array(pending.payload),
+      signature: multiSignature,
+      options: { showEffects: true },
+    });
+  }
+
+  get address() {
+    return this.info.address;
+  }
+
+  private get backend() {
+    return this.globals.backend;
+  }
+
+  private get wallet() {
+    return this.globals.wallet;
+  }
+
+  private async userAddress() {
+    return this.globals.wallet.address();
+  }
+
+  private get suiClient() {
+    return this.globals.suiClient;
+  }
+}

package/src/core/MSafeClient.ts

@@ -0,0 +1,91 @@
+import { JWTToken } from '@/backend/types';
+import { CreateHelper } from '@/core/CreateHelper';
+import { MessageHelper } from '@/core/MessageHelper';
+import { MSafeAccount } from '@/core/MSafeAccount';
+import { PublicKeyHelper } from '@/core/PublicKeyHelper';
+import { MSafeConfigOptions, MSafeEnv } from '@/globals/const';
+import { MSafeGlobals } from '@/globals/MSafeGlobals';
+import { CreateMSafeAccountInfo } from '@/types/creation';
+import { MSafeAccountInfo } from '@/types/msafe';
+import { IWallet } from '@/types/wallet';
+
+export class MSafeClient {
+  private _creationHelper: CreateHelper | undefined;
+
+  private _publicKeyHelper: PublicKeyHelper | undefined;
+
+  constructor(public readonly globals: MSafeGlobals) {}
+
+  static async New(env: MSafeEnv, options?: MSafeConfigOptions) {
+    const globals = await MSafeGlobals.New(env, options);
+    return new MSafeClient(globals);
+  }
+
+  async connectWallet(input: { wallet: IWallet; jwtToken?: JWTToken }): Promise<JWTToken> {
+    this.globals.wallet = input.wallet;
+    const isValidJWT = input.jwtToken && (await this.backend.isJWTTokenValid(input.jwtToken));
+    if (isValidJWT) {
+      this.backend.setJWTToken(input.jwtToken as JWTToken);
+      return input.jwtToken as JWTToken;
+    }
+    const messageStr = MessageHelper.welcomeMessage(new Date().toUTCString());
+    const sig = await input.wallet.signPersonalMessage({
+      messageStr,
+    });
+    return this.backend.authSign({
+      address: await input.wallet.address(),
+      message: messageStr,
+      signature: sig.signature,
+      walletType: input.wallet.walletType,
+    });
+  }
+
+  async userInfo() {
+    return this.globals.backend.getUserInfo(await this.walletAddress());
+  }
+
+  async createAccount(info: CreateMSafeAccountInfo) {
+    return this.creationHelper.submitMSafeCreation(info);
+  }
+
+  getMSafeAccount(info: MSafeAccountInfo) {
+    return new MSafeAccount(this.globals, info);
+  }
+
+  async getMSafeAccountFromAddress(msafeAddress: string) {
+    const info = await this.backend.getMSafeAccountInfo(msafeAddress);
+    return new MSafeAccount(this.globals, info);
+  }
+
+  // Get the creation helper to calculate the msafe account address,
+  // validation, and more.
+  get creationHelper() {
+    if (!this._creationHelper) {
+      this._creationHelper = new CreateHelper(this.globals, this.publicKeyHelper);
+    }
+    return this._creationHelper;
+  }
+
+  get publicKeyHelper() {
+    if (!this._publicKeyHelper) {
+      this._publicKeyHelper = new PublicKeyHelper(this.globals);
+    }
+    return this._publicKeyHelper;
+  }
+
+  get config() {
+    return this.globals.config;
+  }
+
+  get backend() {
+    return this.globals.backend;
+  }
+
+  get wallet() {
+    return this.globals.wallet;
+  }
+
+  private async walletAddress() {
+    return this.wallet.address();
+  }
+}

package/src/core/MessageHelper.ts

@@ -0,0 +1,63 @@
+import { IntentionHelper, TxIntention } from '@/transactions/intention';
+
+export class MessageHelper {
+  // Message used for MSafe creation
+  static createMSafeMessage(msafeAddress: string): string {
+    return `Create MSafe Account: ${msafeAddress}`;
+  }
+
+  static deCreateMSafeMessage(msg: string) {
+    const regex = /Create MSafe Account: (.+)/;
+    const matches = msg.match(regex);
+    return matches ? matches[1] : undefined;
+  }
+
+  // Message to be used when user login. The timestamp string
+  // is used to for extra validation.
+  static welcomeMessage(timestamp: string): string {
+    return `Welcome to MSafe. ${timestamp}`;
+  }
+
+  static deWelcomeMessage(msg: string): string | undefined {
+    const regex = /Welcome to MSafe. (.+)/;
+    const matches = msg.match(regex);
+    return matches ? matches[1] : undefined;
+  }
+
+  static proposeIntentionMessage(data: ProposeIntentionData) {
+    const { intention, sn } = data;
+    const intentionData = IntentionHelper.ser(intention);
+    const msg: ProposeIntentionMessage = {
+      intentionData,
+      sequenceNumber: sn,
+    };
+    return JSON.stringify(msg);
+  }
+
+  static deProposeIntentionMessage(s: string): ProposeIntentionData {
+    const de = JSON.parse(s);
+    if (
+      !('intentionData' in de) ||
+      typeof de.intentionData !== 'string' ||
+      !('sequenceNumber' in de) ||
+      typeof de.sequenceNumber !== 'number'
+    ) {
+      throw new Error('Invalid intention data');
+    }
+    const { sequenceNumber, intentionData } = de;
+    return {
+      sn: sequenceNumber,
+      intention: IntentionHelper.de(intentionData),
+    };
+  }
+}
+
+export interface ProposeIntentionData {
+  intention: TxIntention;
+  sn: number;
+}
+
+export interface ProposeIntentionMessage {
+  intentionData: string;
+  sequenceNumber: number;
+}

package/src/core/PublicKeyHelper.ts

@@ -0,0 +1,88 @@
+import { PublicKey } from '@mysten/sui.js/src/cryptography';
+
+import { MSafeGlobals } from '@/globals/MSafeGlobals';
+import { getPublicKeyFromChain } from '@/utils/sui';
+
+/**
+ * PublicKeyHelper is the helper to query for public keys from
+ * backend and blockchain.
+ */
+export class PublicKeyHelper {
+  private knownPublicKeys: Map<string, PublicKey>;
+
+  constructor(public readonly globals: MSafeGlobals) {
+    this.knownPublicKeys = new Map<string, PublicKey>();
+  }
+
+  async getPublicKey(address: string) {
+    const cached = this.knownPublicKeys.get(address);
+    if (cached) {
+      return cached;
+    }
+    const pk = await this._getPublicKey(address);
+    if (pk) {
+      this.knownPublicKeys.set(address, pk);
+    }
+    return pk;
+  }
+
+  async getPublicKeyBatch(addresses: string[]): Promise<(PublicKey | undefined)[]> {
+    const results: (PublicKey | undefined)[] = new Array(addresses.length).fill(undefined);
+
+    // Query local cache first
+    for (let i = 0; i < addresses.length; i++) {
+      const address = addresses[i];
+      results[i] = this.knownPublicKeys.get(address);
+    }
+
+    // Query backend in batch
+    const emptyIndexes = results
+      .map((elem, index) => (elem === undefined ? index : -1))
+      .filter((index) => index !== -1);
+    const backendResult = await this.globals.backend.getPublicKeyBatch(emptyIndexes.map((index) => addresses[index]));
+    for (let i = 0; i < emptyIndexes.length; i++) {
+      const index = emptyIndexes[i];
+      results[index] = backendResult[i];
+    }
+
+    // Query the public key from blockchain
+    for (let i = 0; i < results.length; i++) {
+      if (results[i] === undefined) {
+        results[i] = await this.getPublicKeyFromChain(addresses[i]);
+      }
+    }
+
+    // Finally, write the public keys to the local cache
+    for (let i = 0; i < addresses.length; i++) {
+      if (results[i]) {
+        this.knownPublicKeys.set(addresses[i], results[i] as PublicKey);
+      }
+    }
+    return results;
+  }
+
+  private async _getPublicKey(address: string) {
+    const pkBackend = await this.getPublicKeyFromBackend(address);
+    if (pkBackend) {
+      return pkBackend;
+    }
+    const pkChain = await this.getPublicKeyFromChain(address);
+    if (pkChain) {
+      return pkChain;
+    }
+    return undefined;
+  }
+
+  private async getPublicKeyFromBackend(address: string): Promise<PublicKey | undefined> {
+    try {
+      const pk = await this.globals.backend.getPublicKey(address);
+      return pk;
+    } catch (_) {
+      return undefined;
+    }
+  }
+
+  private async getPublicKeyFromChain(address: string): Promise<PublicKey | undefined> {
+    return getPublicKeyFromChain(this.globals.suiClient, address);
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,4 @@
+export { CreateHelper } from './CreateHelper';
+export { MessageHelper } from './MessageHelper';
+export { MSafeClient } from './MSafeClient';
+export { MSafeAccount } from './MSafeAccount';

package/src/globals/MSafeGlobals.ts

@@ -0,0 +1,48 @@
+import { SuiClient } from '@mysten/sui.js/client';
+
+import { IBackend } from '@/backend/interface';
+import { PseudoBackend } from '@/backend/PseudoBackend';
+import { getMSafeConfig, MSafeConfig, MSafeConfigOptions, MSafeEnv } from '@/globals/const';
+import { IWallet } from '@/types/wallet';
+
+export class MSafeGlobals {
+  public readonly backend: IBackend;
+
+  public readonly suiClient: SuiClient;
+
+  public readonly config: MSafeConfig;
+
+  _wallet: IWallet | undefined;
+
+  constructor(input: { backend: IBackend; suiClient: SuiClient; config: MSafeConfig }) {
+    this.backend = input.backend;
+    this.suiClient = input.suiClient;
+    this.config = input.config;
+  }
+
+  static async New(env: MSafeEnv, options?: MSafeConfigOptions) {
+    const config = getMSafeConfig(env, options);
+    const suiClient = new SuiClient(config.suiClient);
+    const backend = await PseudoBackend.New(config.backend, suiClient);
+    return new MSafeGlobals({
+      backend,
+      suiClient,
+      config,
+    });
+  }
+
+  connectWallet(wallet: IWallet) {
+    this._wallet = wallet;
+  }
+
+  get wallet() {
+    if (!this._wallet) {
+      throw new Error('wallet not connected');
+    }
+    return this._wallet;
+  }
+
+  set wallet(val: IWallet) {
+    this._wallet = val;
+  }
+}