add aws signer docs (#2795)

---------

Co-authored-by: Trajan0x <[email protected]>

docker/signer-example.Dockerfile

@@ -0,0 +1,15 @@
+FROM gcr.io/distroless/static:latest
+
+LABEL org.label-schema.description="signer-example Docker Image"
+LABEL org.label-schema.name="ghcr.io/synapsecns/sanguine/contrib/signer-example"
+LABEL org.label-schema.schema-version="1.0.0"
+LABEL org.label-schema.vcs-url="https://github.com/synapsecns/sanguine"
+LABEL org.opencontainers.image.source="https://github.com/synapsecns/sanguine"
+LABEL org.opencontainers.image.description="signer-example Docker image"
+
+USER nonroot:nonroot
+
+WORKDIR /app
+COPY --chown=nonroot:nonroot signer-example /app/signer-example
+
+ENTRYPOINT ["/app/signer-example"]

docs/bridge/docs/Services/Signer.md

@@ -1,3 +1,136 @@
 # Signer
 
+## Setup with AWS KMS
+
+In order to setup the signer with AWS KMS, you will need to create a KMS key and give the appropriate permissions to a user that will be using the signer. While we do not have IAC (Infrastructure as Code) for this, you can follow the steps below to setup the KMS key and the user.
+
+**Note**: If you already have an IAM user you can skip to the [Create a KMS Key](#create-a-kms-key) section. If you have a custom IAM setup/role skip this and assign the permissions to the user or role you want to use.
+
+### Create an IAM User
+
+1. Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam.
+![IAM Dashboard](img/iam-dash.png)
+
+2. Click on `Users` in the left-hand menu and then click on `Add user`.
+
+![Create User](img/kms-user.png)
+
+3. Leave Permissions empty and click `Next`
+
+![img.png](img/perms.png)
+
+4. Add tags if you want and click `Create User`
+
+![IAM Preview User](img/iam-preview-user.png)
+
+5. The user will be create and appear in the list of users. Click on the user to view the user details.
+
+![User List](img/user-list.png)
+
+6. Click on 'Create access key'.
+
+<details>
+  <summary>Important Note</summary>
+<p>
+In the example above, we use access keys & secrets to authenticate the user. This is not recommended for production use. There are a lot of ways to authenticate users in AWS and the "Best Practices & alternatives" page below will tell you the best way to authenticate. Since we're only covering access key & secret, we'll ignore these other methods. The AWS documentation is very good and you can find more information on the best practices & alternatives [here](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html).
+</p>
+</details>
+
+
+7. Skip the description page
+
+![user-perms.png](img/user-perms.png)
+
+8. Click on `Create access key`
+
+![Create Access Key](img/create-acces-key.png)
+
+Note down the `Access key ID` and `Secret access key` as you will need these to configure the signer.
+
+### Create a KMS Key
+1. Sign in to the AWS Management Console and open the KMS console at https://console.aws.amazon.com/kms.
+
+![KMS Key](img/kms-1.png)
+
+2. Choose `Create key` and fill in the following options:
+
+![Create Key](img/kms-2.png)
+
+- Key Type: `Asymmetric`: Since ethereum uses [ECDSA](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm) keys, we need to use an asymmetric key.
+- Key Usage: `Sign and verify`: We will be using the key to sign transactions so we select this option.
+- Key Spec: `ECC_SECG_P256K1`: Ethereum uses the [`secp256k1`](https://en.bitcoin.it/wiki/Secp256k1) curve for transacting keys.
+
+Note: The advanced options are not required for this setup. You can leave them as default:
+
+![Advanced Options](img/kms-advanced.png)
+
+3. Choose `Next` and fill in the following options:
+
+![KMS Creation Step 2](img/kms-labels.png)
+
+- Alias: This is an alias that will be used to reference the key in the signer. The field is required but the value doesn't matter.
+- Description: This is a description that will be used to describe the key in the signer. This is only optional and only for your reference.
+- Tags: These are tags that will be used to describe the key in the signer. These are optional and only for your reference.
+
+4. Choose `Next` and define your key admin permissions. These are *not* required by the signer itself but are required to manage the key. You can use whatever you like here.
+
+![KMS Permissions](img/kms-permissons.png)
+
+5. Choose `Next` and define your user permissions. Here you should set your user as a user.
+
+![KMS User Permissions](img/kms-user-permissions.png)
+
+6. Choose `Next` and review your key settings. If everything looks good, choose `Finish`.
+
+![Review](img/review.png)
+
+7. Your key will be created and you will be redirected to the key details page. Note down the `Key ID` as you will need this to configure the signer.
+
+8. You will be redirected to the key details page. Click on the key alias to view the key details.
+
+![Key Details](img/key-details.png)
+
+9. Using Your Key (AWS)
+
+Now that you have your key and user setup, you can use the key to sign transactions. Since the `signerconfig` is used across multiple services, I'll be doing a generic example that just prints out the key.
+
+Note: this is a very basic example and you should not use this in production. You should store your key in a secure location and use it securely.
+
+
+`signer.yml`:
+```yaml
+signer_config:
+  type: "aws"
+  file: "/path/to/aws.yaml"
+```
+
+`aws.yaml`:
+```yaml
+region: us-east-1
+access_key: YOUR_ACCESS_KEY
+access_secret: YOUR_ACCESS_SECRET
+key_id: f15fa759-7c13-44eb-a868-e7388aa1387b # this will be the id from above.
+```
+
+This is obviously used in multiple services, so we've put together an example service that will print out the address of your key.
+
+You can run this locally by running:
+
+```bash
+brew install go # if on mac
+git clone https://github.com/synapsecns/sanguine --recurse-submodules
+cd sanguine/ethergo/examples/signer
+go run main.go --config=/path/to/signer.yml
+```
+
+We also have this available as a docker container for your convenience here:
+
+`ghcr.io/synapsecns/sanguine/signer-example:latest`
+
+## Setup with GCP CloudKMS
+
+This section is still in progress, please see [here](https://pkg.go.dev/github.com/synapsecns/sanguine/[email protected]/signer/signer#section-readme) for details.
+
+## Setup with a Local Signer
+
 This section is still in progress, please see [here](https://pkg.go.dev/github.com/synapsecns/sanguine/[email protected]/signer/signer#section-readme) for details.

ethergo/.goreleaser.yml

@@ -5,7 +5,46 @@ monorepo:
   dir: ethergo/
 
 builds:
-  - skip: true
+  # Linux AMD64
+  - id: signer-example
+    binary: api
+    ldflags:
+      # We need to build a static binary because we are building in a glibc based system and running in a musl container
+      - -s -w -extldflags '-static'
+    # required workaround for https://github.com/Shopify/sarama/issues/2206
+    # See: https://github.com/golang/go/issues/35067#issuecomment-544805311 because we're statically compiling,
+    # without forcing netgo, we use the cgo resolver which will not work for .local (a canonical tld in kubernetes)
+    # the other way to resolve this would be to modify the nsswitch.conf in the container, but that's a bit less clean.
+    # osusergo was included as a recommendation here: https://github.com/kubernetes/kubernetes/pull/114225#issuecomment-1348920040
+    tags:
+      - netgo
+      - osusergo
+    env:
+      - CC=gcc
+      - CXX=g++
+    main: examples/signer-example/main.go
+    goos:
+      - linux
+    goarch:
+      - amd64
+
+dockers:
+  # Docker AMD64
+  - goos: linux
+    goarch: amd64
+    image_templates:
+      - 'ghcr.io/synapsecns/sanguine/signer-example:latest'
+      - 'ghcr.io/synapsecns/sanguine/signer-example:{{ .FullCommit }}'
+      - 'ghcr.io/synapsecns/sanguine/signer-example:{{ .Tag }}'
+    build_flag_templates:
+      - '--label=org.opencontainers.image.created={{.Date}}'
+      - '--label=org.opencontainers.image.name={{.ProjectName}}'
+      - '--label=org.opencontainers.image.revision={{.FullCommit}}'
+      - '--label=org.opencontainers.image.version={{.Version}}'
+      - '--label=org.opencontainers.image.source={{.GitURL}}'
+    dockerfile: ../docker/signer-example.Dockerfile
+    ids:
+      - signer-example
 
 # add a source archive at release time
 source:

ethergo/README.md

@@ -16,7 +16,7 @@ Some key components of Ethergo include:
  - **Manager**: The manager is responsible for handling contract deployments.
  -  **Signer**: Ethergo offers signing and transaction submission utilities, with various adapters for signing transactions and handling race conditions with nonces. It also includes a wallet interface capable of importing keys from seed phrases, private keys, and mnemonics.
 
- To see a working example of Ethergo in action, refer to the [`example`](./example) folder, which provides a complete demonstration of how to use the deployer and manager components. Please note that the APIs are subject to change.
+ To see a working example of Ethergo in action, refer to the [`example`](./examples) folder, which provides a complete demonstration of how to use the deployer and manager components. Please note that the APIs are subject to change.
 
 
 ## Directory Structure
@@ -36,7 +36,7 @@ root
 │   ├── <a href="./chain/watcher">watcher</a>: Client interface for chain watcher.</s>
 ├── <a href="./contracts">contracts</a>: Contains interfaces for using contracts with the deployer + manager
 ├── <a href="./client">client</a>: Contains an open tracing compatible ethclient with batching.
-├── <a href="./example">example</a>: Contains a full featured example of how to use deployer + manager
+├── <a href="./examples">examples</a>: Contains a full featured example of how to use deployer + manager & a signer.
 ├── <a href="./forker">forker</a>: Allows the use of fork tests in live chains without docker using an anvil binary.
 ├── <a href="./listener">listener</a>: Drop-in contract listener
 ├── <a href="./manager">manager</a>: Manages contract deployments.

ethergo/backends/anvil/suite_test.go

@@ -1,6 +1,8 @@
 package anvil_test
 
 import (
+	"github.com/synapsecns/sanguine/ethergo/examples/contracttests"
+	"github.com/synapsecns/sanguine/ethergo/examples/contracttests/counter"
 	"testing"
 
 	"github.com/ethereum/go-ethereum/common"
@@ -9,8 +11,6 @@ import (
 	"github.com/synapsecns/sanguine/core"
 	"github.com/synapsecns/sanguine/core/testsuite"
 	"github.com/synapsecns/sanguine/ethergo/backends/anvil"
-	"github.com/synapsecns/sanguine/ethergo/example"
-	"github.com/synapsecns/sanguine/ethergo/example/counter"
 	"github.com/synapsecns/sanguine/ethergo/manager"
 )
 
@@ -49,8 +49,8 @@ func (a *AnvilSuite) SetupSuite() {
 	a.client, err = anvil.Dial(a.GetSuiteContext(), a.backend.RPCAddress())
 	Nil(a.T(), err)
 
-	deployer := manager.NewDeployerManager(a.T(), example.NewCounterDeployer)
-	deployedContract := deployer.Get(a.GetSuiteContext(), a.backend, example.CounterType)
+	deployer := manager.NewDeployerManager(a.T(), contracttests.NewCounterDeployer)
+	deployedContract := deployer.Get(a.GetSuiteContext(), a.backend, contracttests.CounterType)
 
 	var ok bool
 	a.counter, ok = deployedContract.ContractHandle().(*counter.CounterRef)

ethergo/deployer/deployed_contract_test.go

@@ -4,7 +4,7 @@ import (
 	. "github.com/stretchr/testify/assert"
 	"github.com/synapsecns/sanguine/ethergo/backends/simulated"
 	"github.com/synapsecns/sanguine/ethergo/deployer"
-	"github.com/synapsecns/sanguine/ethergo/example/counter"
+	counter2 "github.com/synapsecns/sanguine/ethergo/examples/contracttests/counter"
 	"math/big"
 )
 
@@ -13,10 +13,10 @@ func (d *DeployerSuite) TestNewDeployedContract() {
 	backend := simulated.NewSimulatedBackendWithChainID(d.GetTestContext(), d.T(), big.NewInt(chainID))
 
 	counterDeployer := backend.GetTxContext(d.GetTestContext(), nil)
-	deploymentAddress, tx, _, err := counter.DeployCounter(counterDeployer.TransactOpts, backend)
+	deploymentAddress, tx, _, err := counter2.DeployCounter(counterDeployer.TransactOpts, backend)
 	Nil(d.T(), err)
 
-	handle, err := counter.NewCounterRef(deploymentAddress, backend)
+	handle, err := counter2.NewCounterRef(deploymentAddress, backend)
 	Nil(d.T(), err)
 
 	deployed, err := deployer.NewDeployedContract(handle, tx)

ethergo/example/README.md → ethergo/examples/contracttests/README.md

@@ -153,8 +153,8 @@
         "context"
         "github.com/ethereum/go-ethereum/accounts/abi/bind"
         . "github.com/stretchr/testify/assert"
-        "github.com/synapsecns/sanguine/ethergo/example"
-        "github.com/synapsecns/sanguine/ethergo/example/counter"
+        "github.com/synapsecns/sanguine/ethergo/examples"
+        "github.com/synapsecns/sanguine/ethergo/examples/counter"
         "github.com/synapsecns/sanguine/ethergo/manager"
         "github.com/synapsecns/sanguine/ethergo/backends/simulated"
         "testing"
@@ -233,7 +233,7 @@
         "context"
         "github.com/synapsecns/sanguine/ethergo/backends"
         "github.com/synapsecns/sanguine/ethergo/contracts"
-        "github.com/synapsecns/sanguine/ethergo/example/counter"
+        "github.com/synapsecns/sanguine/ethergo/examples/counter"
         "github.com/synapsecns/sanguine/ethergo/manager"
         "testing"
       )
@@ -255,7 +255,7 @@
             "context"
             "github.com/synapsecns/sanguine/ethergo/backends"
             "github.com/synapsecns/sanguine/ethergo/contracts"
-            "github.com/synapsecns/sanguine/ethergo/example"
+            "github.com/synapsecns/sanguine/ethergo/examples"
             "github.com/synapsecns/sanguine/ethergo/manager"
             "testing"
           )

ethergo/example/contracttype.go → ethergo/examples/contracttests/contracttype.go

@@ -1,9 +1,9 @@
-package example
+package contracttests
 
 import (
 	"github.com/ethereum/go-ethereum/common/compiler"
 	"github.com/synapsecns/sanguine/ethergo/contracts"
-	"github.com/synapsecns/sanguine/ethergo/example/counter"
+	"github.com/synapsecns/sanguine/ethergo/examples/contracttests/counter"
 )
 
 // set all contact types.

ethergo/example/counter_test.go → ethergo/examples/contracttests/counter_test.go

@@ -1,12 +1,12 @@
-package example_test
+package contracttests_test
 
 import (
 	"context"
 	"github.com/ethereum/go-ethereum/accounts/abi/bind"
 	. "github.com/stretchr/testify/assert"
 	"github.com/synapsecns/sanguine/ethergo/backends/simulated"
-	"github.com/synapsecns/sanguine/ethergo/example"
-	"github.com/synapsecns/sanguine/ethergo/example/counter"
+	"github.com/synapsecns/sanguine/ethergo/examples/contracttests"
+	"github.com/synapsecns/sanguine/ethergo/examples/contracttests/counter"
 	"github.com/synapsecns/sanguine/ethergo/manager"
 	"testing"
 	"time"
@@ -19,11 +19,11 @@ func TestCounter(t *testing.T) {
 
 	// since extra deployers don't necessarily deploy anything (only when requested in the GetOnlyContractRegistry)
 	// adding them here won't slow anything down. It's recommended you have a global slice of these deployers you register every time.
-	deployer := manager.NewDeployerManager(t, example.NewCounterDeployer)
+	deployer := manager.NewDeployerManager(t, contracttests.NewCounterDeployer)
 
 	newTestBackend := simulated.NewSimulatedBackend(testContext, t)
 
-	deployedContract := deployer.Get(testContext, newTestBackend, example.CounterType)
+	deployedContract := deployer.Get(testContext, newTestBackend, contracttests.CounterType)
 	// if you're using these often, it's recommended you extend manager and add type casted getters here, along with the global registry
 	//nolint: forcetypeassert
 	counterHandle := deployedContract.ContractHandle().(*counter.CounterRef)
@@ -48,6 +48,6 @@ func TestCounter(t *testing.T) {
 
 func TestDependenciesCorrect(t *testing.T) {
 	manager.AssertDependenciesCorrect(context.Background(), t, func() manager.IDeployManager {
-		return manager.NewDeployerManager(t, example.NewCounterDeployer)
+		return manager.NewDeployerManager(t, contracttests.NewCounterDeployer)
 	})
 }

ethergo/example/deployer.go → ethergo/examples/contracttests/deployer.go

@@ -1,4 +1,4 @@
-package example
+package contracttests
 
 import (
 	"context"
@@ -8,7 +8,7 @@ import (
 	"github.com/synapsecns/sanguine/ethergo/backends"
 	"github.com/synapsecns/sanguine/ethergo/contracts"
 	"github.com/synapsecns/sanguine/ethergo/deployer"
-	"github.com/synapsecns/sanguine/ethergo/example/counter"
+	counter2 "github.com/synapsecns/sanguine/ethergo/examples/contracttests/counter"
 )
 
 // CounterDeployer deploys a counter.
@@ -28,11 +28,11 @@ func (n *CounterDeployer) Deploy(ctx context.Context) (contracts.DeployedContrac
 	//nolint: wrapcheck
 	return n.DeploySimpleContract(ctx, func(transactOps *bind.TransactOpts, backend bind.ContractBackend) (common.Address, *types.Transaction, interface{}, error) {
 		//nolint: wrapcheck
-		return counter.DeployCounter(transactOps, backend)
+		return counter2.DeployCounter(transactOps, backend)
 	}, func(address common.Address, backend bind.ContractBackend) (interface{}, error) {
 		// this is kept separate because we often want to add an address handle to this so it's compatible with vm.ContractRef
 		//nolint: wrapcheck
-		return counter.NewCounterRef(address, backend)
+		return counter2.NewCounterRef(address, backend)
 	})
 }
 

ethergo/example/deploymanager.go → ethergo/examples/contracttests/deploymanager.go

@@ -1,10 +1,10 @@
-package example
+package contracttests
 
 import (
 	"context"
 	"github.com/synapsecns/sanguine/ethergo/backends"
 	"github.com/synapsecns/sanguine/ethergo/contracts"
-	"github.com/synapsecns/sanguine/ethergo/example/counter"
+	"github.com/synapsecns/sanguine/ethergo/examples/contracttests/counter"
 	"github.com/synapsecns/sanguine/ethergo/manager"
 	"testing"
 )