Trait ArtifactOutput

pub trait ArtifactOutput {
    type Artifact: Artifact + DeserializeOwned + Serialize + Debug + Send + Sync;
    type CompilerContract: CompilerContract;

    // Required methods
    fn contract_to_artifact(
        &self,
        _file: &Path,
        _name: &str,
        contract: Self::CompilerContract,
        source_file: Option<&SourceFile>,
    ) -> Self::Artifact;
    fn standalone_source_file_to_artifact(
        &self,
        _path: &Path,
        _file: &VersionedSourceFile,
    ) -> Option<Self::Artifact>;

    // Provided methods
    fn on_output<L>(
        &self,
        contracts: &VersionedContracts<Self::CompilerContract>,
        sources: &VersionedSourceFiles,
        layout: &ProjectPathsConfig<L>,
        ctx: OutputContext<'_>,
        primary_profiles: &HashMap<PathBuf, &str>,
    ) -> Result<Artifacts<Self::Artifact>> { ... }
    fn handle_artifacts(
        &self,
        _contracts: &VersionedContracts<Self::CompilerContract>,
        _artifacts: &Artifacts<Self::Artifact>,
    ) -> Result<()> { ... }
    fn output_file_name(
        name: &str,
        version: &Version,
        profile: &str,
        with_version: bool,
        with_profile: bool,
    ) -> PathBuf { ... }
    fn conflict_free_output_file(
        already_taken: &HashSet<String>,
        conflict: PathBuf,
        contract_file: &Path,
        artifacts_folder: &Path,
    ) -> PathBuf { ... }
    fn output_file(
        contract_file: &Path,
        name: &str,
        version: &Version,
        profile: &str,
        with_version: bool,
        with_profile: bool,
    ) -> PathBuf { ... }
    fn contract_name(file: &Path) -> Option<String> { ... }
    fn read_cached_artifact(path: &Path) -> Result<Self::Artifact> { ... }
    fn read_cached_artifacts<T, I>(
        files: I,
    ) -> Result<BTreeMap<PathBuf, Self::Artifact>>
       where I: IntoIterator<Item = T>,
             T: Into<PathBuf> { ... }
    fn get_artifact_path(
        ctx: &OutputContext<'_>,
        already_taken: &HashSet<String>,
        file: &Path,
        name: &str,
        artifacts_folder: &Path,
        version: &Version,
        profile: &str,
        with_version: bool,
        with_profile: bool,
    ) -> PathBuf { ... }
    fn output_to_artifacts<C>(
        &self,
        contracts: &VersionedContracts<Self::CompilerContract>,
        sources: &VersionedSourceFiles,
        ctx: OutputContext<'_>,
        layout: &ProjectPathsConfig<C>,
        primary_profiles: &HashMap<PathBuf, &str>,
    ) -> Artifacts<Self::Artifact> { ... }
    fn is_dirty(
        &self,
        _artifact_file: &ArtifactFile<Self::Artifact>,
    ) -> Result<bool> { ... }
    fn handle_cached_artifacts(
        &self,
        _artifacts: &Artifacts<Self::Artifact>,
    ) -> Result<()> { ... }
}

Handler invoked with the output of solc

Implementers of this trait are expected to take care of crate::compilers::CompilerContract to crate::ArtifactOutput::Artifact conversion and how that Artifact type is stored on disk, this includes artifact file location and naming.

Depending on the crate::Project contracts and their compatible versions, The project compiler may invoke different solc executables on the same solidity file leading to multiple crate::CompilerOutputs for the same .sol file. In addition to the solidity file to contract relationship (1-N*) crate::VersionedContracts also tracks the contract to (artifact + solc version) relationship (1-N+).

Required Associated Types

type Artifact: Artifact + DeserializeOwned + Serialize + Debug + Send + Sync

Represents the artifact that will be stored for a Contract

type CompilerContract: CompilerContract

Required Methods

fn contract_to_artifact( &self, _file: &Path, _name: &str, contract: Self::CompilerContract, source_file: Option<&SourceFile>, ) -> Self::Artifact

Convert a contract to the artifact type

This is the core conversion function that takes care of converting a Contract into the associated Artifact type. The SourceFile is also provided

fn standalone_source_file_to_artifact( &self, _path: &Path, _file: &VersionedSourceFile, ) -> Option<Self::Artifact>

This converts a SourceFile that doesn’t contain any contract definitions (interfaces, contracts, libraries) to an artifact.

