Added Javadoc in Bridge and xEVMLiSA classes

Author: merendamattia

src/main/java/it/unipr/crosschain/Bridge.java

@@ -35,18 +35,53 @@ public class Bridge implements Iterable<SmartContract> {
 	/** Detected vulnerabilities in the bridge. */
 	private VulnerabilitiesObject _vulnerabilities;
 
+	/**
+	 * Creates a new Bridge instance with only a name.
+	 *
+	 * @param name the name of the bridge
+	 */
 	public Bridge(String name) {
 		this(null, null, null, name);
 	}
 
+	/**
+	 * Creates a new Bridge instance with bytecode and ABI directories, and
+	 * policy path. The bridge name will be auto-generated with a timestamp.
+	 *
+	 * @param bytecodeDirectoryPath path to the directory containing bytecode
+	 *                                  files
+	 * @param abiDirectoryPath      path to the directory containing ABI files
+	 * @param policyPath            path to the policy JSON file
+	 */
 	public Bridge(Path bytecodeDirectoryPath, Path abiDirectoryPath, Path policyPath) {
 		this(bytecodeDirectoryPath, abiDirectoryPath, policyPath, "unknown_bridge_" + System.currentTimeMillis());
 	}
 
+	/**
+	 * Creates a new Bridge instance with bytecode and ABI directories. No
+	 * policy will be loaded and the bridge name will be auto-generated.
+	 *
+	 * @param bytecodeDirectoryPath path to the directory containing bytecode
+	 *                                  files
+	 * @param abiDirectoryPath      path to the directory containing ABI files
+	 */
 	public Bridge(Path bytecodeDirectoryPath, Path abiDirectoryPath) {
 		this(bytecodeDirectoryPath, abiDirectoryPath, null, "unknown_bridge_" + System.currentTimeMillis());
 	}
 
+	/**
+	 * Creates a new Bridge instance with all specified parameters. This is the
+	 * main constructor that initializes the bridge with smart contracts from
+	 * the provided bytecode and ABI directories, loads the policy if specified,
+	 * and assigns the given name.
+	 *
+	 * @param bytecodeDirectoryPath path to the directory containing bytecode
+	 *                                  files
+	 * @param abiDirectoryPath      path to the directory containing ABI files
+	 * @param policyPath            path to the policy JSON file, or null if no
+	 *                                  policy should be loaded
+	 * @param name                  the name to assign to this bridge
+	 */
 	public Bridge(Path bytecodeDirectoryPath, Path abiDirectoryPath, Path policyPath, String name) {
 		this.name = name;
 		this.contracts = new ArrayList<>();
@@ -71,50 +106,99 @@ public Bridge(Path bytecodeDirectoryPath, Path abiDirectoryPath, Path policyPath
 
 	}
 
+	/**
+	 * Gets the name of the bridge.
+	 *
+	 * @return the name of the bridge
+	 */
 	public String getName() {
 		return name;
 	}
 
+	/**
+	 * Gets the list of smart contracts in this bridge.
+	 *
+	 * @return a list of SmartContract objects
+	 */
 	public List<SmartContract> getSmartContracts() {
 		return contracts;
 	}
 
+	/**
+	 * Gets all function signatures from all contracts in this bridge.
+	 *
+	 * @return a list of function signatures
+	 */
 	public List<Signature> getFunctions() {
 		List<Signature> functions = new ArrayList<>();
 		for (SmartContract contract : contracts)
 			functions.addAll(contract.getFunctionsSignature());
 		return functions;
 	}
 
+	/**
+	 * Gets all event signatures from all contracts in this bridge.
+	 *
+	 * @return a list of event signatures
+	 */
 	public List<Signature> getEvents() {
 		List<Signature> events = new ArrayList<>();
 		for (SmartContract contract : contracts)
 			events.addAll(contract.getEventsSignature());
 		return events;
 	}
 
+	/**
+	 * Gets the cross-chain control flow graph (xCFG) of this bridge.
+	 *
+	 * @return the EVMCFG representing the cross-chain control flow graph
+	 */
 	public EVMCFG getXCFG() {
 		return xCFG;
 	}
 
+	/**
+	 * Gets the cross-chain policy containing event-function pairs.
+	 *
+	 * @return a list of event-function pairs
+	 */
 	public List<Pair<String, String>> getPolicy() {
 		return policy;
 	}
 
+	/**
+	 * Checks if an event has an associated function in the policy.
+	 *
+	 * @param event the name of the event to check
+	 *
+	 * @return true if the event has an associated function, false otherwise
+	 */
 	public boolean hasEventFunctionMapping(String event) {
 		for (Pair<String, String> pair : policy)
 			if (pair.getLeft().equals(event))
 				return true;
 		return false;
 	}
 
+	/**
+	 * Gets the function name associated with an event from the policy.
+	 *
+	 * @param event the name of the event
+	 *
+	 * @return the associated function name, or null if not found
+	 */
 	public String getFunctionForEvent(String event) {
 		for (Pair<String, String> pair : policy)
 			if (pair.getLeft().equals(event))
 				return pair.getRight();
 		return null;
 	}
 
+	/**
+	 * Adds multiple cross-chain edges to the xCFG.
+	 *
+	 * @param edges a set of edges to be added
+	 */
 	public void addEdges(Set<Edge> edges) {
 		for (Edge edge : edges)
 			addEdge(edge);
@@ -141,6 +225,11 @@ public Bridge setVulnerabilities(VulnerabilitiesObject vulnerabilities) {
 		return this;
 	}
 
+	/**
+	 * Adds a single cross-chain edge to the xCFG.
+	 *
+	 * @param edge the edge to be added
+	 */
 	public void addEdge(Edge edge) {
 		xCFG.addEdge(edge);
 	}
@@ -176,6 +265,13 @@ public EVMCFG buildPartialXCFG() {
 		return xCFG;
 	}
 
+	/**
+	 * Loads the cross-chain policy from a JSON file and populates the policy
+	 * list. The JSON file should contain an array named "policy" with
+	 * event-function pairs.
+	 *
+	 * @param policyPath the path to the policy JSON file
+	 */
 	private void loadPolicy(Path policyPath) {
 		try {
 			log.info("Loading policy from: {}", policyPath);
@@ -286,6 +382,11 @@ public String toString() {
 		return toJson().toString(4);
 	}
 
+	/**
+	 * Returns an iterator over the smart contracts in this bridge.
+	 *
+	 * @return an Iterator over SmartContract objects
+	 */
 	@Override
 	public Iterator<SmartContract> iterator() {
 		return contracts.iterator();

src/main/java/it/unipr/crosschain/xEVMLiSA.java

@@ -35,6 +35,16 @@
 public class xEVMLiSA {
 	private static final Logger log = LogManager.getLogger(xEVMLiSA.class);
 
+	/**
+	 * Main entry point for running cross-chain analysis on a bridge. This
+	 * method configures EVMLiSA, creates a bridge from the provided paths,
+	 * analyzes it, runs cross-chain checkers, and prints the results.
+	 *
+	 * @param bytecodeDirectoryPath path to the directory containing bytecode
+	 *                                  files
+	 * @param abiDirectoryPath      path to the directory containing ABI files
+	 * @param policyPath            path to the policy JSON file
+	 */
 	public static void runAnalysis(Path bytecodeDirectoryPath, Path abiDirectoryPath, Path policyPath) {
 		EVMLiSA.setLinkUnsoundJumpsToAllJumpdest();
 		EVMLiSA.setCores(Runtime.getRuntime().availableProcessors() - 1);
@@ -130,6 +140,18 @@ public static Set<Edge> getCrossChainEdgesUsingEventsAndFunctionsEntrypoint(Brid
 		return crossChainEdges;
 	}
 
+	/**
+	 * Applies the cross-chain policy to determine if an event should be linked
+	 * to a function. If no policy is provided, it defaults to matching events
+	 * and functions by name.
+	 *
+	 * @param policy   the list of event-function pairs from the policy
+	 * @param event    the event signature to match
+	 * @param function the function signature to match
+	 *
+	 * @return true if the event should be linked to the function according to
+	 *             the policy
+	 */
 	public static boolean applyPolicy(List<Pair<String, String>> policy, Signature event, Signature function) {
 		if (policy == null || policy.isEmpty())
 			return event.getName().equalsIgnoreCase(function.getName());