
\section{Introduction}

With the advent of blockchain\xspace technology as a mainstream technological innovation many researchers and software developers started investigating the new possibilities for software products relying on such infrastructure. Second generation blockchains offer the possibility to code the so called smart-contracts\xspace in a Turing complete programming language where all the main operations of traditional software systems can be carried on. 
The paradigmatic reference is the Ethereum blockchain\xspace which offers the possibility to deploy and execute decentralized applications (dApps) which are mainly coded in Solidity, presently the most adopted programming language \cite{O_Donovan_2019}.
 

Coding smart-contracts\xspace which run in a blockchain\xspace environment has its peculiarities and constraints and differs from coding in traditional out-of-chain contexts~\cite{pierro20}. One of the major differences is the immutability of deployed code, so that if bugs or bad smells are introduced into a smart-contract\xspace these cannot be fixed afterwards with patches. Another contract must be deployed in substitution of the former and users must be well 
advised not to use the wrong code. Another main issue is the interaction with the blockchain\xspace by means of transactions where information exchange can occur only between blockchain\xspace internal components. Furthermore, memory occupation on blockchain typically has a cost that developers want to reduce and 
chaining all the blocks poses limits to the reasonable space available for each smart-contract\xspace imposing practical constraints to source code size~\cite{Murgia2010}. 

This new programming paradigm poses major challenges also to expert developers so that famous failures are commonly found in blockchain\xspace software~\cite{Zheng_2020, 9127445, Murgia12}. 
The novelty of the paradigm largely contributes to these faults, since developers do not have historical records or examples where to learn from previous code, as it happens in traditional software coding, where software reuse and coding by imitation are reference practices to help in coding better quality software. 
Another issue is the lack of reference measures, such as quality, complexity or coupling metrics, which are extensively used in out-of-chain software production to keep software projects under control \cite{Ibba_2018}. 

The situation is slowly changing for what concerns historical records (even if history is quite recent) of software code, since the Ethereum blockchain\xspace can now count on up to 1.5 million deployed smart-contracts\xspace, which have been used and running in the last few years. Access to the source code of this body of smart-contracts\xspace is still a challenge since the transparency and the open access granted by the public blockchains regards only data registered in the blocks, where only contracts' byte-code is available. 