We do this because not all SourceFiles emitted by solc have at least 1 corresponding entry in the contracts section of the solc output. For example for an errors.sol that only contains custom error definitions and no contract, no Contract object will be generated by solc. However, we still want to emit an Artifact for that file that may include the ast, docs etc., because other tools depend on this, such as slither.

Provided Methods

fn on_output<L>( &self, contracts: &VersionedContracts<Self::CompilerContract>, sources: &VersionedSourceFiles, layout: &ProjectPathsConfig<L>, ctx: OutputContext<'_>, primary_profiles: &HashMap<PathBuf, &str>, ) -> Result<Artifacts<Self::Artifact>>

Handle the aggregated set of compiled contracts from the solc crate::CompilerOutput.

This will be invoked with all aggregated contracts from (multiple) solc CompilerOutput. See crate::AggregatedCompilerOutput

fn handle_artifacts( &self, _contracts: &VersionedContracts<Self::CompilerContract>, _artifacts: &Artifacts<Self::Artifact>, ) -> Result<()>

Invoked after artifacts has been written to disk for additional processing.

fn output_file_name( name: &str, version: &Version, profile: &str, with_version: bool, with_profile: bool, ) -> PathBuf

Returns the file name for the contract’s artifact Greeter.json

fn conflict_free_output_file( already_taken: &HashSet<String>, conflict: PathBuf, contract_file: &Path, artifacts_folder: &Path, ) -> PathBuf

Returns the appropriate file name for the conflicting file.

This should ensure that the resulting PathBuf is conflict free, which could be possible if there are two separate contract files (in different folders) that contain the same contract:

src/A.sol::A src/nested/A.sol::A

Which would result in the same PathBuf if only the file and contract name is taken into account, Self::output_file.

This return a unique output file

fn output_file( contract_file: &Path, name: &str, version: &Version, profile: &str, with_version: bool, with_profile: bool, ) -> PathBuf

Returns the path to the contract’s artifact location based on the contract’s file and name

This returns contract.sol/contract.json by default

fn contract_name(file: &Path) -> Option<String>

The inverse of contract_file_name

Expected to return the solidity contract’s name derived from the file path sources/Greeter.sol -> Greeter

fn read_cached_artifact(path: &Path) -> Result<Self::Artifact>

Read the artifact that’s stored at the given path

Errors

Returns an error if - The file does not exist - The file’s content couldn’t be deserialized into the Artifact type

fn read_cached_artifacts<T, I>( files: I, ) -> Result<BTreeMap<PathBuf, Self::Artifact>>

where I: IntoIterator<Item = T>, T: Into<PathBuf>,

Read the cached artifacts that are located the paths the iterator yields

See Self::read_cached_artifact()

fn get_artifact_path( ctx: &OutputContext<'_>, already_taken: &HashSet<String>, file: &Path, name: &str, artifacts_folder: &Path, version: &Version, profile: &str, with_version: bool, with_profile: bool, ) -> PathBuf

Generates a path for an artifact based on already taken paths by either cached or compiled artifacts.

fn output_to_artifacts<C>( &self, contracts: &VersionedContracts<Self::CompilerContract>, sources: &VersionedSourceFiles, ctx: OutputContext<'_>, layout: &ProjectPathsConfig<C>, primary_profiles: &HashMap<PathBuf, &str>, ) -> Artifacts<Self::Artifact>

Convert the compiler output into a set of artifacts

Note: This does only convert, but NOT write the artifacts to disk, See Self::on_output()

fn is_dirty( &self, _artifact_file: &ArtifactFile<Self::Artifact>, ) -> Result<bool>

Handler allowing artifacts handler to enforce artifact recompilation.

fn handle_cached_artifacts( &self, _artifacts: &Artifacts<Self::Artifact>, ) -> Result<()>

Invoked with all artifacts that were not recompiled.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl ArtifactOutput for ConfigurableArtifacts

type Artifact = ConfigurableContractArtifact

type CompilerContract = Contract

impl ArtifactOutput for HardhatArtifacts

type Artifact = HardhatArtifact

type CompilerContract = Contract

impl ArtifactOutput for MinimalCombinedArtifacts

type Artifact = CompactContractBytecode

type CompilerContract = Contract

impl ArtifactOutput for MinimalCombinedArtifactsHardhatFallback

type Artifact = CompactContractBytecode

type CompilerContract = Contract

impl<T: ArtifactOutput<CompilerContract = C::CompilerContract>, C: Compiler> ArtifactOutput for Project<C, T>

type Artifact = <T as ArtifactOutput>::Artifact

type CompilerContract = <C as Compiler>::CompilerContract