Merge pull request #30 from rvanasa/ryan/dev

Overhaul repository

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @dfinity/dx

.github/workflows/rust.yml → .github/workflows/ci.yml

@@ -1,4 +1,4 @@
-name: Rust
+name: CI
 
 on:
   pull_request:
@@ -8,7 +8,7 @@ on:
     tags:
       - v*
     paths-ignore:
-      - 'README.md'
+      - "README.md"
 jobs:
   cargo-fmt:
     runs-on: ubuntu-latest
@@ -18,14 +18,7 @@ jobs:
       - name: Cargo fmt
         run: |
           rustup component add rustfmt
-          cargo fmt
-      - name: Commit Formatting changes
-        uses: EndBug/add-and-commit@v9
-        if: ${{ github.ref != 'refs/heads/main' }}
-        with:
-          add: src
-          default_author: github_actions
-          message: "🤖 cargo-fmt auto-update"
+          cargo fmt --all -- --check
 
   cargo-clippy:
     runs-on: ubuntu-latest
@@ -41,25 +34,25 @@ jobs:
           cargo clippy -- -D clippy::all -D warnings -A clippy::manual_range_contains
           cargo clippy --tests --benches -- -D clippy::all -D warnings -A clippy::manual_range_contains
 
-  cargo-deny:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@master
-      - run: cargo install --locked cargo-deny
-      - name: Cargo deny
-        run: |
-          cargo-deny check --hide-inclusion-graph || true
+  # cargo-deny:
+  #   runs-on: ubuntu-latest
+  #   steps:
+  #     - name: Checkout
+  #       uses: actions/checkout@master
+  #     - run: cargo install --locked cargo-deny
+  #     - name: Cargo deny
+  #       run: |
+  #         cargo-deny check --hide-inclusion-graph || true
 
-  cargo-audit:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@master
-      - run: cargo install --locked cargo-audit
-      - name: Cargo audit
-        run: |
-          cargo audit || true
+  # cargo-audit:
+  #   runs-on: ubuntu-latest
+  #   steps:
+  #     - name: Checkout
+  #       uses: actions/checkout@master
+  #     - run: cargo install --locked cargo-audit
+  #     - name: Cargo audit
+  #       run: |
+  #         cargo audit || true
 
   cargo-check:
     runs-on: ubuntu-latest
@@ -98,3 +91,25 @@ jobs:
         with:
           command: build
           args: --tests --release --target wasm32-unknown-unknown
+
+  cargo-test:
+    runs-on: ubuntu-latest
+    needs: cargo-check
+    steps:
+      - name: Checkout
+        uses: actions/checkout@master
+
+      - name: Cargo test
+        uses: actions-rs/cargo@master
+        with:
+          command: test
+
+  # candid-check:
+  #   runs-on: ubuntu-latest
+  #   steps:
+  #     - name: Checkout
+  #       uses: actions/checkout@master
+  #     - name: Check interface
+  #       run: |
+  #         cargo run > candid/ic_eth_expected.did
+  #         diff candid/ic_eth.did candid/ic_eth_expected.did

.gitignore

@@ -0,0 +1,2 @@
+.dfx/
+target/

iceth-API.md → API.md

@@ -1,54 +1,57 @@
-# IC Eth API
+# IC 🔗 ETH (Canister API)
 
-## Overview
+## Terminology
 