To access the smart-contracts\xspace' source code, the developers must resort to other 
means or to code repositories, such as the classical GitHub or similar resources. 
Fortunately, in the last few years, EtherScan\xspace \footnote{https://etherscan.io/} and other web sites have started providing smart-contracts\xspace checking as a service, so that Ethereum developers 
can submit their source code to be analyzed and the source code is made available afterword by the website.
However, there is an odd side of the medal for many reasons: the access to this body of knowledge is far from easy and far from fast; it is not structured and organized;
the smart-contracts\xspace metrics are not available and must be computed separately~\cite{pierro2019}. All these tasks can and need to be automatized, to save developers' time and work, as well as computational resources. 
Indeed, in the last few years, a number of research papers have been published reporting findings based on smart-contracts\xspace' source code, mined from GitHub or some Ethereum block explorer such as EtherScan\xspace~\cite{Mense2018, Amani2018, Tran19, tonelli2018smart}. However, when conducting this kind of empirical research on smart-contracts\xspace with data from Ethereum blockchain, the tasks above mentioned need to be carried out by the developers themselves.
The first task is the downloading of the smart-contracts\xspace' source code to be analyzed.
One way to download smart-contracts\xspace' source code data is to inspect open-source software (OSS) project repositories such as GitHub~\cite{Jaccheri07, pierro2020gasPrice}. 

Another way to perform this task is to use some Ethereum block explorer. 
These web services allow users to find the desired information by directly accessing the Ethereum blocks, by using a unique identifier or sequentially searching several blocks~\cite{Braga2018}.
Some of these Ethereum block explorers provide RESTful Web services, 
which allow the users to obtain a JSON format payload containing various data. 
These data may be related to a current or past state of the Ethereum blockchain: an example may be the list of transaction addresses included in a given block of the Ethereum blockchain.
This activity might be tedious and time-consuming~\cite{Zhou2005}, when conducted by a single user/developer/researcher.
Furthermore, the obtained smart-contracts\xspace' data-set can consist of duplicated smart contracts, i.e. smart-contracts\xspace having different addresses but with the same code. 

In this work we tackle these problems and propose an organized, easy to use, large and available software repository for Ethereum smart-contracts\xspace source code and metrics where users, researchers, blockchain\xspace start-ups and developers can take advantage of the body of knowledge collected during the last few years. 
This paper thus proposes Smart Corpus\xspace, a repository that provides the users with an interface, which allows to search and download smart contracts' source code. The user interface is available at the following online address: https://aphd.github.io/smac-corpus/.
The main challenge of the implementation lies in the fact that the Ethereum blockchain\xspace stores a massive amount of heterogeneous data, smart-contracts\xspace included, which enormously grow in time.
For this reason, Smart Corpus\xspace was designed to be scalable, by adopting the latest cutting-edge technology, such as document-oriented database, graph query language and serverless computing platform~\cite{Kratzke_2020}.

\section{Related Work}\label{sec:related-work}

\subsection{Previous Literature on Software Corpus Analysis}
Gabel and Su~\cite{Gabel2010} built and studied a corpus of open source software written in three of the most widely used languages: C, C++, and Java. 
The corpus contains six thousand software projects corresponding to 430 million lines of source code. The authors measured the degree to which each project of the corpus can be \dquotes{assembled} solely from portions of the corpus, thus providing a precise measure of \dquotes{uniqueness}. Their primary contribution is to provide a quantitative answer to the following question: \textit{how unique is software?}
Our work also aims to answer this question, because many smart contracts written in the Solidity language have code that is a replication of other smart contracts, although presenting different addresses, as we will see in Section~\ref{sec:cleaning-data}.
Our goal is therefore to answer the question: \textit{how unique are smart contracts written in Solidity?} in order to provide a corpus that is composed by smart contracts which can be distinguished from each other.

Tempero and co-authors~\cite{05693210} presented the "Qualitas Corpus", a curated collection of open-source Java systems. The corpus reduced 
the time needed to find, collect, and organize the necessary source code sets to the time needed to download the corpus. The metadata provided with the corpus explicitly indicates the metrics calculated to identify the main features of the source code: the number of code lines, the number of classes, etc.
Our work also aims to present a curated collection of smart-contracts\xspace equipped with a set of metadata with the aim of allowing experts in the blockchain field to perform static analysis.




\subsection{Static Analysis on Smart Contract Code}
There is a number of scientific publications having as objective the analysis of the smart-contracts\xspace' source code, also testifying the scientific community's interest in advancing the knowledge about the characteristics of smart-contracts\xspace' code structure.

Hegedus~\cite{Hegedus18} developed a metric calculator for Solidity code, inspired by the work by Tonelli and collaborators~\cite{tonelli2018smart}. The metric calculator uses a parser to generate an abstract syntax tree (AST), on which it computes various software metrics, such as the number of code lines for each smart-contract\xspace, the Cyclomatic Complexity, the number of functions, the number of parameters for each function. This command-line tool is written in Java and is available on GitHub without license indication since February 2018~\footnote{https://github.com/chicxurug/SolMet-Solidity-parser}. By using this tool, he calculated and published software metrics results for 10,206 Solidity smart-contracts\xspace source code files written in Solidity languages.
Our work also aims to calculate a set of metadata on the smart-contracts\xspace corpus by using a similar software.

Pinna and colleagues~\cite{Pinna2019AMA} performed a static analysis on 10,174 smart-contracts\xspace, deployed in the Ethereum blockchain.
The authors showed that some metrics related to smart contracts, such as the number of transactions and the balances follow power-law distributions. 
Also, they reported that software code metrics in Solidity have (on average) lower values but higher variance than metrics values in other programming languages for standard softwares. 
Our work is inspired by their research as Smart Corpus\xspace is characterized by (some of) the metrics they defined, as we will explain in Section~\ref{sec:modelling-data}.

Pierro and Tonelli~\cite{PASO} pointed out that even the most experienced users, as software developers of smart contracts are, need to be helped to analyze smart contracts and write a more reliable and secure code. For this reason, an open-source platform~\footnote{https://aphd.github.io/paso/}, called PASO, was proposed as an aid for experts in smart-contracts\xspace' static analysis. Their work focused on Ethereum\xspace blockchain and smart-contracts\xspace written in Solidity\xspace. The platform PASO facilitates the debugging of smart-contracts\xspace by providing software metrics commonly used to comply with coding guidelines.

\subsection{Related Projects}
Other projects, similar to Smart Corpus\xspace, have been previously developed, to online access smart-contracts\xspace' code deployed in the Ethereum blockchain platform.
The projects present specific features and limitations which are summarized in
Table~\ref{tab:related-work}.


\begin{table}[H]
    \caption{Projects' list, main features and limitations}
    \centering
    \label{tab:related-work}
    \def1.3{1.2}
    \begin{tabular}{c|l|l|p{45mm}}
      \textbf{Project's name} & \textbf{Home Page} & \textbf{REST API URL} & \textbf{Limitations} \\
      \hline
      GitHub   
      & \href{https://github.com/}{https://github.com/}  
      & \href{https://docs.github.com/en/free-pro-team@latest/graphql}{https://developer.git...}                                                           
      & Some repositories have restricted access.
      \\
      Ethplorer               
      & \href{https://ethplorer.io/}{https://ethplorer.io/}             
      & \href{https://api.ethplorer.io/getAddressInfo/0xff71cb760666ab06aa73f34995b42dd4b85ea07b?apiKey=freekey}{https://api.ethplorer...} 
      &  Requests are limited to 3000/week.    
      \\
      EtherScan\xspace               
      & \href{https://etherscan.io/}{https://etherscan.io/}             
      & \href{https://etherscan.io/apis}{https://etherscan...}  
      & Smart-contracts\xspace' addresses are not immediately available.
      \\
      EtherChain
      & \href{https://www.etherchain.org/}{https://www.etherch...}
      & \href{https://www.etherchain.org/api/gasPriceOracle}{https://www.etherch...}
      & Smart-contracts\xspace' source code is not available.
      \\
      BlockScout
      & \href{https://blockscout.com/}{https://blockscout.com/}
      & \href{https://blockscout.com/eth/mainnet/api\_docs}{https://blockscout.com...} 
      & Smart-contracts\xspace' source code is not available.
      \\
    \end{tabular}
\end{table}

\subsubsection{GitHub}\label{sec:github}
GitHub is the largest collaborative source code hosting site built on top of the Git version control system~\cite{loeliger2012version}. 
The availability of a comprehensive API has made GitHub a target for many software engineering and online collaboration research efforts~\cite{Gousios2017}.
GitHub offers just open-source software to the community. 
In GitHub, there are many works regarding projects written in different programming languages, such as Java, Python and Solidity, which is by far the most commonly used  language to write smart-contracts.

Some GitHub repository collects smart contracts' source code but such code typically has not a direct reference to smart contracts deployed on the Ethereum blockchain and to a corresponding Ethereum address, and it is had to find out if it has been really tested or used on the blockchain. 
Many smart contracts available on GitHub are there just for testing purpose and not for production and 
in many occasions are only deployed on a test net.
Thus for the purpose of the paper, we collect only smart contracts that are deployed in the main network of the Ethereum blockchain. 
Besides, GitHub lacks some information needed to users to select or filter the smart-contracts, and the researcher might not want to select the smart-contracts' source code randomly or on the basis of their forks or likes number. 
It is highly probable that the users, especially if developers or researchers, want to access smart-contracts' source code having the possibility to choose on the basis of specific software metrics and on its real usage on the blockchain. 

\subsubsection{Ethereum Block Explorers}
\label{sec:ethereum-block-explorers}
Ethereum block explorers are platforms that allow the users to explore and search the Ethereum blockchain for transactions, addresses, tokens and other activities taking place on the Ethereum blockchain~\cite{Bistarelli20}.
Unlike GitHub, the Ethereum block explorers allow accessing only Ethereum data used in the Ethereum blockchain and thus smart contracts' real use-cases. 
To date, in the market, there are different Ethereum block explorers, as for instance:

\begin{itemize}
    \item \textbf{Ethplorer}\footnote{https://ethplorer.io/} provides an API to access many Ethereum data, such as the balances for specified token, the description of a specific address but it does not allow to access to the smart contracts' code.
    The full documentation of the Ethpoler API is available at the following address~\footnote{https://github.com/EverexIO/Ethplorer/wiki/Ethplorer-API}.
    The Requests to API are limited to 5 per second, 50/min, 200/hour, 2000/24hours, 3000/week.
    \item \textbf{EtherChain}\footnote{https://etherchain.org/} is an explorer for the Ethereum blockchain.
    Unlike Ethplorer, it claims to provide smart contract code, even though it actually displays the contract byte-code and the Constructor arguments, for a specific smart contract's address.
    EtherChain provides API just to access the Oracle gas price predictions~\footnote{https://www.etherchain.org/api/gasPriceOracle}, but not the Ethreum data. 
    If the users want to gather Ethereum data from EtherChain, they need to parser the HTML code.
    \item \textbf{BlockScout}\footnote{https://blockscout.com/poa/xdai/} provides an API to access the Ethereum data. 
    It claims to have an API to access only the source code of few verified smart contracts. Anyway the addresses list of the verified smart contracts is not available in BlockScout.
   
    \item \textbf{EtherScan\xspace} allows to explore and search the Ethereum blockchain for smart-contracts. However, when downloading the smart-contracts' source code, the block explorer presents some limitation. First, smart-contracts' data and number are huge (on the Giga scale, based on our estimation), but there is a limited API rate of 100 submissions per day per user to retrieve just a smart contract, making the complete download of the data an impossible endeavour~\footnote{https://etherscan.io/apis\#contracts}. Second, the EtherScan\xspace's API does not provide facilities to obtain a list of the smart-contracts's address, as the existing API calls mainly allow navigation from one block to another. Third, a researcher cannot directly and easily explore the smart-contract's source code, but rather has to first inspect any block in Ethereum and then look for all the transactions that involve an address associated with the smart-contract.
\end{itemize}

\section{Research Methodology}
Smart Corpus\xspace has been designed to provide the users with a reasoned repository, i.e. a repository which is not just a web space where to collect them but also and mainly a service to help the researchers to filter and analyze the Smart contracts' source code. To this aim, Smart Corpus\xspace has been planned to perform four main automatic operations on Smart contracts' source code (data):
\begin{enumerate*}
    \item Data Retrieving,
    \item Data Cleaning,
    \item Data Modelling,
    \item Data Querying.
\end{enumerate*}
Figure~\ref{fig:pipeline-model} shows the Smart Corpus\xspace's pipeline of the operations.

\begin{figure}[H]
    \centering
    {\includegraphics[width=0.9\linewidth]{images/smac-corpus-pipeline-model.png}}
    \caption{Smac-Corpus's pipeline model}
    \label{fig:pipeline-model}
\end{figure} 

\subsection{Retrieving Data}
We collected smart-contracts' source code, smart-contracts' application binary interface (ABI) and smart-contracts' byte-code through the EtherScan\xspace web site, which makes available the source code of a subset of verified smart-contracts\xspace 
deployed on the Etehreum blockchain, though in a laborious way. We instead made this task easier and automatic via a retrieving data script available at the following address~\footnote{https://github.com/aphd/solidity-metrics/tree/master/examples}. 
During this phase the blockchain blocks are automatically inspected.
Each block is formed by a list of transactions between two different blockchain addresses, which can refer to a wallet or to a smart-contract.
The script looks for addresses that refer to a smart-contract and when the source code is available, it downloads the smart-contract's source code, the ABI and the byte-code.
The data coming from the source code are not immediately available as they are embedded in the HTML code of the web page provided by EtherScan\xspace. Therefore, the script removes the HTML tags and stores the code cleaned up.

Figure~\ref{fig:retrieving-data-a} shows how Smart Corpus\xspace finds the smart-contracts' list in a given block. Figure~\ref{fig:retrieving-data-b} shows the HTML page where the smart contract code is available. The HTML page containing the smart contract code and the HTML tags is downloaded. Figure~\ref{fig:retrieving-data-c} shows the HTML code that will be processed to remove the HTML tags and save just the Solidity source code of the smart-contract\xspace.


\begin{figure}[H]
    \begin{subfigure}{.33\textwidth}
        \includegraphics[width=.9\linewidth]{images/retrieving-data-a.png}
        \caption{Transactions' list in a block}
        \label{fig:retrieving-data-a}
    \end{subfigure}%
    \begin{subfigure}{.33\textwidth}
        \includegraphics[width=.9\linewidth]{images/retrieving-data-b.png}
        \caption{Smart contract's webpage code}
        \label{fig:retrieving-data-b}
        \end{subfigure}
    \begin{subfigure}{.33\textwidth}
        \includegraphics[width=.9\linewidth]{images/retrieving-data-c.png}
        \caption{Smart contract's source code}
        \label{fig:retrieving-data-c}
        \end{subfigure}
    \caption{Data Retrieving Pipeline. The figures~\ref{fig:retrieving-data-a},~\ref{fig:retrieving-data-b},~\ref{fig:retrieving-data-c} shows three different phases to retrieve the smart contracts.}
    \label{fig:paso-gui}
\end{figure}

The smart-contracts' code is stored in the filesystem of the Smart Corpus\xspace server. 
Due to the quota limits on queries per second (EtherScan\xspace web site allows few connections per second), Smart Corpus\xspace contains only a portion of all available smart contracts.
However, the retrieving data phase is continuously collecting data, starting from December 10, 2019. 
To date, thirty thousand of smart-contracts (source code, ABI and byte-code) have been downloaded and made available through Smart Corpus\xspace.

\subsection{Cleaning Data}
\label{sec:cleaning-data}
Each smart-contract in the Ethereum blockchain is distinguished from any other smart-contract as it is identified by a unique address, i.e. a hash of 160 bits, and its byte-code is stored on the blockchain~\cite{Chi91}. 
Indeed, each time a smart-contract is deployed in the network, either in the main or in the test network, a unique address is associated with the smart-contract even in the case the source code of two or more smart-contracts is the same. However, this is a problem for the analysis of the software metrics, because the smart-contracts are distinguished only on the basis of their address and not of their content. Therefore, Smart Corpus\xspace eliminates double contracts in order to provide a clean smart-contracts' corpus, where to perform the analysis. To this aim, duplicate smart-contracts\xspace have been defined on the basis of their content, i.e. having the same code despite presenting different address. 

\subsection{Modelling Data}
\label{sec:modelling-data}
Unlike the tools discussed in the related work Section~\ref{sec:related-work}, Smart Corpus\xspace associates different metrics (intrinsic metrics and extrinsic metrics) to the smart-contracts, aiming to facilitate the selection of a smart-contracts' set that meets precise requirements. The metrics associated with the smart-contracts are then stored in a document-oriented database.
Figure~\ref{fig:smac-nosql-schema} shows the database schema of a smart contract.
\begin{figure}[H]
    \centering
    {\includegraphics[width=0.48\linewidth]{images/smac-nosql-schema.png}}
    \caption{Smart-Corpus's database schema}\label{fig:smac-nosql-schema}
\end{figure} 


\subsubsection{Smart Contracts' Intrinsic Metrics}
\label{sec:intrinsic-metrics}
The smart contracts' intrinsic metrics are smart-contracts\xspace' software metrics which depend on internal properties of the smart contracts' code, such as the number of lines of code, modifiers, payable, etc.
Table~\ref{tab:intrinsic-cues} shows the smart-contracts\xspace' intrinsic software metrics.

\begin{table}[H]
        \caption{Smart-contracts' intrinsic metrics}
        \label{tab:intrinsic-cues}
        \centering
        \def1.3{1.3}
        \begin{tabular}{l|p{105mm}}
            \textbf{Name} & \textbf{Description} \\
            \hline
            Pragma & \dquotes{Pragma} indicates version indicates which version of Solidity compiler is used to prevent issues with future compiler versions.\\
            SLOC & \dquotes{SLOC} indicates the number of lines in a smart-contracts\xspace' source code. \\
            Modifiers & \dquotes{Modifiers} indicates the number of function modifiers in a smart-contract\xspace. \\
            Payable & \dquotes{Payable} indicates the number of payable functions in a smart-contract\xspace. \\
            Mapping & \dquotes{Mapping} indicates the number of variables of mapping types in a smart-contract\xspace. \\
            Address & \dquotes{Address} indicates the number of variables of address types in a smart-contract\xspace. \\
        \end{tabular}
\end{table}

\subsubsection{Smart Contract Extrinsic Metric}
\label{sec:extrinsic-metrics}
The smart-contracts\xspace' extrinsic metrics are properties depending on external factors rather than the code itself, such as the number of transactions executed to the smart-contracts or the number of tokens associated with the smart contracts.
Table~\ref{tab:extrinsic-cues} shows the smart-contracts' extrinsic metrics.
\begin{table}[H]
        \caption{Smart-contracts' extrinsic metrics}
        \label{tab:extrinsic-cues}
        \centering
        \def1.3{1.3}
        \begin{tabular}{l|p{105mm}}
            \textbf{Name} & \textbf{Description} \\
            \hline
            Transactions & \dquotes{Transactions} represents the total number of transactions generated by the smart contract (sent or received). \\
            Balance & \dquotes{Balance} is the amount of crypto coins associated with a smart-contract address. \\
            EtherValue & \dquotes{EtherValue} is the dollar value associated with a smart-contract address.\\
            Token & \dquotes{Token} is the value for each token associated with a smart-contract address. \\
            Last\_seen & \dquotes{Last\_seen} is the timestamp of the last time the smart-contract was used (sent or received).\\
            First\_seen & \dquotes{First\_seen} is the timestamp of the first time the smart-contract was used (sent or received).\\
        \end{tabular}
\end{table}

\subsection{Filtered Data}
The smart contracts' source code is stored in a file system and is organized in folders and subfolders to ease the navigation.
Figure~\ref{fig:directory-structure} shows the sub-directory structure.
The first leaf corresponds to the first two letters of the smart contract address and then each directory contains the file having as name the full address of the smart contract and three different extensions, respectively .sol for the Solidity\xspace source code, .abi for the ABI, and .bytecode for the byte code.

\begin{figure}[H]
    \centering
    {\includegraphics[width=0.78\linewidth]{images/directory-structure.png}}
    \caption{Smart-contracts' directory structure.}\label{fig:directory-structure}
\end{figure} 

The metadata (both the intrinsic and extrinsic metrics) are stored in a document-oriented database: MongoDB~\cite{Chodorow2013}. 
The choice to use a Document-oriented database instead of a relational database such as Mysql is based on:
\begin{itemize}
    \item Relational databases are prone to deterioration when data-sets overcome a size threshold, while a document-oriented database such as MongoDB comes with inbuilt load balancer, which makes it a better solution in applications with high data load~\cite{Diogo_2019}. We update MongoDB each day to generate the data archive. 
    \item Unlike relational databases where data is stored in rows and columns, document oriented databases store data in documents. The documents typically use a structure similar to JSON (JavaScript Object Notation), they indeed provide a natural way to model data that is closely aligned with object oriented programming. Each document is considered as an object in object oriented programming, similarly each document is a JSON in document-oriented database. The concept of schema in document databases is dynamic: every document might contain a different number of fields. This is useful when modeling unstructured and polymorphic data. Also, document databases allow robust queries: any combination of fields in the document can be combined for querying data~\cite{Baker_Effendi_2020}. 
\end{itemize}


\subsection{User Interface}
The Smart Corpus\xspace' graphical user interface (GUI) allows users to access the smart-contracts\xspace' repository.
There are two way to access the smart-contracts\xspace' repository: through the \dquotes{HTML user interface} and through a \dquotes{GraphiQL application}, both of them via a Web browser.

\subsubsection{Smart Corpus HTML user interface}
\label{sec:html-gui}
The Smart Corpus\xspace HTML user interface is publicly available since January 2020~\footnote{https://aphd.github.io/smac-corpus/}.
Figure~\ref{fig:html-gui} shows the different components of the GUI.
\begin{itemize}
    \item At the top, the user can find the form where to filter the smart-contracts\xspace. 
    The form is made of a number of drop-down lists, each one corresponding to a different metric and a submit button to perform the research.
    The GUI form allows the user to inspect smart contracts based on some metadata, such as the \dquotes{pragma version}, and software metrics, such as the numbers of \dquotes{modifiers} and/or the numbers of \dquotes{payable}.
    \item Below the form, the smart contracts filtered by the user are displayed. For readability reasons, only a part of the smart-contracts metrics are presented in the table layout format. Each column header in the table indicates the name of a metric associated to smart-contracts. While the HTML-GUI displays just some metrics, the user can access to all the metrics and to the smart-contracts' source code by selecting the checkbox displayed on the right of the smart-contract address and clicking on the red button "download". The user can also access the original repository where the smart-contract was retrieved, i.e. the EtherScan\xspace service.
\end{itemize}

\subsubsection{Smart Corpus\xspace GraphQL application}
\label{sec:graphql-gui}
Graph Query Language (GQL) is a full data query language to implement web-based services, centered on high-level abstractions, such as schemas, types, queries, and mutations. GQL is a domain-specific language internally developed in Facebook from 2012 onward and publicly announced in 2015, with the release of a draft language specification.
The language was conceived with the following goals:
\begin{itemize}
    \item To reduce possible overload of data transfer relative to REST-like web service models, in terms of both the amount of data unnecessarily transferred, and the number of separate queries required to do it.
    \item To reduce the potential of errors caused by invalid queries on the part of the client. In particular, with the GQL application, the user can execute \dquotes{type introspection}, i.e. the user can examine the type or properties of an object at runtime. For example, thanks to the introspection queries the user can find out both the intrinsic and the extrinsic metrics associated with a specific smart-contract\xspace while typing the query.
\end{itemize} 
Figure~\ref{fig:graphql} shows an example query and its result.

\begin{figure}[H]
    \centering
    {\includegraphics[width=0.9\linewidth]{images/graphql.png}}
    \caption{Example with the use of variables to filter a query result with GraphQL.}
    \label{fig:graphql}
\end{figure} 

Smart Corpus\xspace GQL application, unlike the Smart Corpus\xspace HTML user interface
is still in development and testing phase. 
However, the Smart Corpus\xspace GQL application source code is publicly available and can be downloaded and deployed on any platform having the software requirements specified in its documentation~\footnote{https://github.com/aphd/smac-corpus-api}. 

\subsection{Use Case}
A use case for Smart Corpus\xspace might concern a researcher interested in the static analysis of smart contracts. 
For example, the researcher might be interested in performing an analysis of smart-contracts written with a particular version of the Solidity language, 6.0, and having at least a payable function in the smart-contract\xspace.
The research of smart contracts that meets these requirements would be very expensive in terms of time, work and computational resources, using a service like EtherScan\xspace. 
Instead, thanks to the Smart Corpus\xspace, the user needs to perform only a few steps, as described below:
\begin{itemize}
    \item connect to the service through the link: https://aphd.github.io/smac-corpus/
    \item select the option "version 6.0" from the drop-down menu entitled "pragma version".
    \item select the option "greater than zero" from the drop-down menu entitled "number of payables".
    \item submit the form by clicking on the button "submit".
\end{itemize}

After few seconds, depending on the number of smart-contracts that meet the requirements specified by the user, the smart-contracts' addresses and the metrics values will be displayed in a table layout format ready to be downloaded.

\begin{figure}[H]
    \centering
    {\includegraphics[width=0.88\linewidth]{images/html-gui.png}}
    \caption{Smart Corpus\xspace's User Interface}
    \label{fig:html-gui}
\end{figure} 
 











\section{Results}


The Smart Corpus\xspace has been in use for 10 months, since December 2019 and 100K smart contracts have been downloaded via the user interface. 
Until the paper was written (October 2020), Smart Corpus\xspace is a curated corpus of 30K smart-contracts\xspace's source codes, ABI and byte-codes with related metadata and software metrics.
As the time passes, the Smart Corpus\xspace is continuously increasing at a rate of 100 smart contracts per day.
Figure~\ref{fig:trend-plot} shows the number of smart-contracts' source codes, ABI and byte-codes retrieved per day since the Smart Corpus\xspace was deployed for the first time.
For each smart contract Smart Corpus\xspace computed extrinsic and intrinsic metrics, as described in Sections~\ref{sec:extrinsic-metrics} and~\ref{sec:intrinsic-metrics}.

\begin{figure}[H]
    \centering
    {\includegraphics[width=0.88\linewidth]{images/trend-plot.png}}
    \caption{Number of smart-contracts' collected in Smart Corpus\xspace.}
    \label{fig:trend-plot}
\end{figure} 

Summing up, the Smart Corpus\xspace has two GUIs to access data, the HTML GUI and the GraphQL interface.
The HTML GUI is described in Section~\ref{sec:html-gui}, while the GraphQL interface is described in Section~\ref{sec:graphql-gui}.
The GraphQL interface gives blockchain researchers the ability to request for exactly what they need.
The user can directly access the results via GraphQL interface, as shown in Figure~\ref{fig:graphql}. 


Unlike the existing repositories (see Section~\ref{sec:ethereum-block-explorers}) which makes available the source code in a laborious way, 
Smart Corpus\xspace instead made this task easier and faster.
Indeed, one of the advantages of using Smart Corpus\xspace lies in the fact that it can reduce the costs in performing the smart contract static analysis. 
For example, it can be used to easily analyze design and programming patterns for the smart contract programming language.
Smart Corpus\xspace allows to analyze how the industry companies use the Solidity programming language to solve concrete problems in different application areas, such as Healthcare, Insurance, Transportation, Government, Entertainment and Energy.



\section{Conclusions and Future Works}
In this paper, we described the Smart Corpus\xspace project, an effort to bring smart contracts data (source codes, ABIs and byte-codes) to the hands of the research community, providing help for reproducible research and a less time-consuming way to gather data and perform static analysis. 
The project has already stored several megabytes of data, which correspond to about thirty thousand of smart contracts.
This work corresponds to 10 months of data retrieving that are made available to the blockchain scientific community and the blockchain developers in a few seconds.
The Smart Corpus\xspace data-set has strong potential to provide an interesting venue for research in many software engineering areas including, but not limited to, the best practices for Solidity\xspace software development, distributed collaboration, and code paternity and attribution.
The Smart Corpus\xspace project is in its initial stage of development, but it can already provide useful insight for researchers on smart contracts' coding and everyday use in the blockchain\xspace.
The corpus will continue to be expanded in content and in the provision of intrinsic and extrinsic metrics, this becoming more and more representative of the Solidity code actually used in the blockchain\xspace community.

\vspace{6pt} 










