# eth-adapter

> An ethereum adapter/transpiler to make interacting wirth smart contracts wicked simple

Latest version **1.0.7** (published 2024-08-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install eth-adapter
pnpm add eth-adapter
yarn add eth-adapter
bun add eth-adapter
```

Provides the commands `ethpst`, `ethinit`.

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.7 |
| Published | 2024-08-21 |
| First published | 2022-11-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 7 |
| Unpacked size | 70.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | ACatThatPrograms |
| Maintainers | acatthatprograms |

## Links

- npm: https://www.npmjs.com/package/eth-adapter
- npm.io page: https://npm.io/package/eth-adapter

## Dependencies (7)

- [tslib](https://npm.io/package/tslib.md) 2.4.1
- [dotenv](https://npm.io/package/dotenv.md) 16.0.3
- [ethers](https://npm.io/package/ethers.md) 5.7.2
- [rollup](https://npm.io/package/rollup.md) ^4.21.0
- [typescript](https://npm.io/package/typescript.md) ^4.9.5
- [@types/node](https://npm.io/package/@types/node.md) 18.11.9
- [@rollup/plugin-typescript](https://npm.io/package/@rollup/plugin-typescript.md) 11.1.6

## Recent versions

- 1.0.7 (latest) — 2024-08-21
- 1.0.6 — 2024-08-21
- 1.0.5 — 2024-08-21
- 1.0.4 — 2023-04-03
- 1.0.3 — 2023-03-31
- 1.0.2 — 2023-03-31
- 1.0.1 — 2023-03-29
- 0.0.13 — 2023-01-26
- 0.0.12 — 2023-01-26
- 0.0.11 — 2023-01-26
- 0.0.10 — 2022-11-30
- 0.0.9 — 2022-11-22
- 0.0.8 — 2022-11-13
- 0.0.7 — 2022-11-12
- 0.0.6 — 2022-11-11
- … 1 more at https://npm.io/package/eth-adapter/versions

## README

# eth-adapter :electric_plug:

Ethereum development made easier, interact with smart contracts instantly.

### What this library helps with: :check:

- Reduce need for writing complex wrapper functions to call `ethers.js` or `web3.js`
- Reduce complexity around how to interact with smart contracts.
- Provided typed parameters for the generated functions based on your ABI:

![auto_complete_demo](https://raw.githubusercontent.com/ACatThatPrograms/eth-adapter/main/readme_img/auto_complete.png)
#### Additionally

- Exposes ethers on `ethAdapter.ethers` if you need it
- Exposes all loaded contract configuration under `ethAdapter.contractConfig`

# About :grey_question:	

eth-adapter is a high level abstraction for interacting with deployed smart contracts through a web3 provider like Metamask.

Would you like to interact with smartcontracts like this:

```
// If you want to use metamask / injected web3
await ethAdapter.connectToWeb3Wallet();

// OR, just use a JSON Rpc Provider
ethAdapter.setJsonRpcProvider() // Used by default if you don't use connectToWeb3Wallet()

let storedInt = await ethAdapter.contractMethods.STORAGE.retrieve_view_IN0_OUT1();
if (storedInt.error) {
    // ...Handle it
}

// Else... you have storedInt now, conquer the world!
```

If the above looks pleasing, this library is for you!

# How do I use it? :wrench:

## Setup :sewing_needle:	

1. `npm install eth-adapter` | `yarn add eth-adapter`
2. Compile a contract and get those artifact files as a `.json` file, ours is `Storage.json`
3. Drop them in your project in a new root `/artifacts` folder
   - Take note of the names, they're important. We have a **Storage.json** for example
4. Create a .env file and add your contract with an address
   `CONTRACT_ADDRESS_STORAGE=0x0`
   - If you use React, the library will also parse REACT_APP_ environment keys
   - The name should be uppercased here without the .json so **STORAGE**
5. Run 'ethpst' a bin provided by this library 
    - For React projects it is advised to edit start/build/test to have `ethpst;` preceed them:
  ```
      "scripts": {
        "start": "npx ethpst; react-scripts start",
        "build": "npx ethpst; react-scripts build",
        "test": "npx ethpst; react-scripts test",
        "eject": "react-scripts eject" // Not needed here
    }
  ```
  - The _Ethereum Pre-Start-Transpiler_ (ethpst) should be ran anytime the abi's are updated

### For CJS / ES5 compile:

If you wish to use this inside node as ES5 and not ES6 modules, you can compile to cjs by including the following .env parameter in your project root:

`ETH_ADAPTER_USE_CJS="TRUE"`

* A false .env does not need to be included for ES6 Module compiling, it is the default

## Calling Contracts :incoming_envelope:	

This is the easy part:

```
// Import ethAdapter
import ethAdapter from 'eth-adapter`

// Set the JSON Rpc Provider
ethAdapter.setJsonRpcProvider("https://localhost:8545); 

// All methods are available on ethAdapter.contractMethods broken down by 'CONTRACTNAME' and have generated types for IntelliSense friendliness
let storedInt = await ethAdapter.contractMethods.STORAGE.retrieve_view_IN0_OUT1();
```

Remember:

- Parameters for contract methods must be passed as destructured objects as `{paramName:value}`
- Functions are named with IN/OUT counts to provide access to overloaded functions

## More Functionality :gear:	

EthAdapter has some inbuilts for basic things, but also gives you direct access to ethers if you need it through `ethAdapter.ethers`

EthAdapter exposes all of the compiled contract configuration at `ethAdapter.contractConfig` this allows you to get the compiled information on your contract within the context ethAdapter sits in.

### Additional Methods

### **setOnNetworkChangeFunction(onNetworkFunction = (networkId: number) => {})**

Update the function to be ran anytime the network is updated on the provider
### **setOnAccountChangeFunction(onAccountChangeFunction = (activeAccount: string) => {})**

Update the function to be ran anytime the active account is changed on the provider
#### **setEqualizeFunction( () => {} )**

This function is used for the changing the function that is ran everytime ethAdapter changes it's own instance state. This can be beneficial if you integrate EthAdapter into a state management system such as redux.

#### **setJsonRpcProvider(url: string)**

Sets the JsonRPCProvider to be used by EthAdapter.

If you run this *after* connecting a web3 wallet, you will overwrite the injected provider.

#### **connectToWeb3Wallet( () => {})**

Used to connect to the injected web3 wallet. Callback is called with `{error: msg}` as the first parameter if there is a problem connecting or `{}` if successful.

#### **getAddressByIndex(accountIdx: int)**

Get the address by index for the connected provider

#### **updateEthereumBalance(accountIdx: int)** 

Updates the ethAdapter.balances state with the latest ETH balance for a connected address

#### **signSimpleStringMsg(msg: string)**

Attempts to sign a simple message with signer.signMessage()

#### **signBytes (bytes: string)**

Attempts to sign bytes with signMessage

#### **_getReadonlyContractInstance(contractName: string)**

Will get an ethers read instance using the current provider of the CONTRACT_NAME as noted in the .env

`let storageInstance = await _getReadonlyContractInstance("STORAGE");`

#### **_getSignerContractInstance(contractName: string)**

Will get an ethers read instance using the current signer of the CONTRACT_NAME as noted in the .env

`let storageInstance = await _getSignerContractInstance("STORAGE");`

## Development & Additional Info

Development of eth-adapter is slightly agaianst the grain as the package itself actually gets compiled on site, the package consists of mainly scripts and tooling to convert existing templates into a a customed eth adapter.

## Issues

Please submit issues/feature requests as needed

---
_Source: https://npm.io/package/eth-adapter · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._