Foreign Procedure Invocation Tutorial

Using foreign procedure invocation to craft read-only cross-contract calls with the WebClient

Overview

In previous tutorials we deployed a public counter contract and incremented the count from a different client instance.

In this tutorial we will cover the basics of "foreign procedure invocation" (FPI) using the WebClient. To demonstrate FPI, we will build a "count copy" smart contract that reads the count from our previously deployed counter contract and copies the count to its own local storage.

Foreign procedure invocation (FPI) is a powerful tool for building composable smart contracts in Miden. FPI allows one smart contract or note to read the state of another contract.

The term "foreign procedure invocation" might sound a bit verbose, but it is as simple as one smart contract calling a non-state modifying procedure in another smart contract. The "EVM equivalent" of foreign procedure invocation would be a smart contract calling a read-only function in another contract.

FPI is useful for developing smart contracts that extend the functionality of existing contracts on Miden. FPI is the core primitive used by price oracles on Miden.

What We Will Build

The diagram above depicts the "count copy" smart contract using foreign procedure invocation to read the count state of the counter contract. After reading the state via FPI, the "count copy" smart contract writes the value returned from the counter contract to storage.

What we'll cover

• Foreign Procedure Invocation (FPI) with the WebClient
• Building a "count copy" smart contract
• Executing cross-contract calls in the browser

Prerequisites

• Node v20 or greater
• Familiarity with TypeScript
• yarn

This tutorial assumes you have a basic understanding of Miden assembly and completed the previous tutorial on incrementing the counter contract. To quickly get up to speed with Miden assembly (MASM), please play around with running basic Miden assembly programs in the Miden playground.

Step 1: Initialize your Next.js project

1. Create a new Next.js app with TypeScript:

   yarn create next-app@latest miden-fpi-app --typescript

   Hit enter for all terminal prompts.

2. Change into the project directory:

   cd miden-fpi-app

3. Install the Miden WebClient SDK:

   yarn install @miden-sdk/[email protected]

NOTE!: Be sure to add the --webpack command to your package.json when running the dev script. The dev script should look like this:

package.json

  "scripts": {
    "dev": "next dev --webpack",
    ...
  }

Step 2: Edit the app/page.tsx file

Add the following code to the app/page.tsx file. This code defines the main page of our web application:

'use client';
import { useState } from 'react';
import { foreignProcedureInvocation } from '../lib/foreignProcedureInvocation';

export default function Home() {
  const [isFPIRunning, setIsFPIRunning] = useState(false);

  const handleForeignProcedureInvocation = async () => {
    setIsFPIRunning(true);
    await foreignProcedureInvocation();
    setIsFPIRunning(false);
  };

  return (
    <main className="min-h-screen flex items-center justify-center bg-gradient-to-br from-gray-900 via-gray-800 to-black text-slate-800 dark:text-slate-100">
      <div className="text-center">
        <h1 className="text-4xl font-semibold mb-4">Miden FPI Web App</h1>
        <p className="mb-6">Open your browser console to see WebClient logs.</p>

        <div className="max-w-sm w-full bg-gray-800/20 border border-gray-600 rounded-2xl p-6 mx-auto flex flex-col gap-4">
          <button
            onClick={handleForeignProcedureInvocation}
            className="w-full px-6 py-3 text-lg cursor-pointer bg-transparent border-2 border-orange-600 text-white rounded-lg transition-all hover:bg-orange-600 hover:text-white"
          >
            {isFPIRunning
              ? 'Working...'
              : 'Foreign Procedure Invocation Tutorial'}
          </button>
        </div>
      </div>
    </main>
  );
}

Step 3: Write the MASM Contract Files

The MASM (Miden Assembly) code for our smart contracts lives in separate .masm files. Create a lib/masm/ directory and add the two contract files:

mkdir -p lib/masm

Counter contract

Create the file lib/masm/counter_contract.masm. This is the counter contract that was deployed in the previous tutorial. We need its source code here so we can compile it locally and obtain the procedure hash for get_count:

use miden::protocol::active_account
use miden::protocol::native_account
use miden::core::word
use miden::core::sys

const COUNTER_SLOT = word("miden::tutorials::counter")

