ethereum-emissions-calculator - npm Package Compare versions

Comparing version 1.5.0 to 1.6.0

lib/index.d.ts

@@ -53,2 +53,9 @@ /** This is the API response for a normal, internal, token or NFT transaction query */
 }
+/**
+ * Calculate emissions of an address. Emissions are allocated for SENT (outgoing) transactions only.
+ */
 export declare const calculateAddressEmissions: (options: CalculatorOptions) => Promise<AddressEmissionsResult>;
+/**
+ * Calculate emissions of a contract address. Emissions are allocated for BOTH outgoing AND incoming transactions.
+ */
+export declare const calculateContractEmissions: (options: CalculatorOptions) => Promise<AddressEmissionsResult>;

lib/index.js

@@ -15,6 +15,7 @@ "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.calculateAddressEmissions = void 0;
+exports.calculateContractEmissions = exports.calculateAddressEmissions = void 0;
 const constructEtherscanURL_1 = __importDefault(require("./utils/constructEtherscanURL"));
 const fetchJSON_1 = __importDefault(require("./utils/fetchJSON"));
 const filterValidOutgoingTransactions_1 = __importDefault(require("./utils/filterValidOutgoingTransactions"));
+const filterValidTransactions_1 = __importDefault(require("./utils/filterValidTransactions"));
 const getSumGasUsed_1 = __importDefault(require("./utils/getSumGasUsed"));
@@ -28,2 +29,5 @@ const validateCalculatorOptions_1 = __importDefault(require("./utils/validateCalculatorOptions"));
 const KG_CO2_PER_GAS = 0.0003487183523;
+/**
+ * Calculate emissions of an address. Emissions are allocated for SENT (outgoing) transactions only.
+ */
 const calculateAddressEmissions = (options) => __awaiter(void 0, void 0, void 0, function* () {
@@ -56,1 +60,31 @@ validateCalculatorOptions_1.default(options);
 exports.calculateAddressEmissions = calculateAddressEmissions;
+/**
+ * Calculate emissions of a contract address. Emissions are allocated for BOTH outgoing AND incoming transactions.
+ */
+const calculateContractEmissions = (options) => __awaiter(void 0, void 0, void 0, function* () {
+    validateCalculatorOptions_1.default(options);
+    const response = yield fetchJSON_1.default(constructEtherscanURL_1.default(options));
+    if (response.status === "0" && response.message === "No transactions found") {
+        return {
+            transactionType: options.transactionType,
+            kgCO2: 0,
+            transactionsCount: 0,
+            gasUsed: 0,
+        };
+    }
+    if (response.status !== "1") {
+        throw new Error(`Failed to calculate contract emissions: ${response.message}`);
+    }
+    if (response.result.length >= 10000) {
+        throw new Error(`This contract has too many ${options.transactionType} transactions to count! This calculator can't handle addresses with more than 10,000 transactions of any one type.`);
+    }
+    const txns = filterValidTransactions_1.default(response.result);
+    const totalGasUsed = getSumGasUsed_1.default(txns);
+    return {
+        transactionType: options.transactionType,
+        kgCO2: Math.round(totalGasUsed * KG_CO2_PER_GAS),
+        transactionsCount: txns.length,
+        gasUsed: totalGasUsed,
+    };
+});
+exports.calculateContractEmissions = calculateContractEmissions;

package.json

 {
   "name": "ethereum-emissions-calculator",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "TypeScript utils to calculate the CO2 emissions of an Ethereum wallet. Powered by the Etherscan.io API.",
@@ -5,0 +5,0 @@ "main": "./lib/index.js",

README.md

@@ -9,5 +9,7 @@ # Ethereum Carbon Emissions Calculator
 
+Questions, comments, forks and PRs all very much appreciated!
+
 ## Summary
 
-JavaScript utility to calculate the CO2 emissions of any Ethereum address.
+JavaScript utility to calculate the CO2 emissions of any Ethereum address or contract.
 
@@ -17,8 +19,5 @@ The tool is written in TypeScript and powered by the the Etherscan.io API & an open-source carbon accounting methodology under development by Offsetra.
 
-Questions, comments, forks and PRs all very much appreciated!
-
 ## Usage
 
-NOTE: Currently this calculator can only tally emissions for <10k transactions, which is the API page limit from Etherscan.io.
-If the address has >10k transactions of the specified transaction type (eth/erc20/erc721), the function will throw an error.
+This calculator should work in any client or server-side JavaScript environment.
 
@@ -29,5 +28,14 @@ ```
 
-Provide an address and a transaction type, and the calculator will tell you how many emissions this represents in KG CO2e.
-To calculate the sum total of your addresses' lifetime emissions, you must combine the sum of `eth`, `erc20`, and `erc721` emissions.
+The calculator exports two methods:
 
+- `calculateAddressEmissions`
+- `calculateContractEmissions`
+
+### calculateAddressEmissions
+
+`calculateAddressEmissions` will only allocate emissions for outgoing (sent) transactions.
+
+Provide an `address` and a `transactionType`, and the calculator will tell you how many emissions this represents in KG CO2e.
+To calculate the sum total emissions for an address, you must combine the sum of `eth`, `erc20`, and `erc721` emissions.
+
 ```typescript
@@ -52,7 +60,31 @@ import { calculateAddressEmissions } from "ethereum-emissions-calculator";
 
+### calculateContractEmissions
+
+The only difference between this method and `calculateAddressEmissions`, is that this method will also calculate and add emissions from _incoming_ transactions.
+We have included this method at the request of platforms who are interested in calculating the collective impact of their contract, however for most cases we think `calculateAddressEmissions` makes more sense (to avoid double-counting the same emissions-- sender takes responsibility!)
+
+```typescript
+import { calculateContractEmissions } from "ethereum-emissions-calculator";
+import { address, etherscanAPIKey } from "data";
+
+const emissions = await calculateContractEmissions({
+  transactionType: "eth", // "eth" | "erc20" | "erc721"
+  address, // 0x12345[...]
+  etherscanAPIKey,
+});
+
+console.log(emissions);
+// {
+//   transactionType: "eth",
+//   kgCO2: 12345`,
+//   transactionsCount: 69,
+//   gasUsed: 420,
+// }
+```
+
 ## Methodology
 
-Emissions are calculated based on the transactions initiated (sent) by the provided address.
 The total emissions are derived from the amount of `gas` used for each transaction.
+See https://carbon.fyi/learn for a brief intro and link to more in-depth explainers.
 
-More on this coming soon!
+We would like to integrate the actuall carbon accounting methodology and hash-rate calculations into this repository at some point in the near future. Let us know if you'd like to put in a PR to help us along!

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

17793

increased by28.26%

Number of package files

17

increased by13.33%

Lines of code

272

increased by28.91%

Number of lines in readme file

87

increased by58.18%

No dependency changes