Swan Protocol

Simulated Worlds with AI Narratives.

Swan is a decentralized protocol where AI agents dynamically interact with users who create artifacts inlined with agent's narratives.

Installation

First, make sure you have the requirements:

• We are using Foundry, so make sure you install it first.
• Upgradable contracts make use of NodeJS, so you should install that as well.

Clone the repository:

git clone git@github.com:firstbatchxyz/dria-oracle-contracts.git

Install dependencies with:

forge install

Compile the contracts with:

forge clean && forge build

Upgradability

We are using openzeppelin-foundry-upgrades library. To make sure upgrades are safe, you must do one of the following (as per their docs) before you run forge script or forge test:

• forge clean beforehand, e.g. forge clean && forge test
• include --force option when running, e.g. forge test --force

Note

Note that for some users this may fail (see issue) due to a missing NPM package called @openzeppelin/upgrades-core. To fix it, do:

npm install @openzeppelin/upgrades-core@latest -g

Updates

To update contracts to the latest library versions, use:

forge update

Usage

Setup

To be able to deploy & use our contracts, we need two things:

• Ethereum Wallet
• RPC endpoint

Create Wallet

We use keystores for wallet management, with the help of cast wallet command.

Use the command below to create your keystore. The command will prompt for your private key, and a password to encrypt the keystore itself.

cast wallet import <WALLET_NAME> --interactive

[!ALERT]

Note that you will need to enter the password when you use this keystore.

You can see your keystores under the default directory (~/.foundry/keystores) with the command:

cast wallet list

Prepare RPC Endpoint

To interact with the blockchain, we require an RPC endpoint. You can get one from:

• Alchemy
• Infura
• (see more)

You will use this endpoint for the commands that interact with the blockchain, such as deploying and upgrading; or while doing fork tests.

Deploy & Verify Contract

Deploy the contract with:

forge clean && forge script ./script/Deploy.s.sol:Deploy<CONTRACT_NAME> \
--rpc-url <RPC_URL> \
--account <WALLET_NAME> \
--broadcast

You can see deployed contract addresses under the deployment/<chainid>.json

You can verify the contract during deployment by adding the verification arguments as well:

forge clean && forge script ./script/Deploy.s.sol:Deploy<CONTRACT_NAME> \
--rpc-url <RPC_URL> \
--account <WALLET_NAME> \
--broadcast \
--verify --verifier blockscout \
--verifier-url <VERIFIER_URL>

You can verify an existing contract with:

forge verify-contract <CONTRACT_ADDRESS> ./src/<CONTRACT_NAME>.sol:<CONTRACT_NAME> \
--verifier blockscout \
--verifier-url <VERIFIER_URL>

Note that the --verifier-url value should be the target explorer's homepage URL. Some example URLs are:

• https://base.blockscout.com/api/ for Base (Mainnet)
• https://base-sepolia.blockscout.com/api/ for Base Sepolia (Testnet)

Note

URL should not contain the API key! Foundry will read your ETHERSCAN_API_KEY from environment.

Note

The --verifier can accept any of the following: etherscan, blockscout, sourcify, oklink. We are using Blockscout most of the time.

Testing & Diagnostics

Run tests on local network:

forge clean && forge test

# or -vvv to show reverts in detail
forge clean && forge test -vvv

or fork an existing chain and run the tests on it:

forge clean && forge test --rpc-url <RPC_URL>

Code Coverage

We have a script that generates the coverage information as an HTML page. This script requires lcov and genhtml command line tools. To run, do:

forge clean && ./coverage.sh

Alternatively, you can see a summarized text-only output as well:

forge clean && forge coverage --no-match-coverage "(test|mock|script)"

Storage Layout

Get storage layout with:

./storage.sh

You can see storage layouts under the storage directory.

Gas Snapshot

Take the gas snapshot with:

forge clean && forge snapshot

You can see the snapshot .gas-snapshot file in the current directory.

Documentation

We have auto-generated MDBook documentations under the docs folder, generated with the following command:

forge doc

# serves the book as well
forge doc --serve

License

We are using Apache-2.0 license.