#! Inputs:  []
#! Outputs: [count]
pub proc get_count
    push.COUNTER_SLOT[0..2] exec.active_account::get_item
    # => [count]

    exec.sys::truncate_stack
    # => [count]
end

#! Inputs:  []
#! Outputs: []
pub proc increment_count
    push.COUNTER_SLOT[0..2] exec.active_account::get_item
    # => [count]

    add.1
    # => [count+1]

    push.COUNTER_SLOT[0..2] exec.native_account::set_item
    # => []

    exec.sys::truncate_stack
    # => []
end

Count reader contract

Create the file lib/masm/count_reader.masm. This is the new "count copy" contract that reads the counter value via FPI and stores it locally:

use miden::protocol::active_account
use miden::protocol::native_account
use miden::protocol::tx
use miden::core::word
use miden::core::sys

const COUNT_READER_SLOT = word("miden::tutorials::count_reader")

# => [account_id_prefix, account_id_suffix, get_count_proc_hash]
pub proc copy_count
    exec.tx::execute_foreign_procedure
    # => [count]

    push.COUNT_READER_SLOT[0..2]
    # [slot_id_prefix, slot_id_suffix, count]

    exec.native_account::set_item
    # => [OLD_VALUE]

    dropw
    # => []

    exec.sys::truncate_stack
    # => []
end

Type declaration

Create lib/masm/masm.d.ts so TypeScript recognizes .masm imports:

declare module '*.masm' {
  const content: string;
  export default content;
}

Step 4: Configure Your Bundler to Import .masm Files

We need to tell our bundler to treat .masm files as plain text strings. In Next.js, add an asset/source webpack rule.

Open next.config.ts and add the highlighted rule inside the webpack callback:

webpack: (config, { isServer }) => {
  // ... existing WASM config ...

  // Import .masm files as strings
  config.module.rules.push({
    test: /\.masm$/,
    type: "asset/source",
  });

  return config;
},

• Vite: use the ?raw suffix — import code from './masm/counter_contract.masm?raw'
• Other bundlers / no bundler: use fetch() at runtime — const code = await fetch('/masm/counter_contract.masm').then(r => r.text())

Step 5: Create the Foreign Procedure Invocation Implementation

Create the file lib/foreignProcedureInvocation.ts and add the following code.

touch lib/foreignProcedureInvocation.ts

Copy and paste the following code into the lib/foreignProcedureInvocation.ts file:

// lib/foreignProcedureInvocation.ts
import counterContractCode from './masm/counter_contract.masm';
import countReaderCode from './masm/count_reader.masm';

