@chipi-stack/chipi-react 14.9.0 → 14.10.0

package/dist/index.js

@@ -10736,6 +10736,7 @@ var OutsideExecutionTypesV2 = {
   ]
 };
 var OutsideExecutionVersion = {
+  UNSUPPORTED: "0",
   V1: "1",
   V2: "2"
 };
@@ -18627,9 +18628,76 @@ var BrotherId = class _BrotherId {
     }
   }
 };
-(class extends Mixin(RpcProvider, StarknetId, BrotherId) {
-});
+var RpcProvider2 = class extends Mixin(RpcProvider, StarknetId, BrotherId) {
+};
 new RpcProvider({ default: true });
+var Signer = class {
+  constructor(pk = utils.randomPrivateKey()) {
+    __publicField(this, "pk");
+    this.pk = pk instanceof Uint8Array ? buf2hex(pk) : toHex(pk);
+  }
+  async getPubKey() {
+    return getStarkKey(this.pk);
+  }
+  async signMessage(typedData, accountAddress) {
+    const msgHash = getMessageHash(typedData, accountAddress);
+    return this.signRaw(msgHash);
+  }
+  async signTransaction(transactions, details) {
+    const compiledCalldata = getExecuteCalldata(transactions, details.cairoVersion);
+    let msgHash;
+    if (Object.values(api_exports3.ETransactionVersion3).includes(details.version)) {
+      const det = details;
+      msgHash = calculateInvokeTransactionHash2({
+        ...det,
+        senderAddress: det.walletAddress,
+        compiledCalldata,
+        version: det.version,
+        nonceDataAvailabilityMode: intDAM(det.nonceDataAvailabilityMode),
+        feeDataAvailabilityMode: intDAM(det.feeDataAvailabilityMode)
+      });
+    } else {
+      throw Error("unsupported signTransaction version");
+    }
+    return this.signRaw(msgHash);
+  }
+  async signDeployAccountTransaction(details) {
+    const compiledConstructorCalldata = CallData.compile(details.constructorCalldata);
+    let msgHash;
+    if (Object.values(api_exports3.ETransactionVersion3).includes(details.version)) {
+      const det = details;
+      msgHash = calculateDeployAccountTransactionHash3({
+        ...det,
+        salt: det.addressSalt,
+        compiledConstructorCalldata,
+        version: det.version,
+        nonceDataAvailabilityMode: intDAM(det.nonceDataAvailabilityMode),
+        feeDataAvailabilityMode: intDAM(det.feeDataAvailabilityMode)
+      });
+    } else {
+      throw Error("unsupported signDeployAccountTransaction version");
+    }
+    return this.signRaw(msgHash);
+  }
+  async signDeclareTransaction(details) {
+    let msgHash;
+    if (Object.values(api_exports3.ETransactionVersion3).includes(details.version)) {
+      const det = details;
+      msgHash = calculateDeclareTransactionHash3({
+        ...det,
+        version: det.version,
+        nonceDataAvailabilityMode: intDAM(det.nonceDataAvailabilityMode),
+        feeDataAvailabilityMode: intDAM(det.feeDataAvailabilityMode)
+      });
+    } else {
+      throw Error("unsupported signDeclareTransaction version");
+    }
+    return this.signRaw(msgHash);
+  }
+  async signRaw(msgHash) {
+    return sign(msgHash, this.pk);
+  }
+};
 var uint256_exports = {};
 __export2(uint256_exports, {
   bnToUint256: () => bnToUint256,
@@ -19074,7 +19142,7 @@ var PaymasterRpc = class _PaymasterRpc {
     );
   }
 };
-new PaymasterRpc({ default: true });
+var defaultPaymaster = new PaymasterRpc({ default: true });
 var Deployer = class {
   constructor(address, entryPoint) {
     __publicField(this, "address");
@@ -19149,8 +19217,791 @@ var Deployer = class {
     };
   }
 };
-new Deployer(UDC.ADDRESS, UDC.ENTRYPOINT);
+var defaultDeployer = new Deployer(UDC.ADDRESS, UDC.ENTRYPOINT);
 new Deployer(LegacyUDC.ADDRESS, LegacyUDC.ENTRYPOINT);
