ethers-rs/ethers-solc/src/artifacts/output_selection.rs

577 lines
20 KiB
Rust

//! bindings for standard json output selection
use serde::{ser::SerializeMap, Deserialize, Deserializer, Serialize, Serializer};
use std::{collections::BTreeMap, fmt, str::FromStr};
/// Represents the desired outputs based on a File `(file -> (contract -> [outputs]))`
pub type FileOutputSelection = BTreeMap<String, Vec<String>>;
/// Represents the selected output of files and contracts
/// The first level key is the file name and the second level key is the
/// contract name. An empty contract name is used for outputs that are
/// not tied to a contract but to the whole source file like the AST.
/// A star as contract name refers to all contracts in the file.
/// Similarly, a star as a file name matches all files.
/// To select all outputs the compiler can possibly generate, use
/// "outputSelection: { "*": { "*": [ "*" ], "": [ "*" ] } }"
/// but note that this might slow down the compilation process needlessly.
///
/// The available output types are as follows:
///
/// File level (needs empty string as contract name):
/// ast - AST of all source files
///
/// Contract level (needs the contract name or "*"):
/// abi - ABI
/// devdoc - Developer documentation (natspec)
/// userdoc - User documentation (natspec)
/// metadata - Metadata
/// ir - Yul intermediate representation of the code before optimization
/// irOptimized - Intermediate representation after optimization
/// storageLayout - Slots, offsets and types of the contract's state
/// variables.
/// evm.assembly - New assembly format
/// evm.legacyAssembly - Old-style assembly format in JSON
/// evm.bytecode.functionDebugData - Debugging information at function level
/// evm.bytecode.object - Bytecode object
/// evm.bytecode.opcodes - Opcodes list
/// evm.bytecode.sourceMap - Source mapping (useful for debugging)
/// evm.bytecode.linkReferences - Link references (if unlinked object)
/// evm.bytecode.generatedSources - Sources generated by the compiler
/// evm.deployedBytecode* - Deployed bytecode (has all the options that
/// evm.bytecode has)
/// evm.deployedBytecode.immutableReferences - Map from AST ids to
/// bytecode ranges that reference immutables
/// evm.methodIdentifiers - The list of function hashes
/// evm.gasEstimates - Function gas estimates
/// ewasm.wast - Ewasm in WebAssembly S-expressions format
/// ewasm.wasm - Ewasm in WebAssembly binary format
///
/// Note that using a using `evm`, `evm.bytecode`, `ewasm`, etc. will select
/// every target part of that output. Additionally, `*` can be used as a
/// wildcard to request everything.
///
/// The default output selection is
///
/// ```json
/// {
/// "*": {
/// "*": [
/// "abi",
/// "evm.bytecode",
/// "evm.deployedBytecode",
/// "evm.methodIdentifiers"
/// ],
/// "": [
/// "ast"
/// ]
/// }
/// }
/// ```
#[derive(Debug, Clone, Eq, PartialEq, Default, Deserialize)]
#[serde(transparent)]
pub struct OutputSelection(pub BTreeMap<String, FileOutputSelection>);
impl OutputSelection {
/// select all outputs the compiler can possibly generate, use
/// `{ "*": { "*": [ "*" ], "": [ "*" ] } }`
/// but note that this might slow down the compilation process needlessly.
pub fn complete_output_selection() -> Self {
BTreeMap::from([(
"*".to_string(),
BTreeMap::from([
("*".to_string(), vec!["*".to_string()]),
("".to_string(), vec!["*".to_string()]),
]),
)])
.into()
}
/// Default output selection for compiler output:
///
/// `{ "*": { "*": [ "*" ], "": [
/// "abi","evm.bytecode","evm.deployedBytecode","evm.methodIdentifiers"] } }`
///
/// Which enables it for all files and all their contracts ("*" wildcard)
pub fn default_output_selection() -> Self {
BTreeMap::from([("*".to_string(), Self::default_file_output_selection())]).into()
}
/// Default output selection for a single file:
///
/// `{ "*": [ "*" ], "": [
/// "abi","evm.bytecode","evm.deployedBytecode","evm.methodIdentifiers"] }`
///
/// Which enables it for all the contracts in the file ("*" wildcard)
pub fn default_file_output_selection() -> FileOutputSelection {
BTreeMap::from([(
"*".to_string(),
vec![
"abi".to_string(),
"evm.bytecode".to_string(),
"evm.deployedBytecode".to_string(),
"evm.methodIdentifiers".to_string(),
],
)])
}
/// Returns an empty output selection which corresponds to an empty map `{}`
pub fn empty_file_output_select() -> FileOutputSelection {
Default::default()
}
}
// this will make sure that if the `FileOutputSelection` for a certain file is empty will be
// serializes as `"*" : []` because
// > Contract level (needs the contract name or "*") <https://docs.soliditylang.org/en/v0.8.13/using-the-compiler.html>
impl Serialize for OutputSelection {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: Serializer,
{
struct EmptyFileOutput;
impl Serialize for EmptyFileOutput {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: Serializer,
{
let mut map = serializer.serialize_map(Some(1))?;
map.serialize_entry("*", &[] as &[String])?;
map.end()
}
}
let mut map = serializer.serialize_map(Some(self.0.len()))?;
for (file, selection) in self.0.iter() {
if selection.is_empty() {
map.serialize_entry(file, &EmptyFileOutput {})?;
} else {
map.serialize_entry(file, selection)?;
}
}
map.end()
}
}
impl AsRef<BTreeMap<String, FileOutputSelection>> for OutputSelection {
fn as_ref(&self) -> &BTreeMap<String, FileOutputSelection> {
&self.0
}
}
impl AsMut<BTreeMap<String, FileOutputSelection>> for OutputSelection {
fn as_mut(&mut self) -> &mut BTreeMap<String, FileOutputSelection> {
&mut self.0
}
}
impl From<BTreeMap<String, FileOutputSelection>> for OutputSelection {
fn from(s: BTreeMap<String, FileOutputSelection>) -> Self {
OutputSelection(s)
}
}
/// Contract level output selection
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub enum ContractOutputSelection {
Abi,
DevDoc,
UserDoc,
Metadata,
Ir,
IrOptimized,
StorageLayout,
Evm(EvmOutputSelection),
Ewasm(EwasmOutputSelection),
}
impl ContractOutputSelection {
/// Returns the basic set of contract level settings that should be included in the `Contract`
/// that solc emits:
/// - "abi"
/// - "evm.bytecode"
/// - "evm.deployedBytecode"
/// - "evm.methodIdentifiers"
pub fn basic() -> Vec<ContractOutputSelection> {
vec![
ContractOutputSelection::Abi,
BytecodeOutputSelection::All.into(),
DeployedBytecodeOutputSelection::All.into(),
EvmOutputSelection::MethodIdentifiers.into(),
]
}
}
impl Serialize for ContractOutputSelection {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: Serializer,
{
serializer.collect_str(self)
}
}
impl<'de> Deserialize<'de> for ContractOutputSelection {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
String::deserialize(deserializer)?.parse().map_err(serde::de::Error::custom)
}
}
impl fmt::Display for ContractOutputSelection {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
ContractOutputSelection::Abi => f.write_str("abi"),
ContractOutputSelection::DevDoc => f.write_str("devdoc"),
ContractOutputSelection::UserDoc => f.write_str("userdoc"),
ContractOutputSelection::Metadata => f.write_str("metadata"),
ContractOutputSelection::Ir => f.write_str("ir"),
ContractOutputSelection::IrOptimized => f.write_str("irOptimized"),
ContractOutputSelection::StorageLayout => f.write_str("storageLayout"),
ContractOutputSelection::Evm(e) => e.fmt(f),
ContractOutputSelection::Ewasm(e) => e.fmt(f),
}
}
}
impl FromStr for ContractOutputSelection {
type Err = String;
fn from_str(s: &str) -> Result<Self, Self::Err> {
match s {
"abi" => Ok(ContractOutputSelection::Abi),
"devdoc" => Ok(ContractOutputSelection::DevDoc),
"userdoc" => Ok(ContractOutputSelection::UserDoc),
"metadata" => Ok(ContractOutputSelection::Metadata),
"ir" => Ok(ContractOutputSelection::Ir),
"ir-optimized" | "irOptimized" | "iroptimized" => {
Ok(ContractOutputSelection::IrOptimized)
}
"storage-layout" | "storagelayout" | "storageLayout" => {
Ok(ContractOutputSelection::StorageLayout)
}
s => EvmOutputSelection::from_str(s)
.map(ContractOutputSelection::Evm)
.or_else(|_| EwasmOutputSelection::from_str(s).map(ContractOutputSelection::Ewasm))
.map_err(|_| format!("Invalid contract output selection: {}", s)),
}
}
}
impl<T: Into<EvmOutputSelection>> From<T> for ContractOutputSelection {
fn from(evm: T) -> Self {
ContractOutputSelection::Evm(evm.into())
}
}
impl From<EwasmOutputSelection> for ContractOutputSelection {
fn from(ewasm: EwasmOutputSelection) -> Self {
ContractOutputSelection::Ewasm(ewasm)
}
}
/// Contract level output selection for `evm`
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub enum EvmOutputSelection {
All,
Assembly,
LegacyAssembly,
MethodIdentifiers,
GasEstimates,
ByteCode(BytecodeOutputSelection),
DeployedByteCode(DeployedBytecodeOutputSelection),
}
impl From<BytecodeOutputSelection> for EvmOutputSelection {
fn from(b: BytecodeOutputSelection) -> Self {
EvmOutputSelection::ByteCode(b)
}
}
impl From<DeployedBytecodeOutputSelection> for EvmOutputSelection {
fn from(b: DeployedBytecodeOutputSelection) -> Self {
EvmOutputSelection::DeployedByteCode(b)
}
}
impl Serialize for EvmOutputSelection {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: Serializer,
{
serializer.collect_str(self)
}
}
impl<'de> Deserialize<'de> for EvmOutputSelection {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
String::deserialize(deserializer)?.parse().map_err(serde::de::Error::custom)
}
}
impl fmt::Display for EvmOutputSelection {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
EvmOutputSelection::All => f.write_str("evm"),
EvmOutputSelection::Assembly => f.write_str("evm.assembly"),
EvmOutputSelection::LegacyAssembly => f.write_str("evm.legacyAssembly"),
EvmOutputSelection::MethodIdentifiers => f.write_str("evm.methodIdentifiers"),
EvmOutputSelection::GasEstimates => f.write_str("evm.gasEstimates"),
EvmOutputSelection::ByteCode(b) => b.fmt(f),
EvmOutputSelection::DeployedByteCode(b) => b.fmt(f),
}
}
}
impl FromStr for EvmOutputSelection {
type Err = String;
fn from_str(s: &str) -> Result<Self, Self::Err> {
match s {
"evm" => Ok(EvmOutputSelection::All),
"asm" | "evm.assembly" => Ok(EvmOutputSelection::Assembly),
"evm.legacyAssembly" => Ok(EvmOutputSelection::LegacyAssembly),
"methodidentifiers" | "evm.methodIdentifiers" | "evm.methodidentifiers" => {
Ok(EvmOutputSelection::MethodIdentifiers)
}
"gas" | "evm.gasEstimates" | "evm.gasestimates" => Ok(EvmOutputSelection::GasEstimates),
s => BytecodeOutputSelection::from_str(s)
.map(EvmOutputSelection::ByteCode)
.or_else(|_| {
DeployedBytecodeOutputSelection::from_str(s)
.map(EvmOutputSelection::DeployedByteCode)
})
.map_err(|_| format!("Invalid evm selection: {}", s)),
}
}
}
/// Contract level output selection for `evm.bytecode`
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub enum BytecodeOutputSelection {
All,
FunctionDebugData,
Object,
Opcodes,
SourceMap,
LinkReferences,
GeneratedSources,
}
impl Serialize for BytecodeOutputSelection {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: Serializer,
{
serializer.collect_str(self)
}
}
impl<'de> Deserialize<'de> for BytecodeOutputSelection {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
String::deserialize(deserializer)?.parse().map_err(serde::de::Error::custom)
}
}
impl fmt::Display for BytecodeOutputSelection {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
BytecodeOutputSelection::All => f.write_str("evm.bytecode"),
BytecodeOutputSelection::FunctionDebugData => {
f.write_str("evm.bytecode.functionDebugData")
}
BytecodeOutputSelection::Object => f.write_str("evm.bytecode.object"),
BytecodeOutputSelection::Opcodes => f.write_str("evm.bytecode.opcodes"),
BytecodeOutputSelection::SourceMap => f.write_str("evm.bytecode.sourceMap"),
BytecodeOutputSelection::LinkReferences => f.write_str("evm.bytecode.linkReferences"),
BytecodeOutputSelection::GeneratedSources => {
f.write_str("evm.bytecode.generatedSources")
}
}
}
}
impl FromStr for BytecodeOutputSelection {
type Err = String;
fn from_str(s: &str) -> Result<Self, Self::Err> {
match s {
"evm.bytecode" => Ok(BytecodeOutputSelection::All),
"evm.bytecode.functionDebugData" => Ok(BytecodeOutputSelection::FunctionDebugData),
"evm.bytecode.object" => Ok(BytecodeOutputSelection::Object),
"evm.bytecode.opcodes" => Ok(BytecodeOutputSelection::Opcodes),
"evm.bytecode.sourceMap" => Ok(BytecodeOutputSelection::SourceMap),
"evm.bytecode.linkReferences" => Ok(BytecodeOutputSelection::LinkReferences),
"evm.bytecode.generatedSources" => Ok(BytecodeOutputSelection::GeneratedSources),
s => Err(format!("Invalid bytecode selection: {}", s)),
}
}
}
/// Contract level output selection for `evm.deployedBytecode`
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub enum DeployedBytecodeOutputSelection {
All,
FunctionDebugData,
Object,
Opcodes,
SourceMap,
LinkReferences,
GeneratedSources,
}
impl Serialize for DeployedBytecodeOutputSelection {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: Serializer,
{
serializer.collect_str(self)
}
}
impl<'de> Deserialize<'de> for DeployedBytecodeOutputSelection {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
String::deserialize(deserializer)?.parse().map_err(serde::de::Error::custom)
}
}
impl fmt::Display for DeployedBytecodeOutputSelection {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
DeployedBytecodeOutputSelection::All => f.write_str("evm.deployedBytecode"),
DeployedBytecodeOutputSelection::FunctionDebugData => {
f.write_str("evm.deployedBytecode.functionDebugData")
}
DeployedBytecodeOutputSelection::Object => f.write_str("evm.deployedBytecode.object"),
DeployedBytecodeOutputSelection::Opcodes => f.write_str("evm.deployedBytecode.opcodes"),
DeployedBytecodeOutputSelection::SourceMap => {
f.write_str("evm.deployedBytecode.sourceMap")
}
DeployedBytecodeOutputSelection::LinkReferences => {
f.write_str("evm.deployedBytecode.linkReferences")
}
DeployedBytecodeOutputSelection::GeneratedSources => {
f.write_str("evm.deployedBytecode.generatedSources")
}
}
}
}
impl FromStr for DeployedBytecodeOutputSelection {
type Err = String;
fn from_str(s: &str) -> Result<Self, Self::Err> {
match s {
"evm.deployedBytecode" => Ok(DeployedBytecodeOutputSelection::All),
"evm.deployedBytecode.functionDebugData" => {
Ok(DeployedBytecodeOutputSelection::FunctionDebugData)
}
"evm.deployedBytecode.object" => Ok(DeployedBytecodeOutputSelection::Object),
"evm.deployedBytecode.opcodes" => Ok(DeployedBytecodeOutputSelection::Opcodes),
"evm.deployedBytecode.sourceMap" => Ok(DeployedBytecodeOutputSelection::SourceMap),
"evm.deployedBytecode.linkReferences" => {
Ok(DeployedBytecodeOutputSelection::LinkReferences)
}
"evm.deployedBytecode.generatedSources" => {
Ok(DeployedBytecodeOutputSelection::GeneratedSources)
}
s => Err(format!("Invalid deployedBytecode selection: {}", s)),
}
}
}
/// Contract level output selection for `evm.ewasm`
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub enum EwasmOutputSelection {
All,
Wast,
Wasm,
}
impl Serialize for EwasmOutputSelection {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: Serializer,
{
serializer.collect_str(self)
}
}
impl<'de> Deserialize<'de> for EwasmOutputSelection {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
String::deserialize(deserializer)?.parse().map_err(serde::de::Error::custom)
}
}
impl fmt::Display for EwasmOutputSelection {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
EwasmOutputSelection::All => f.write_str("ewasm"),
EwasmOutputSelection::Wast => f.write_str("ewasm.wast"),
EwasmOutputSelection::Wasm => f.write_str("ewasm.wasm"),
}
}
}
impl FromStr for EwasmOutputSelection {
type Err = String;
fn from_str(s: &str) -> Result<Self, Self::Err> {
match s {
"ewasm" => Ok(EwasmOutputSelection::All),
"ewasm.wast" => Ok(EwasmOutputSelection::Wast),
"ewasm.wasm" => Ok(EwasmOutputSelection::Wasm),
s => Err(format!("Invalid ewasm selection: {}", s)),
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use std::collections::BTreeMap;
#[test]
fn outputselection_serde_works() {
let mut output = BTreeMap::default();
output.insert(
"*".to_string(),
vec![
"abi".to_string(),
"evm.bytecode".to_string(),
"evm.deployedBytecode".to_string(),
"evm.methodIdentifiers".to_string(),
],
);
let json = serde_json::to_string(&output).unwrap();
let deserde_selection: BTreeMap<String, Vec<ContractOutputSelection>> =
serde_json::from_str(&json).unwrap();
assert_eq!(json, serde_json::to_string(&deserde_selection).unwrap());
}
#[test]
fn empty_outputselection_serde_works() {
let mut empty = OutputSelection::default();
empty.0.insert("contract.sol".to_string(), OutputSelection::empty_file_output_select());
let s = serde_json::to_string(&empty).unwrap();
assert_eq!(s, r#"{"contract.sol":{"*":[]}}"#);
}
}