export async function foreignProcedureInvocation(): Promise<void> {
  if (typeof window === 'undefined') {
    console.warn('foreignProcedureInvocation() can only run in the browser');
    return;
  }

  // dynamic import → only in the browser, so WASM is loaded client‑side
  const { AccountType, AuthSecretKey, StorageMode, StorageSlot, MidenClient } =
    await import('@miden-sdk/miden-sdk');

  const nodeEndpoint = 'https://rpc.testnet.miden.io';
  const client = await MidenClient.create({ rpcUrl: nodeEndpoint });
  console.log('Current block number: ', (await client.sync()).blockNum());

  // -------------------------------------------------------------------------
  // STEP 1: Create the Count Reader Contract
  // -------------------------------------------------------------------------
  console.log('\n[STEP 1] Creating count reader contract.');

  const countReaderSlotName = 'miden::tutorials::count_reader';
  const counterSlotName = 'miden::tutorials::counter';

  // Compile the count reader component
  const countReaderComponent = await client.compile.component({
    code: countReaderCode,
    slots: [StorageSlot.emptyValue(countReaderSlotName)],
  });

  const walletSeed = new Uint8Array(32);
  crypto.getRandomValues(walletSeed);

  const auth = AuthSecretKey.rpoFalconWithRNG(walletSeed);

  // Create the count reader contract account
  console.log('Creating count reader contract account...');
  let countReaderAccount = await client.accounts.create({
    type: AccountType.ImmutableContract,
    storage: StorageMode.Public,
    seed: walletSeed,
    auth,
    components: [countReaderComponent],
  });

  console.log('Count reader contract ID:', countReaderAccount.id().toString());

  // -------------------------------------------------------------------------
  // STEP 2: Build & Get State of the Counter Contract
  // -------------------------------------------------------------------------
  console.log('\n[STEP 2] Building counter contract from public state');

  // Import the counter contract from testnet by its bech32 address
  let counterContractAccount = await client.accounts.getOrImport(
    'mtst1arjemrxne8lj5qz4mg9c8mtyxg954483',
  );
  console.log(
    'Account storage slot:',
    counterContractAccount.storage().getItem(counterSlotName)?.toHex(),
  );

  // -------------------------------------------------------------------------
  // STEP 3: Call the Counter Contract via Foreign Procedure Invocation (FPI)
  // -------------------------------------------------------------------------
  console.log(
    '\n[STEP 3] Call counter contract with FPI from count reader contract',
  );

  // Compile the counter contract component to get the procedure hash
  const counterContractComponent = await client.compile.component({
    code: counterContractCode,
    slots: [StorageSlot.emptyValue(counterSlotName)],
  });

  const getCountProcHash =
    counterContractComponent.getProcedureHash('get_count');

  // Build the script that calls the count reader contract.
  // This script uses template literals because it interpolates runtime values
  // (procedure hash and account ID) that are only known after compilation.
  const fpiScriptCode = `
    use external_contract::count_reader_contract
    use miden::core::sys

    begin
    push.${getCountProcHash}
    # => [GET_COUNT_HASH]

    push.${counterContractAccount.id().suffix()}
    # => [account_id_suffix, GET_COUNT_HASH]

    push.${counterContractAccount.id().prefix()}
    # => [account_id_prefix, account_id_suffix, GET_COUNT_HASH]

    call.count_reader_contract::copy_count
    # => []

    exec.sys::truncate_stack
    # => []

    end
`;

  // Compile the transaction script with the count reader library
  const script = await client.compile.txScript({
    code: fpiScriptCode,
    libraries: [
      {
        namespace: 'external_contract::count_reader_contract',
        code: countReaderCode,
      },
    ],
  });

  // Execute the transaction on the count reader contract and send it to the network
  const txId = await client.transactions.execute({
    account: countReaderAccount.id(),
    script,
    foreignAccounts: [{ id: counterContractId }],
  });

  console.log(
    'View transaction on MidenScan: https://testnet.midenscan.com/tx/' +
      txId.toHex(),
  );

  // Refresh account objects to see the results
  counterContractAccount = await client.accounts.get(counterContractAccount);
  console.log(
    'counter contract storage:',
    counterContractAccount?.storage().getItem(counterSlotName)?.toHex(),
  );

  countReaderAccount = await client.accounts.get(countReaderAccount);
  console.log(
    'count reader contract storage:',
    countReaderAccount?.storage().getItem(countReaderSlotName)?.toHex(),
  );

  // Log the count value copied via FPI
  const countReaderStorage = countReaderAccount
    ?.storage()
    .getItem(countReaderSlotName);
  if (countReaderStorage) {
    const countValue = Number(countReaderStorage.toU64s()[3]);
    console.log('Count copied via Foreign Procedure Invocation:', countValue);
  }

  console.log('\nForeign Procedure Invocation Transaction completed!');
}

To run the code above in our frontend, run the following command:

yarn dev

Open the browser console and click the button "Foreign Procedure Invocation Tutorial".

This is what you should see in the browser console:

Current block number:  2168

[STEP 1] Creating count reader contract.
Count reader contract ID: 0x90128b4e27f34500000720bedaa49b

[STEP 2] Building counter contract from public state
Account storage slot: 0x0000000000000000000000000000000000000000000000001200000000000000

[STEP 3] Call counter contract with FPI from count reader contract
View transaction on MidenScan: https://testnet.midenscan.com/tx/0xffff3dc5454154d1ccf64c1ad170bdef2df471c714f6fe6ab542d060396b559f
counter contract storage: 0x0000000000000000000000000000000000000000000000001200000000000000
count reader contract storage: 0x0000000000000000000000000000000000000000000000001200000000000000
Count copied via Foreign Procedure Invocation: 18

Foreign Procedure Invocation Transaction completed!

Understanding the Count Reader Contract

The count reader smart contract contains a copy_count procedure that uses tx::execute_foreign_procedure to call the get_count procedure in the counter contract.

