Starknet Deploy is a tool designed to streamline the deployment, interaction, and management of Starknet contracts. This guide walks you through setting up your project, configuring your environment, and leveraging our public functions to work with contracts easily.

📚 Check out our complete documentation for detailed guides.

Table of Contents

• Overview
• Installation
• Project Initialization
• Project Structure
• Configuration
• Using the Contract Manager
  • Initialization
  • Deploying Contracts
  • Interacting with Contracts
    • Getting a Contract Instance
    • Reading Contract State (Call)
    • Writing to Contract State (Invoke)
  • Switching Accounts
• Available Public Functions

Overview

Starknet Contract Manager simplifies the process of:

• Deploying contracts: Automatically manage deployments and store contract addresses.
• Interacting with contracts: Easily call view functions or send transactions.
• Managing accounts: Seamlessly switch between different accounts for transactions.

Installation

Install the package via npm:

npm install @olas-protocol/starknet-deploy

Project Initialization

Set up your project with a single command that creates the necessary directories, configuration file, and example scripts:

npx starknet-deploy init

This command will:

• Create a project structure including directories for deployments and tasks.
• Generate a configuration file (starknet-deploy.config.ts).
• Add example deployment scripts and tasks to help you get started.

Project Structure

After initialization, your project will have a structure similar to:

your-project/
├── src/
│   └── scripts/
│       ├── deployments/
│       │   ├── example_deployment.ts
│       └── tasks/
│           └── example_task.ts
└── starknet-deploy.config.ts

Configuration

The main configuration is defined in the starknet-deploy.config.ts file. Here you can set your network details, account keys, and project paths.

Configuration File Example

import { StarknetDeployConfig } from '@olas-protocol/starknet-deploy';

const config: StarknetDeployConfig = {
  // Default network used for deployments and interactions
  defaultNetwork: 'sepolia',

  // Network settings
  networks: {
    sepolia: {
      rpcUrl: 'https://starknet-sepolia.public.blastapi.io/rpc/v0_8', // RPC URL for Sepolia
      accounts: ['<privateKey1>'], // Array of private keys for transactions
      addresses: ['<address1>'], // Array of addresses for the  given private keys
    },
    local: {
      rpcUrl: 'http://localhost:5050',
      accounts: [],
      addresses: [],
    },
  },

  // File paths for contract classes and scripts
  paths: {
    package_name: 'your_scarb_package_name', // (Optional) Your Scarb package name for compiled contract file names.
    root: '', // (Optional) Project root directory (defaults to current working directory)
    contractClasses: 'target/dev', // Directory containing compiled contract classes
    scripts: 'src/scripts', // Directory for deployment scripts and tasks
  },
};

export default config;

Using the Contract Manager

The Contract Manager exposes several public functions to help you deploy contracts, interact with them, and manage your accounts.

Initialization

Before performing any operations, initialize the Contract Manager:

import { initializeContractManager } from '@olas-protocol/starknet-deploy';

(async () => {
  // Initialize the contract manager (defaults to an 80% fee buffer)
  const contractManager = await initializeContractManager();
  // Now you can deploy or interact with contracts
})();

You can override the default buffer for all subsequent invocations by passing an option:

const contractManager = await initializeContractManager({
  defaultFeeBufferPercent: 120,
});

You can also define the fallback in starknet-deploy.config.ts via the defaultTransactionBufferPercent option:

const config: StarknetDeployConfig = {
  defaultNetwork: 'sepolia',
  defaultFeeBufferPercent: 120,
  // ...
};

Deploying Contracts

Deploy contracts using the deployContract function. Deployed addresses are stored automatically for future reference.

import { initializeContractManager } from '@olas-protocol/starknet-deploy';

(async () => {
  const contractManager = await initializeContractManager();

  // Deploy a contract named 'MyContract' with constructor arguments
  const contractAddress = await contractManager.deployContract({
    contractName: 'MyContract',
    constructorArgs: [123, '0x456'],
  });

  console.log(`Contract deployed at: ${contractAddress}`);
})();

Interacting with Contracts

Getting a Contract Instance

Retrieve a contract instance by its name (from saved deployments) or by using its address directly.

import { initializeContractManager } from '@olas-protocol/starknet-deploy';

(async () => {
  const contractManager = await initializeContractManager();

  // Get contract instance by name
  const contractInstance =
    await contractManager.getContractInstance('MyContract');

  // Or get contract instance by address
  const contractByAddress =
    await contractManager.getContractByAddress('0x04a149636a5...');
})();

Reading Contract State (Call)

To read state (i.e., call a view function), use the queryContract function with the appropriate parameters.

import { initializeContractManager } from '@olas-protocol/starknet-deploy';

(async () => {
  const contractManager = await initializeContractManager();

  // Call a view function (e.g., 'balanceOf') to read contract state
  const balance = await contractManager.queryContract(
    'MyToken', // Contract reference (name, address, or instance)
    'balanceOf', // Function name
    ['0x04a1496...'], // Function arguments
  );

  console.log(`Balance: ${balance}`);
})();

Writing to Contract State (Invoke)

For state-changing operations, invoke a function using the invokeContract method. You can also specify an optional fee buffer percentage.

import { initializeContractManager } from '@olas-protocol/starknet-deploy';

(async () => {
  const contractManager = await initializeContractManager();

  // Invoke a function (e.g., 'transfer') to update the contract state
  const txHash = await contractManager.invokeContract(
    'MyToken', // Contract reference (name, address, or instance)
    'transfer', // Function name
    ['0x04a1496...', 1000], // Function arguments
    50, // Optional fee buffer percentage (defaults to 80% if omitted)
  );

  console.log(`Transaction sent. Hash: ${txHash}`);
})();

Switching Accounts

You can change the account used for sending transactions with the updateAccount function. This allows you to manage multiple accounts seamlessly.

import { initializeContractManager } from '@olas-protocol/starknet-deploy';

(async () => {
  const contractManager = await initializeContractManager();

  // Switch to a different account by index (e.g., second account in the config)
  await contractManager.updateAccount(1);

  // Alternatively, pass a custom account object:
  // await contractManager.updateAccount(myCustomAccount);

  // Subsequent transactions will use the updated account
  const txHash = await contractManager.invokeContract(
    'MyContract',
    'setOwner',
    ['0x04a1496...'],
  );

  console.log(`Transaction sent. Hash: ${txHash}`);
})();

Available Public Functions

The following functions are publicly available via the Contract Manager:

• initializeContractManager(options?: { defaultFeeBufferPercent?: number }) Initializes and returns an instance of the Contract Manager. Use defaultFeeBufferPercent to set the fallback fee buffer (defaults to 80%).

• deployContract({ contractName, constructorArgs }) Deploys a contract with the given name and constructor arguments.

• getContractInstance(contractName: string) Retrieves a deployed contract instance by its name from saved deployments.

• getContractByAddress(address: string) Retrieves a contract instance using its address.

• queryContract(contractReference, functionName, args) Queries a contract's view function.

• invokeContract(contractReference, functionName, args, feeBuffer?) Sends a state-changing transaction to a contract.

  • The contractReference can be a contract name, an address, or a contract instance.
  • The feeBuffer is an optional parameter for fee estimation (defaults to 80% unless you override it). If a higher transaction fee is required, ensure you increase the feeBuffer accordingly.

• updateAccount(account: number | object) Switches the active account for transactions by index (number) or using a custom account object.