-*Service, JSON API service:* A Web2 service such as [Infura](https://www.infura.io/), [Gateway.fm](https://gateway.fm/), or [CloudFlare](https://www.cloudflare.com/en-gb/web3/) that offers access to the Ethereum JSON RPC API through HTTP. Note that also other EVM-compatible chains may be covered by such a JSON RPC API.
+* `service`: A Web2 service such as [Infura](https://www.infura.io/), [Gateway.fm](https://gateway.fm/), or [CloudFlare](https://www.cloudflare.com/en-gb/web3/) that offers access to the Ethereum JSON RPC API through HTTP. Note that also other EVM-compatible chains may be covered by such a JSON RPC API.
+* `network`: An EVM blockchain such as the Ethereum mainnet or Sepolia testnet.
+* `chain id`: An EVM network identifier (e.g. `0x1` for the Ethereum mainnet, `0xaa36a7` for the Sepolia testnet). 
+* `provider`: A provider is registered in the canister and allows for connecting to a specific JSON-RPC service. Each chain id for a particular service requires a different provider and typically requires a different API key. Multiple providers can be registered for a service / chain id combination.
 
-*Provider:* A provider is registered in the canister and allows for connecting to a specific JSON API service in the Web2 world. Each chain id for a particular service requires a different provider and typically requires a different API key. Multiple providers can be registered for a service / chain id combination.
-
-*Chain id*: The chain id determines the Ethereum / EVM network to connect to.
-
-## Data Types
+View this [reference site](https://chainlist.org/) for a list of available networks and services. 
 
 ## Methods
 
-### register_provider
+### `register_provider`
 
-Register a new *provider* for a Web2-based *service*.
+Register a new provider for a Web2-based service.
 
-    type RegisterProvider = record {
-        chain_id: nat64;
-        service_url: text;
-        api_key: text;
-        cycles_per_call: nat64;
-        cycles_per_message_byte: nat64;
-    };
+```candid
+type RegisterProvider = record {
+    chain_id: nat64;
+    base_url: text;
+    credential_path: text;
+    cycles_per_call: nat64;
+    cycles_per_message_byte: nat64;
+};
 
-    register_provider: (RegisterProvider) -> ();
+register_provider: (RegisterProvider) -> ();
+```
 
 The `RegisterProvider` record defines the details about the service to register, including the API key for the service.
 * `chain_id`: The id of the Ethereum chain this provider allows to connect to. The ids refer to the chain ids as defined for EVM-compatible blockchains, see, e.g., [ChainList](https://chainlist.org/?testnets=true).
-* `service_url`: The URLs of the Web2 service provider that is used by the canister when using this provider.
-* `api_key`: The API key for authorizing requests to this service provider. The API key is private to the entity registering it and the canister. It is not exposed in the response of the `get_providers` method. The URL used to access the service is constructed by concatenating the `service_url` and the `api_key` (without a seperator), e.g., "https://cloudflare-eth.com" and "/my-api-key").
+* `base_url`: The URLs of the Web2 service provider that is used by the canister when using this provider.
+* `credential_path`: A path containing API key for authorizing requests to this service provider. This part of the path is private to the entity registering it and the canister. It is not exposed in the response of the `get_providers` method. The URL used to access the service is constructed by concatenating the `base_url` and the `credential_path` (without a seperator), e.g., "https://cloudflare-eth.com" and "/my-api-key".
 * `cycles_per_call`: Cycles charged per call by the canister in addition to the base charges when using this provider.
 * `cycles_per_message_byte`: Cycles charged per payload byte by the canister in addition to the base charges when using this provider.
 
 The cycles charged can, for example, be used by the entity providing the API key to amortize the API key costs in the case of commercial API keys. A provider record can be removed by its owner principal or a pricipal with administrative permissions.
 
-### get_providers
+### `get_providers`
 
 Returns a list of currently registered `RegisteredProvider` entries of the canister.
 
-    type RegisteredProvider = record {
-        provider_id: nat64;
-        owner: principal;
-        chain_id: nat64;
-        service_url: text;
-        cycles_per_call: nat64;
-        cycles_per_message_byte: nat64;
-    };
+```candid
+type RegisteredProvider = record {
+    provider_id: nat64;
+    owner: principal;
+    chain_id: nat64;
+    base_url: text;
+    cycles_per_call: nat64;
+    cycles_per_message_byte: nat64;
+};
 
-    get_providers: () -> (vec RegisteredProvider) query;
+get_providers: () -> (vec RegisteredProvider) query;
+```
 
 `vec RegisteredProvider` is a list of providers, each of which represents one provider that has been registered with the canister and corresponds to a registration of an API key for a specific external API service and chain id. A provider entry also contains the cycles price for using this provider, in addition to what is charged for the canister services.
 
@@ -59,45 +62,69 @@ Returns a list of currently registered `RegisteredProvider` entries of the canis
 * `cycles_per_call`: See `RegisterProvider`.
 * `cycles_per_message_byte`: See `RegisterProvider`.
 
-Clients of this canister need to select a provider that matches w.r.t. the `chain_id` the network they intend to connect to. If multiple providers are available for a given `chain_id`, the per-message or per-byte price or the entity behind the provider (this can be inferred from the `service_url`) may be factors to choose a suitable provider.
+Clients of this canister need to select a provider that matches w.r.t. the `chain_id` the network they intend to connect to. If multiple providers are available for a given `chain_id`, the per-message or per-byte price or the entity behind the provider (this can be inferred from the `base_url`) may be factors to choose a suitable provider.
 
-### json_rpc_request
+### `request`
 
 Make a request to a Web2 Ethereum node using the caller's URL to an openly available JSON RPC API service, or the caller's URL including an API key for an access-protected API provider. No registered API key of the canister is used in this scenario.
 
-    json_rpc_request: (json_rpc_payload: text, service_url: text, max_response_bytes: nat64) -> (EthRpcResult);
+    request: (service_url: text, json_rpc_payload: text, max_response_bytes: nat64) -> (EthRpcResult);
 
-* `json_rpc_payload`: The payload for the JSON RPC request, in compliance with the [JSON RPC specification](https://www.jsonrpc.org/specification).
 * `service_url`: The URL of the service, including any API key if required for access-protected services.
+* `json_rpc_payload`: The payload for the JSON RPC request, in compliance with the [JSON RPC specification](https://www.jsonrpc.org/specification).
 * `max_response_bytes`: The expected maximum size of the response of the Web2 API server. This parameter determines the network response size that is charged for. Not specifying it or it being larger than required may lead to substantial extra cycles cost for the HTTPS outcalls mechanism as its (large) default value is used and charged for.
 * `EthRpcResult`: The response comprises the JSON-encoded result or error, see the corresponding type.
 
-### json_rpc_provider_request
+### `provider_request`
 
 Make a request to a Web2 Ethereum node using a registered provider for a JSON RPC API service. There is no need for the client to have any established relationship with the API service.
 
-    json_rpc_provider_request: (json_rpc_payload: text, provider_id: nat64, max_response_bytes: nat64) -> (EthRpcResult);
+    provider_request: (provider_id: nat64, json_rpc_payload: text, max_response_bytes: nat64) -> (EthRpcResult);
+
+* `provider_id`: The id of the registered provider to be used for this call. This uniquely identifies a provider registered with the canister.
+* `json_rpc_payload`: See `request`.
+* `max_response_bytes`: See `request`.
+* `EthRpcResult`: See `request`.
+
+### `request_cost`
+
+Calculate the cost of sending a request with the given input arguments.
+
+    request_cost: (service_url: text, json_rpc_payload: text, max_response_bytes: nat64) -> (nat) query;
+
+* `service_url`: The URL of the service, including any API key if required for access-protected services.
+* `json_rpc_payload`: See `request`.
+* `max_response_bytes`: See `request`.
+
+### `provider_request_cost`
+
+Calculate the cost of sending a request with the given input arguments.
+
+    provider_request_cost: (provider_id: nat64, json_rpc_payload: text, max_response_bytes: nat64) -> (nat) query;
 
-* `json_rpc_payload`: See `json_rpc_request`.
 * `provider_id`: The id of the registered provider to be used for this call. This uniquely identifies a provider registered with the canister.
-* `max_response_bytes`: See `json_rpc_request`.
-* `EthRpcResult`: See `json_rpc_request`.
+* `json_rpc_payload`: See `request_cost`.
+* `max_response_bytes`: See `request_cost`.
 
-### unregister_provider
+### `unregister_provider`
 
 Unregister a provider from the canister. Only the owner of the provider or an admin principal is authorized to perform this action.
 
-    unregister_provider: (provider_id: nat64) -> () ;
+```candid
+unregister_provider: (provider_id: nat64) -> ();
+```
 
 The `provider_id` for the provider to be unregistered is the only parameter required.
 
-### authorize
+### `authorize`
 
 Used for authorizing a principal for certain classes of actions as defined through `Auth`.
 
-    authorize : (principal, Auth) -> ();
+```candid
+authorize : (principal, Auth) -> ();
 
-    type Auth = variant { Rpc; RegisterProvider; Admin };
+type Auth = variant { Rpc; RegisterProvider; Admin };
+```
 
 The `Auth` variant defines the following cases:
 * `Rpc`: Governs access control to the RPC methods.