use miden::protocol::active_account
use miden::protocol::native_account
use miden::protocol::tx
use miden::core::word
use miden::core::sys

const COUNT_READER_SLOT = word("miden::tutorials::count_reader")

# => [account_id_prefix, account_id_suffix, get_count_proc_hash]
pub proc copy_count
    exec.tx::execute_foreign_procedure
    # => [count]

    push.COUNT_READER_SLOT[0..2]
    # [slot_id_prefix, slot_id_suffix, count]

    exec.native_account::set_item
    # => [OLD_VALUE]

    dropw
    # => []

    exec.sys::truncate_stack
    # => []
end

To call the get_count procedure, we push its hash along with the counter contract's ID suffix and prefix onto the stack before calling tx::execute_foreign_procedure.

The stack state before calling tx::execute_foreign_procedure should look like this:

# => [account_id_prefix, account_id_suffix, GET_COUNT_HASH]

After calling the get_count procedure in the counter contract, we save the count into the miden::tutorials::count_reader storage slot.

Understanding the Transaction Script

The transaction script that executes the foreign procedure invocation looks like this:

use external_contract::count_reader_contract
use miden::core::sys

begin
    push.${getCountProcHash}
    # => [GET_COUNT_HASH]

    push.${counterContractAccount.id().suffix()}
    # => [account_id_suffix, GET_COUNT_HASH]

    push.${counterContractAccount.id().prefix()}
    # => [account_id_prefix, account_id_suffix, GET_COUNT_HASH]

    call.count_reader_contract::copy_count
    # => []

    exec.sys::truncate_stack
    # => []
end

This script:

1. Pushes the procedure hash of the get_count function
2. Pushes the counter contract's account ID suffix and prefix
3. Calls the copy_count procedure in our count reader contract
4. Truncates the stack

Key WebClient Concepts for FPI

Getting Procedure Hashes

Compile the counter contract component using client.compile.component() and call getProcedureHash() to obtain the hash needed by the FPI script:

const counterContractComponent = await client.compile.component({
  code: counterContractCode,
  slots: [StorageSlot.emptyValue(counterSlotName)],
});

const getCountProcHash = counterContractComponent.getProcedureHash('get_count');

Compiling the Transaction Script with a Library

Use client.compile.txScript() and pass the count reader library inline. The library is linked dynamically so the script can call its procedures:

const script = await client.compile.txScript({
  code: fpiScriptCode,
  libraries: [
    {
      namespace: 'external_contract::count_reader_contract',
      code: countReaderCode,
    },
  ],
});

Foreign Accounts

Pass the foreign account directly in the execute() call using the foreignAccounts option. The client creates the ForeignAccount and AccountStorageRequirements internally — no manual construction needed:

const txId = await client.transactions.execute({
  account: countReaderAccount.id(),
  script,
  foreignAccounts: [{ id: counterContractId }],
});

Summary

In this tutorial we created a smart contract that calls the get_count procedure in the counter contract using foreign procedure invocation, and then saves the returned value to its local storage using the Miden WebClient.

The key steps were:

1. Writing the MASM contract files (counter_contract.masm and count_reader.masm)
2. Configuring the bundler to import .masm files as strings
3. Creating a count reader contract with a copy_count procedure
4. Importing the counter contract from the network
5. Getting the procedure hash for the get_count function
6. Building a transaction script that calls our count reader contract
7. Executing the transaction with a foreign account reference

Running the example

To run a full working example navigate to the web-client directory in the miden-tutorials repository and run the web application example:

cd web-client
yarn install
yarn start

Resetting the MidenClientDB

The Miden webclient stores account and note data in the browser. If you get errors such as "Failed to build MMR", then you should reset the Miden webclient store. When switching between Miden networks such as from localhost to testnet be sure to reset the browser store. To clear the account and node data in the browser, paste this code snippet into the browser console:

(async () => {
  const dbs = await indexedDB.databases();
  for (const db of dbs) {
    await indexedDB.deleteDatabase(db.name);
    console.log(`Deleted database: ${db.name}`);
  }
  console.log('All databases deleted.');
})();

Continue learning

Next tutorial: Creating Multiple Notes