+var Account = class extends RpcProvider2 {
+  constructor(options) {
+    const {
+      provider,
+      address,
+      signer,
+      cairoVersion,
+      transactionVersion,
+      paymaster,
+      defaultTipType
+    } = options;
+    super(provider);
+    __publicField(this, "signer");
+    __publicField(this, "address");
+    __publicField(this, "cairoVersion");
+    __publicField(this, "transactionVersion");
+    __publicField(this, "paymaster");
+    __publicField(this, "deployer");
+    __publicField(this, "defaultTipType");
+    __publicField(this, "deploySelf", this.deployAccount);
+    this.address = address.toLowerCase();
+    this.signer = isString(signer) || signer instanceof Uint8Array ? new Signer(signer) : signer;
+    if (cairoVersion) {
+      this.cairoVersion = cairoVersion.toString();
+    }
+    this.transactionVersion = transactionVersion ?? config2.get("transactionVersion");
+    this.paymaster = paymaster ? new PaymasterRpc(paymaster) : defaultPaymaster;
+    this.deployer = options.deployer ?? defaultDeployer;
+    this.defaultTipType = defaultTipType ?? config2.get("defaultTipType");
+    logger.debug("Account setup", {
+      transactionVersion: this.transactionVersion,
+      cairoVersion: this.cairoVersion,
+      channel: this.channel.id
+    });
+  }
+  /** @deprecated @hidden */
+  // The deprecation tag is meant to discourage use, not to signal future removal
+  // it should only be removed if the relationship with the corresponding Provider.create(...) method changes
+  static async create() {
+    throw new LibraryError("Not supported");
+  }
+  async getNonce(blockIdentifier) {
+    return super.getNonceForAddress(this.address, blockIdentifier);
+  }
+  async getNonceSafe(nonce) {
+    try {
+      return toBigInt(nonce ?? await this.getNonce());
+    } catch (error) {
+      return 0n;
+    }
+  }
+  /**
+   * Retrieves the Cairo version from the network and sets `cairoVersion` if not already set in the constructor.
+   * @param classHash if provided detects Cairo version from classHash, otherwise from the account address
+   */
+  async getCairoVersion(classHash) {
+    if (!this.cairoVersion) {
+      const { cairo } = classHash ? await super.getContractVersion(void 0, classHash) : await super.getContractVersion(this.address);
+      this.cairoVersion = cairo;
+    }
+    return this.cairoVersion;
+  }
+  // TODO: TT Cairo version is still needed for invoke on existing contracts
+  async estimateInvokeFee(calls, details = {}) {
+    const invocations = [{ type: api_exports3.ETransactionType.INVOKE, payload: [calls].flat() }];
+    const estimateBulk = await this.estimateFeeBulk(invocations, details);
+    return estimateBulk[0];
+  }
+  async estimateDeclareFee(payload, details = {}) {
+    assert(
+      isSierra(payload.contract),
+      "Declare fee estimation is not supported for Cairo0 contracts"
+    );
+    const invocations = [
+      {
+        type: api_exports3.ETransactionType.DECLARE,
+        payload: extractContractHashes(payload, await this.channel.getStarknetVersion())
+      }
+    ];
+    const estimateBulk = await this.estimateFeeBulk(invocations, details);
+    return estimateBulk[0];
+  }
+  async estimateAccountDeployFee({
+    classHash,
+    addressSalt = 0,
+    constructorCalldata = [],
+    contractAddress
+  }, details = {}) {
+    const compiledCalldata = CallData.compile(constructorCalldata);
+    const contractAddressFinal = contractAddress ?? calculateContractAddressFromHash(addressSalt, classHash, compiledCalldata, 0);
+    const invocations = [
+      {
+        type: api_exports3.ETransactionType.DEPLOY_ACCOUNT,
+        payload: {
+          classHash,
+          constructorCalldata: compiledCalldata,
+          addressSalt,
+          contractAddress: contractAddressFinal
+        }
+      }
+    ];
+    const estimateBulk = await this.estimateFeeBulk(invocations, details);
+    return estimateBulk[0];
+  }
+  async estimateDeployFee(payload, details = {}) {
+    const { calls } = this.deployer.buildDeployerCall(payload, this.address);
+    return this.estimateInvokeFee(calls, details);
+  }
+  async estimateFeeBulk(invocations, details = {}) {
+    if (!invocations.length) throw TypeError("Invocations should be non-empty array");
+    if (details.resourceBounds)
+      return [resourceBoundsToEstimateFeeResponse(details.resourceBounds)];
+    const { nonce, blockIdentifier, version, skipValidate } = details;
+    const detailsWithTip = await this.resolveDetailsWithTip(details);
+    const accountInvocations = await this.accountInvocationsFactory(invocations, {
+      ...v3Details(detailsWithTip),
+      versions: [
+        toTransactionVersion(
+          toFeeVersion(this.transactionVersion) || ETransactionVersion33.F3,
+          version
+        )
+        // sierra
+      ],
+      nonce,
+      blockIdentifier,
+      skipValidate
+    });
+    return super.getEstimateFeeBulk(accountInvocations, {
+      blockIdentifier,
+      skipValidate
+    });
+  }
+  async simulateTransaction(invocations, details = {}) {
+    if (!invocations.length) throw TypeError("Invocations should be non-empty array");
+    const {
+      nonce,
+      blockIdentifier,
+      skipValidate = true,
+      skipExecute,
+      version: providedVersion
+    } = details;
+    const detailsWithTip = await this.resolveDetailsWithTip(details);
+    const accountInvocations = await this.accountInvocationsFactory(invocations, {
+      ...v3Details(detailsWithTip),
+      versions: [this.resolveTransactionVersion(providedVersion)],
+      nonce,
+      blockIdentifier,
+      skipValidate
+    });
+    return super.getSimulateTransaction(accountInvocations, {
+      blockIdentifier,
+      skipValidate,
+      skipExecute
+    });
+  }
+  async execute(transactions, transactionsDetail = {}) {
+    const calls = [transactions].flat();
+    const detailsWithTip = await this.resolveDetailsWithTip(transactionsDetail);
+    const { resourceBounds: providedResourceBounds } = transactionsDetail;
+    let resourceBounds = providedResourceBounds;
+    if (!resourceBounds) {
+      const estimateResponse = await this.estimateInvokeFee(calls, detailsWithTip);
+      resourceBounds = estimateResponse.resourceBounds;
+    }
+    const accountInvocations = await this.accountInvocationsFactory(
+      [{ type: api_exports3.ETransactionType.INVOKE, payload: calls }],
+      {
+        ...v3Details(detailsWithTip),
+        resourceBounds,
+        versions: [this.resolveTransactionVersion(transactionsDetail.version)],
+        nonce: transactionsDetail.nonce,
+        skipValidate: false
+      }
+    );
+    const invocation = accountInvocations[0];
+    return this.invokeFunction(
+      {
+        contractAddress: invocation.contractAddress,
+        calldata: invocation.calldata,
+        signature: invocation.signature
+      },
+      {
+        ...v3Details(detailsWithTip),
+        resourceBounds: invocation.resourceBounds,
+        nonce: invocation.nonce,
+        version: invocation.version
+      }
+    );
+  }
+  /**
+   * Execute one or multiple calls through the account contract,
+   * responding as soon as a new transaction is possible with the same account.
+   * Useful for gaming usage.
+   * - This method requires the provider to be initialized with `pre_confirmed` blockIdentifier option.
+   * - Rpc 0.9 minimum.
+   * - In a normal myAccount.execute() call, followed by myProvider.waitForTransaction(), you have an immediate access to the events and to the transaction report. Here, we are processing consecutive transactions faster, but events & transaction reports are not available immediately.
+   * - As a consequence of the previous point, do not use contract/account deployment with this method.
+   * @param {AllowArray<Call>} transactions - Single call or array of calls to execute
+   * @param {UniversalDetails} [transactionsDetail] - Transaction execution options
+   * @param {fastWaitForTransactionOptions} [waitDetail={retries: 50, retryInterval: 500}] - options to scan the network for the next possible transaction. `retries` is the number of times to retry, `retryInterval` is the time in ms between retries.
+   * @returns {Promise<fastExecuteResponse>} Response containing the transaction result and status for the next transaction. If `isReady` is true, you can execute the next transaction. If false, timeout has been reached before the next transaction was possible.
+   * @example
+   * ```typescript
+   * const myProvider = new RpcProvider({ nodeUrl: url, blockIdentifier: BlockTag.PRE_CONFIRMED });
+   * const myAccount = new Account({ provider: myProvider, address: accountAddress0, signer: privateKey0 });
+   * const resp = await myAccount.fastExecute(
+   *     call, { tip: recommendedTip},
+   *     { retries: 30, retryInterval: 500 });
+   * // if resp.isReady is true, you can launch immediately a new tx.
+   * ```
+   */
+  async fastExecute(transactions, transactionsDetail = {}, waitDetail = {}) {
+    assert(
+      this.channel.blockIdentifier === BlockTag.PRE_CONFIRMED,
+      "Provider needs to be initialized with `pre_confirmed` blockIdentifier option."
+    );
+    const initNonce = BigInt(
+      transactionsDetail.nonce ?? await this.getNonceForAddress(this.address, BlockTag.PRE_CONFIRMED)
+    );
+    const details = { ...transactionsDetail, nonce: initNonce };
+    const resultTx = await this.execute(transactions, details);
+    const resultWait = await this.fastWaitForTransaction(
+      resultTx.transaction_hash,
+      this.address,
+      initNonce,
+      waitDetail
+    );
+    return { txResult: resultTx, isReady: resultWait };
+  }
+  /**
+   * First check if contract is already declared, if not declare it
+   * If contract already declared returned transaction_hash is ''.
+   * Method will pass even if contract is already declared
+   * @param transactionsDetail (optional)
+   */
+  async declareIfNot(payload, transactionsDetail = {}) {
+    const declareContractPayload = extractContractHashes(
+      payload,
+      await this.channel.getStarknetVersion()
+    );
+    try {
+      await this.getClassByHash(declareContractPayload.classHash);
+    } catch (error) {
+      return this.declare(payload, transactionsDetail);
+    }
+    return {
+      transaction_hash: "",
+      class_hash: declareContractPayload.classHash
+    };
+  }
+  async declare(payload, details = {}) {
+    assert(isSierra(payload.contract), SYSTEM_MESSAGES.declareNonSierra);
+    const declareContractPayload = extractContractHashes(
+      payload,
+      await this.channel.getStarknetVersion()
+    );
+    const detailsWithTip = await this.resolveDetailsWithTip(details);
+    const { resourceBounds: providedResourceBounds } = details;
+    let resourceBounds = providedResourceBounds;
+    if (!resourceBounds) {
+      const estimateResponse = await this.estimateDeclareFee(payload, detailsWithTip);
+      resourceBounds = estimateResponse.resourceBounds;
+    }
+    const accountInvocations = await this.accountInvocationsFactory(
+      [{ type: api_exports3.ETransactionType.DECLARE, payload: declareContractPayload }],
+      {
+        ...v3Details(detailsWithTip),
+        resourceBounds,
+        versions: [this.resolveTransactionVersion(details.version)],
+        nonce: details.nonce,
+        skipValidate: false
+      }
+    );
+    const declaration = accountInvocations[0];
+    return super.declareContract(
+      {
+        senderAddress: declaration.senderAddress,
+        signature: declaration.signature,
+        contract: declaration.contract,
+        compiledClassHash: declaration.compiledClassHash
+      },
+      {
+        ...v3Details(detailsWithTip),
+        nonce: declaration.nonce,
+        resourceBounds: declaration.resourceBounds,
+        version: declaration.version
+      }
+    );
+  }
+  async deploy(payload, details = {}) {
+    const { calls, addresses } = this.deployer.buildDeployerCall(payload, this.address);
+    const invokeResponse = await this.execute(calls, details);
+    return {
+      ...invokeResponse,
+      contract_address: addresses
+    };
+  }
+  async deployContract(payload, details = {}) {
+    const deployTx = await this.deploy(payload, details);
+    const txReceipt = await this.waitForTransaction(deployTx.transaction_hash, details);
+    return this.deployer.parseDeployerEvent(
+      txReceipt
+    );
+  }
+  async declareAndDeploy(payload, details = {}) {
+    let declare = await this.declareIfNot(payload, details);
+    if (declare.transaction_hash !== "") {
+      const tx = await this.waitForTransaction(declare.transaction_hash, details);
+      declare = { ...declare, ...tx };
+    }
+    const deploy = await this.deployContract(
+      { ...payload, classHash: declare.class_hash },
+      details
+    );
+    return { declare: { ...declare }, deploy };
+  }
+  async deployAccount({
+    classHash,
+    constructorCalldata = [],
+    addressSalt = 0,
+    contractAddress: providedContractAddress
+  }, details = {}) {
+    const compiledCalldata = CallData.compile(constructorCalldata);
+    const contractAddress = providedContractAddress ?? calculateContractAddressFromHash(addressSalt, classHash, compiledCalldata, 0);
+    const detailsWithTip = await this.resolveDetailsWithTip(details);
+    const { resourceBounds: providedResourceBounds } = details;
+    let resourceBounds = providedResourceBounds;
+    if (!resourceBounds) {
+      const estimateResponse = await this.estimateAccountDeployFee(
+        {
+          classHash,
+          constructorCalldata,
+          addressSalt,
+          contractAddress
+        },
+        detailsWithTip
+      );
+      resourceBounds = estimateResponse.resourceBounds;
+    }
+    const accountInvocations = await this.accountInvocationsFactory(
+      [
+        {
+          type: api_exports3.ETransactionType.DEPLOY_ACCOUNT,
+          payload: {
+            classHash,
+            constructorCalldata: compiledCalldata,
+            addressSalt,
+            contractAddress
+          }
+        }
+      ],
+      {
+        ...v3Details(detailsWithTip),
+        resourceBounds,
+        versions: [this.resolveTransactionVersion(details.version)],
+        nonce: ZERO,
+        // DEPLOY_ACCOUNT always uses nonce 0
+        skipValidate: false
+      }
+    );
+    const deployment = accountInvocations[0];
+    return super.deployAccountContract(
+      {
+        classHash: deployment.classHash,
+        addressSalt: deployment.addressSalt,
+        constructorCalldata: deployment.constructorCalldata,
+        signature: deployment.signature
+      },
+      {
+        ...v3Details(detailsWithTip),
+        nonce: deployment.nonce,
+        resourceBounds: deployment.resourceBounds,
+        version: deployment.version
+      }
+    );
+  }
+  async signMessage(typedData) {
+    return this.signer.signMessage(typedData, this.address);
+  }
+  async hashMessage(typedData) {
+    return getMessageHash(typedData, this.address);
+  }
+  /**
+   * Verify if an account is compatible with SNIP-9 outside execution, and with which version of this standard.
+   * @returns {OutsideExecutionVersion} Not compatible, V1, V2.
+   * @example
+   * ```typescript
+   * const result = myAccount.getSnip9Version();
+   * // result = "V1"
+   * ```
+   */
+  async getSnip9Version() {
+    if (await supportsInterface(this, this.address, SNIP9_V2_INTERFACE_ID)) {
+      return OutsideExecutionVersion.V2;
+    }
+    if (await supportsInterface(this, this.address, SNIP9_V1_INTERFACE_ID)) {
+      return OutsideExecutionVersion.V1;
+    }
+    return OutsideExecutionVersion.UNSUPPORTED;
+  }
+  /**
+   * Verify if a SNIP-9 nonce has not yet been used by the account.
+   * @param {BigNumberish} nonce SNIP-9 nonce to test.
+   * @returns  {boolean} true if SNIP-9 nonce not yet used.
+   * @example
+   * ```typescript
+   * const result = myAccount.isValidSnip9Nonce(1234);
+   * // result = true
+   * ```
+   */
+  async isValidSnip9Nonce(nonce) {
+    try {
+      const call = {
+        contractAddress: this.address,
+        entrypoint: "is_valid_outside_execution_nonce",
+        calldata: [toHex(nonce)]
+      };
+      const resp = await this.callContract(call);
+      return BigInt(resp[0]) !== 0n;
+    } catch (error) {
+      throw new Error(`Failed to check if nonce is valid: ${error}`);
+    }
+  }
+  /**
+   * Outside transaction needs a specific SNIP-9 nonce, that we get in this function.
+   * A SNIP-9 nonce can be any number not yet used ; no ordering is needed.
+   * @returns  {string} an Hex string of a SNIP-9 nonce.
+   * @example
+   * ```typescript
+   * const result = myAccount.getSnip9Nonce();
+   * // result = "0x28a612590dbc36927933c8ee0f357eee639c8b22b3d3aa86949eed3ada4ac55"
+   * ```
+   */
+  async getSnip9Nonce() {
+    const nonce = randomAddress();
+    const isValidNonce = await this.isValidSnip9Nonce(nonce);
+    if (!isValidNonce) {
+      return this.getSnip9Nonce();
+    }
+    return nonce;
+  }
+  /**
+   * Creates an object containing transaction(s) that can be executed by an other account with` Account.executeFromOutside()`, called Outside Transaction.
+   * @param {OutsideExecutionOptions} options Parameters of the transaction(s).
+   * @param {AllowArray<Call>} calls Transaction(s) to execute.
+   * @param {OutsideExecutionVersion} [version] SNIP-9 version of the Account that creates the outside transaction.
+   * @param {BigNumberish} [nonce] Outside Nonce.
+   * @returns {OutsideTransaction} and object that can be used in `Account.executeFromOutside()`
+   * @example
+   * ```typescript
+   * const now_seconds = Math.floor(Date.now() / 1000);
+   * const callOptions: OutsideExecutionOptions = {
+      caller: executorAccount.address, execute_after: now_seconds - 3600, execute_before: now_seconds + 3600 };
+   * const call1: Call = { contractAddress: ethAddress, entrypoint: 'transfer', calldata: {
+   *     recipient: recipientAccount.address, amount: cairo.uint256(100) } };
+   * const outsideTransaction1: OutsideTransaction = await signerAccount.getOutsideTransaction(callOptions, call3);
+   * // result = {
+   * // outsideExecution: {
+   * // caller: '0x64b48806902a367c8598f4f95c305e8c1a1acba5f082d294a43793113115691',
+   * // nonce: '0x28a612590dbc36927933c8ee0f357eee639c8b22b3d3aa86949eed3ada4ac55',
+   * // execute_after: 1723650229, execute_before: 1723704229, calls: [[Object]] },
+   * // signature: Signature {
+   * // r: 67518627037915514985321278857825384106482999609634873287406612756843916814n,
+   * // s: 737198738569840639192844101690009498983611654458636624293579534560862067709n, recovery: 0 },
+   * // signerAddress: '0x655f8fd7c4013c07cf12a92184aa6c314d181443913e21f7e209a18f0c78492',
+   * // version: '2'
+   * // }
+   * ```
+   */
+  async getOutsideTransaction(options, calls, version, nonce) {
+    if (!isHex2(options.caller) && options.caller !== "ANY_CALLER") {
+      throw new Error(`The caller ${options.caller} is not valid.`);
+    }
+    const codedCaller = isHex2(options.caller) ? options.caller : OutsideExecutionCallerAny;
+    const myCalls = [calls].flat();
+    const supportedVersion = version ?? await this.getSnip9Version();
+    if (!supportedVersion) {
+      throw new Error("This account is not handling outside transactions.");
+    }
+    const myNonce = nonce ? toHex(nonce) : await this.getSnip9Nonce();
+    const message = getTypedData(
+      await this.getChainId(),
+      {
+        caller: codedCaller,
+        execute_after: options.execute_after,
+        execute_before: options.execute_before
+      },
+      myNonce,
+      myCalls,
+      supportedVersion
+    );
+    const sign2 = await this.signMessage(message);
+    const toExecute = {
+      caller: codedCaller,
+      nonce: myNonce,
+      execute_after: options.execute_after,
+      execute_before: options.execute_before,
+      calls: myCalls.map(getOutsideCall)
+    };
+    return {
+      outsideExecution: toExecute,
+      signature: sign2,
+      signerAddress: this.address,
+      version: supportedVersion
+    };
+  }
+  /**
+   * An account B executes a transaction that has been signed by an account A.
+   * Fees are paid by B.
+   * @param {AllowArray<OutsideTransaction>} outsideTransaction the signed transaction generated by `Account.getOutsideTransaction()`.
+   * @param {UniversalDetails} [opts] same options than `Account.execute()`.
+   * @returns {InvokeFunctionResponse} same response than `Account.execute()`.
+   * @example
+   * ```typescript
+   * const outsideTransaction1: OutsideTransaction = await signerAccount.getOutsideTransaction(callOptions, call1);
+   * const outsideTransaction2: OutsideTransaction = await signerAccount.getOutsideTransaction(callOptions4, call4);
+   * const result = await myAccount.executeFromOutside([
+      outsideTransaction1,
+      outsideTransaction2,
+    ]);
+   * // result = { transaction_hash: '0x11233...`}
+   * ```
+   */
+  async executeFromOutside(outsideTransaction, opts) {
+    const multiCall = buildExecuteFromOutsideCall(outsideTransaction);
+    return this.execute(multiCall, opts);
+  }
+  /*
+   * Support methods
+   */
+  /**
+   * Helper method to resolve details with tip estimation
+   * @private
+   */
+  async resolveDetailsWithTip(details) {
+    return {
+      ...details,
+      tip: details.tip ?? (await this.getEstimateTip())[this.defaultTipType]
+    };
+  }
+  /**
+   * Helper method to resolve transaction version
+   * @private
+   */
+  resolveTransactionVersion(providedVersion) {
+    return toTransactionVersion(
+      this.transactionVersion || ETransactionVersion33.V3,
+      providedVersion
+    );
+  }
+  async buildInvocation(call, details) {
+    const calldata = getExecuteCalldata(call, await this.getCairoVersion());
+    const signature = !details.skipValidate ? await this.signer.signTransaction(call, details) : [];
+    return {
+      ...v3Details(details),
+      contractAddress: this.address,
+      calldata,
+      signature
+    };
+  }
+  async buildDeclarePayload(payload, details) {
+    const { classHash, contract, compiledClassHash } = extractContractHashes(
+      payload,
+      await this.channel.getStarknetVersion()
+    );
+    const compressedCompiledContract = parseContract(contract);
+    assert(
+      !isUndefined(compiledClassHash) && (details.version === ETransactionVersion33.F3 || details.version === ETransactionVersion33.V3),
+      "V3 Transaction work with Cairo1 Contracts and require compiledClassHash"
+    );
+    const signature = !details.skipValidate ? await this.signer.signDeclareTransaction({
+      ...details,
+      ...v3Details(details),
+      classHash,
+      compiledClassHash,
+      senderAddress: details.walletAddress
+    }) : [];
+    return {
+      senderAddress: details.walletAddress,
+      signature,
+      contract: compressedCompiledContract,
+      compiledClassHash
+    };
+  }
+  async buildAccountDeployPayload({
+    classHash,
+    addressSalt = 0,
+    constructorCalldata = [],
+    contractAddress: providedContractAddress
+  }, details) {
+    const compiledCalldata = CallData.compile(constructorCalldata);
+    const contractAddress = providedContractAddress ?? calculateContractAddressFromHash(addressSalt, classHash, compiledCalldata, 0);
+    const signature = !details.skipValidate ? await this.signer.signDeployAccountTransaction({
+      ...details,
+      ...v3Details(details),
+      classHash,
+      contractAddress,
+      addressSalt,
+      constructorCalldata: compiledCalldata
+    }) : [];
+    return {
+      ...v3Details(details),
+      classHash,
+      addressSalt,
+      constructorCalldata: compiledCalldata,
+      signature
+    };
+  }
+  async accountInvocationsFactory(invocations, details) {
+    const { nonce, blockIdentifier, skipValidate = true } = details;
+    const safeNonce = await this.getNonceSafe(nonce);
+    const chainId = await this.getChainId();
+    const versions = details.versions.map((it) => toTransactionVersion(it));
+    const tx0Payload = "payload" in invocations[0] ? invocations[0].payload : invocations[0];
+    const cairoVersion = invocations[0].type === api_exports3.ETransactionType.DEPLOY_ACCOUNT ? await this.getCairoVersion(tx0Payload.classHash) : await this.getCairoVersion();
+    return Promise.all(
+      [].concat(invocations).map(async (transaction, index) => {
+        const txPayload = "payload" in transaction ? transaction.payload : transaction;
+        const signerDetails = {
+          ...v3Details(details),
+          walletAddress: this.address,
+          nonce: toBigInt(Number(safeNonce) + index),
+          chainId,
+          cairoVersion,
+          version: versions[0],
+          skipValidate
+        };
+        const common2 = {
+          type: transaction.type,
+          nonce: toBigInt(Number(safeNonce) + index),
+          blockIdentifier,
+          version: versions[0]
+        };
+        if (transaction.type === api_exports3.ETransactionType.INVOKE) {
+          const payload = await this.buildInvocation(
+            [].concat(txPayload),
+            signerDetails
+          );
+          return {
+            ...common2,
+            ...payload,
+            ...signerDetails
+          };
+        }
+        if (transaction.type === api_exports3.ETransactionType.DEPLOY) {
+          const { calls } = this.deployer.buildDeployerCall(txPayload, this.address);
+          const payload = await this.buildInvocation(calls, signerDetails);
+          return {
+            ...common2,
+            ...payload,
+            ...signerDetails,
+            type: api_exports3.ETransactionType.INVOKE
+          };
+        }
+        if (transaction.type === api_exports3.ETransactionType.DECLARE) {
+          assert(
+            isSierra(txPayload.contract),
+            "Declare fee estimation is not supported for Cairo0 contracts"
+          );
+          const payload = await this.buildDeclarePayload(txPayload, signerDetails);
+          return {
+            ...common2,
+            ...payload,
+            ...signerDetails
+          };
+        }
+        if (transaction.type === api_exports3.ETransactionType.DEPLOY_ACCOUNT) {
+          const payload = await this.buildAccountDeployPayload(txPayload, signerDetails);
+          return {
+            ...common2,
+            ...payload,
+            ...signerDetails
+          };
+        }
+        throw Error(`accountInvocationsFactory: unsupported transaction type: ${transaction}`);
+      })
+    );
+  }
+  /*
+   * SNIP-29 Paymaster
+   */
+  async buildPaymasterTransaction(calls, paymasterDetails) {
+    if (!paymasterDetails.deploymentData) {
+      const snip9Version = await this.getSnip9Version();
+      if (snip9Version === OutsideExecutionVersion.UNSUPPORTED) {
+        throw Error("Account is not compatible with SNIP-9");
+      }
+    }
+    const parameters = {
+      version: "0x1",
+      feeMode: paymasterDetails.feeMode,
+      timeBounds: paymasterDetails.timeBounds
+    };
+    let transaction;
+    if (paymasterDetails.deploymentData) {
+      if (calls.length > 0) {
+        transaction = {
+          type: "deploy_and_invoke",
+          invoke: { userAddress: this.address, calls },
+          deployment: paymasterDetails.deploymentData
+        };
+      } else {
+        transaction = {
+          type: "deploy",
+          deployment: paymasterDetails.deploymentData
+        };
+      }
+    } else {
+      transaction = {
+        type: "invoke",
+        invoke: { userAddress: this.address, calls }
+      };
+    }
+    return this.paymaster.buildTransaction(transaction, parameters);
+  }
+  async estimatePaymasterTransactionFee(calls, paymasterDetails) {
+    const preparedTransaction = await this.buildPaymasterTransaction(calls, paymasterDetails);
+    return preparedTransaction.fee;
+  }
+  async preparePaymasterTransaction(preparedTransaction) {
+    let transaction;
+    switch (preparedTransaction.type) {
+      case "deploy_and_invoke": {
+        const signature = await this.signMessage(preparedTransaction.typed_data);
+        transaction = {
+          type: "deploy_and_invoke",
+          invoke: {
+            userAddress: this.address,
+            typedData: preparedTransaction.typed_data,
+            signature: signatureToHexArray(signature)
+          },
+          deployment: preparedTransaction.deployment
+        };
+        break;
+      }
+      case "invoke": {
+        const signature = await this.signMessage(preparedTransaction.typed_data);
+        transaction = {
+          type: "invoke",
+          invoke: {
+            userAddress: this.address,
+            typedData: preparedTransaction.typed_data,
+            signature: signatureToHexArray(signature)
+          }
+        };
+        break;
+      }
+      case "deploy": {
+        transaction = {
+          type: "deploy",
+          deployment: preparedTransaction.deployment
+        };
+        break;
+      }
+      default:
+        throw Error("Invalid transaction type");
+    }
+    return transaction;
+  }
+  async executePaymasterTransaction(calls, paymasterDetails, maxFeeInGasToken) {
+    const preparedTransaction = await this.buildPaymasterTransaction(calls, paymasterDetails);
+    assertPaymasterTransactionSafety(
+      preparedTransaction,
+      calls,
+      paymasterDetails,
+      maxFeeInGasToken
+    );
+    const transaction = await this.preparePaymasterTransaction(preparedTransaction);
+    return this.paymaster.executeTransaction(transaction, preparedTransaction.parameters).then((response) => ({ transaction_hash: response.transaction_hash }));
+  }
+  /*
+   * External methods
+   */
+  /**
+   * Get the Starknet ID for an address
+   * @param address - The address to get the Starknet ID for
+   * @param StarknetIdContract - The Starknet ID contract address (optional)
+   * @returns The Starknet ID for the address
+   */
+  async getStarkName(address = this.address, StarknetIdContract2) {
+    return super.getStarkName(address, StarknetIdContract2);
+  }
+};
 var connect_exports = {};
 __export2(connect_exports, {
   addDeclareTransaction: () => addDeclareTransaction,
@@ -20076,6 +20927,178 @@ function useThresholdSign(opts) {
     finalize
   };
 }
+var DEFAULTS = {
+  apiBaseUrl: "https://api.chipipay.com/v1",
+  rpcUrl: "https://api.cartridge.gg/x/starknet/mainnet",
+  chainId: "0x534e5f4d41494e",
+  gasTankAddress: "0x232f9c4ec684c03caae94f75987ea0540c06173d96dd5c6705521eb45e28b0a"
+};
+async function derivePrivacyAccount(p) {
+  const pool = await core.derivePoolKeypair({
+    anchorSecret: p.anchorSecret,
+    seedDomainTag: p.seedDomainTag
+  });
+  const companion = await core.deriveCompanionKeypair(p.anchorSecret);
+  return {
+    companionAddress: core.deriveCompanionAddress({
+      publicKey: companion.publicKey,
+      classHash: p.classHash
+    }),
+    companionKey: companion.privateKey,
+    classHash: p.classHash,
+    poolKey: BigInt(pool.privateKey)
+  };
+}
+function buildCtx(config3, keys) {
+  const rpcUrl = config3.rpcUrl ?? DEFAULTS.rpcUrl;
+  return {
+    provider: new RpcProvider2({ nodeUrl: rpcUrl }),
+    chainId: config3.chainId ?? DEFAULTS.chainId,
+    companionAddress: keys.companionAddress,
+    companionKey: keys.companionKey,
+    classHash: keys.classHash,
+    poolKey: keys.poolKey,
+    provingProvider: new core.ChipiProofProvider({
+      baseUrl: config3.apiBaseUrl ?? DEFAULTS.apiBaseUrl,
+      apiKey: config3.apiPublicKey,
+      getBearerToken: config3.getBearerToken,
+      chainId: config3.chainId ?? DEFAULTS.chainId
+    }),
+    gatewaySubmitUrl: config3.gatewaySubmitUrl,
+    rpcUrl
+  };
+}
+async function runShield(input) {
+  const { config: config3, keys } = input;
+  const ctx = buildCtx(config3, keys);
+  input.onStep?.("prepare");
+  input.onStep?.("fund");
+  await core.requestGasFunding(keys.companionAddress, {
+    baseUrl: config3.apiBaseUrl ?? DEFAULTS.apiBaseUrl,
+    apiKey: config3.apiPublicKey,
+    getBearerToken: config3.getBearerToken
+  });
+  if (input.fundDeposit) {
+    input.onStep?.("deposit");
+    await input.fundDeposit(keys.companionAddress, input.amount);
+  }
+  await core.waitForFunding(ctx.provider, keys.companionAddress, {
+    strk: core.GAS_FUND_STRK,
+    token: input.fundDeposit ? { address: input.token, amount: input.amount } : void 0
+  });
+  input.onStep?.("prove");
+  const result = await core.execShield(ctx, input.token, input.amount);
+  input.onStep?.("finish");
+  void core.sweepCompanion({
+    provider: ctx.provider,
+    companionAddress: keys.companionAddress,
+    companionKey: keys.companionKey,
+    gasTank: config3.gasTankAddress ?? DEFAULTS.gasTankAddress
+  });
+  return result;
+}
+async function runUnshield(input) {
+  const { config: config3, keys } = input;
+  const ctx = buildCtx(config3, keys);
+  input.onStep?.("prepare");
+  input.onStep?.("fund");
+  await core.requestGasFunding(keys.companionAddress, {
+    baseUrl: config3.apiBaseUrl ?? DEFAULTS.apiBaseUrl,
+    apiKey: config3.apiPublicKey,
+    getBearerToken: config3.getBearerToken
+  });
+  await core.waitForFunding(ctx.provider, keys.companionAddress, { strk: core.GAS_FUND_STRK });
+  input.onStep?.("prove");
+  const result = await core.execUnshield(ctx, input.token, input.amount);
+  input.onStep?.("finish");
+  const swept = await core.sweepCompanion({
+    provider: ctx.provider,
+    companionAddress: keys.companionAddress,
+    companionKey: keys.companionKey,
+    gasTank: config3.gasTankAddress ?? DEFAULTS.gasTankAddress,
+    deliverToken: { address: input.token, to: input.deliverTo },
+    strict: true
+  });
+  if (swept.transactionHash === null) {
+    throw new Error(
+      "unshield_undelivered: the withdrawal settled but delivery to your wallet could not be confirmed \u2014 funds are safe in the companion account; retry"
+    );
+  }
+  return result;
+}
+function useShield() {
+  const mutation = reactQuery.useMutation({ mutationFn: runShield });
+  return {
+    shield: mutation.mutate,
+    shieldAsync: mutation.mutateAsync,
+    data: mutation.data,
+    isLoading: mutation.isPending,
+    isError: mutation.isError,
+    error: mutation.error,
+    isSuccess: mutation.isSuccess,
+    reset: mutation.reset
+  };
+}
+function useUnshield() {
+  const mutation = reactQuery.useMutation({
+    mutationFn: runUnshield
+  });
+  return {
+    unshield: mutation.mutate,
+    unshieldAsync: mutation.mutateAsync,
+    data: mutation.data,
+    isLoading: mutation.isPending,
+    isError: mutation.isError,
+    error: mutation.error,
+    isSuccess: mutation.isSuccess,
+    reset: mutation.reset
+  };
+}
+function netPrivateBalance(events) {
+  const byToken = {};
+  for (const e of events) {
+    const signed = e.direction === "shield" ? e.amount : -e.amount;
+    byToken[e.token] = (byToken[e.token] ?? 0n) + signed;
+  }
+  for (const k of Object.keys(byToken)) if (byToken[k] < 0n) byToken[k] = 0n;
+  return byToken;
+}
+function usePrivateBalance(input) {
+  const query = reactQuery.useQuery({
+    queryKey: [
+      "chipi-private-balance",
+      input.mode,
+      // A stale cache here is a stale MONEY balance (review finding m1):
+      // ledger mode keys on a content digest (length alone missed same-count
+      // edits); onchain mode keys on the account AND the token filter.
+      input.mode === "ledger" ? input.events.reduce((h, e) => h + (e.direction === "shield" ? e.amount : -e.amount), 0n).toString() + ":" + input.events.length : input.keys.companionAddress + ":" + (input.tokens ?? []).join(",")
+    ],
+    queryFn: async () => {
+      if (input.mode === "ledger") return netPrivateBalance(input.events);
+      const ctx = buildCtx(input.config, input.keys);
+      const { byToken } = await core.getPrivateBalance({
+        provider: ctx.provider,
+        account: new Account({
+          provider: ctx.provider,
+          address: input.keys.companionAddress,
+          signer: input.keys.companionKey,
+          cairoVersion: "1"
+        }),
+        viewingKey: input.keys.poolKey,
+        provingProvider: ctx.provingProvider,
+        tokens: input.tokens
+      });
+      return byToken;
+    }
+  });
+  return {
+    byToken: query.data ?? {},
+    isLoading: query.isLoading,
+    isError: query.isError,
+    error: query.error,
+    refetch: query.refetch
+  };
+}
 
 // src/connect/window-object.ts
 var SUPPORTED_SPECS = ["0.8"];
@@ -20426,7 +21449,9 @@ exports.ChipiInjector = ChipiInjector;
 exports.ChipiProvider = ChipiProvider;
 exports.Recover = Recover;
 exports.createChipiWindowObject = createChipiWindowObject;
+exports.derivePrivacyAccount = derivePrivacyAccount;
 exports.injectChipiWallet = injectChipiWallet;
+exports.netPrivateBalance = netPrivateBalance;
 exports.useAddSessionKeyToContract = useAddSessionKeyToContract;
 exports.useApprove = useApprove;
 exports.useCallAnyContract = useCallAnyContract;
@@ -20449,14 +21474,17 @@ exports.useGetWallet = useGetWallet;
 exports.useGuardianRecovery = useGuardianRecovery;
 exports.useMigrateWalletToPasskey = useMigrateWalletToPasskey;
 exports.useMigrateWalletToShhh = useMigrateWalletToShhh;
+exports.usePrivateBalance = usePrivateBalance;
 exports.usePurchaseSku = usePurchaseSku;
 exports.useRecordSendTransaction = useRecordSendTransaction;
 exports.useRevokeSessionKey = useRevokeSessionKey;
 exports.useShhhSigner = useShhhSigner;
+exports.useShield = useShield;
 exports.useSignTypedData = useSignTypedData;
 exports.useSyncOnChainTransfers = useSyncOnChainTransfers;
 exports.useThresholdSign = useThresholdSign;
 exports.useTransfer = useTransfer;
+exports.useUnshield = useUnshield;
 exports.useUpdateWalletEncryption = useUpdateWalletEncryption;
 exports.useX402Payment = useX402Payment;
 //# sourceMappingURL=index.js.map