Call built-in actors

Built-in actors can be invoked using the Protocol JSON-RPC API or the Filecoin.sol API.

APIs compared

The Protocol JSON-RPC API:

• Is maintained by Protocol Labs (PL).
• Uses JSON-RPC, a standardized way to encode remote procedure calls in JSON that can be transported using HTTP or WebSockets.
• Provides a language agnostic interface for Filecoin functionality.
• Allows applications to access Filecoin functionality using HTTP or WebSockets calls to a Filecoin node, like the Lotus daemon.
• Requires authentication for some API calls.
• Serves as the foundation for language-specific libraries (some of which are maintained by organizations other than PL) such as filecoin.js.

The Filecoin.sol API:

• Supports some but not all of the built-in actors and their methods.

Protocol API

Applications and off-chain services can access built-in actors and methods using the Filecoin JSON-RPC API exposed by nodes such as Lotus. Smart contracts should use Filecoin.sol or the actor precompiles instead. Links to the reference guides for each of the available actor methods are listed below:

• Account actor
• Datacap
• Miner
• Multisig
• Storage market actor
• Storage power actor
• Verified registry actor

Filecoin.sol

Smart contracts can access built-in actor methods with the filecoin.sol library, a set of Solidity libraries that allow Solidity smart contracts to call methods of Filecoin built-in actors. The maintained npm package is filecoin-solidity-api, and its current import paths use contracts/v0.8. This section contains information on the actors and methods available from filecoin.sol, along with installation instructions and references for examples of smart contracts that call built-in actor methods.

To invoke built-in actor methods using filecoin.sol, follow these steps:

1. Review the available actors and methods.
2. Import filecoin.sol.
3. Call a built-in actor.

Available actors and methods

The majority of the Account, DataCap, Storage Market, Miner, Storage Owner and Verified Registry actor methods are supported and are listed below. Cron, Payment Channel, Reward and System actor methods are currently not supported.

Account

DataCap

Miner

Multisig

Storage market

Storage power

Verified registry

Import filecoin.sol

The filecoin.sol library is embeddable into your smart contract, which means it does not need be present on chain first. Instead, you can just import the library and call the available methods. The filecoin.sol library can be added via npm or manually imported into your contract. The npm-based import is simpler, and is recommended.

Import filecoin.sol with npm

1. Install the Filecoin Solidity API package:

npm install filecoin-solidity-api

Import filecoin.sol manually

1. Navigate to your smart contract project folder <my-project>:

cd my-project

1. Create a folder named libs:

mkdir libs

1. Move into the libs directory:

cd libs

1. Copy the Filecoin Solidity API contracts with the methods you wish to call from the contracts folder into libs. Preserve the subdirectories such as types, utils, and cbor, because the actor API files import those dependencies.

Call a built-in actor

Once you’ve either imported particular contracts manually or installed filecoin-solidity-api using npm, create a callable method to access the built-in actor methods the way you normally would in a Solidity smart contract. See the Filecoin.sol guide for npm import examples and the reference guide for actor-specific method examples.

Was this page helpful?