You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[`avalanchego`](https://github.com/ava-labs/avalanchego) validator, used for all
5
-
bls signatures (currently used for peer handshakes and ICM message signatures).
6
-
This service runs a [gRPC](https://grpc.io/) server, implementing the
7
-
[`signer.proto` service definition](https://github.com/ava-labs/avalanchego/blob/master/proto/signer/signer.proto).
8
-
When the `gRPC` endpoints are hit, they make subsequent requests to the
9
-
[Cubist-API](https://signer-docs.cubist.dev/api)
3
+
This repository contains a proxy that can be run alongside [AvalancheGo](https://github.com/ava-labs/avalanchego) nodes to integrate them with [CubeSigner](https://cubist.dev/products/cubesigner-self-custody) for secure BLS key management powered by [Cubist](https://cubist.dev/). AvalancheGo nodes currently use BLS keys for peer handshakes and to sign [ICM messages](https://build.avax.network/docs/cross-chain/avalanche-warp-messaging/overview). By integrating with CubeSigner, AvalancheGo nodes do not need to store their BLS keys in memory or on disk. Instead, the keys are generated and kept within a remote hardware security module (HSM), and the AvalancheGo node is configured to request signatures from that HSM as needed via this `cube-signer-sidecar`.
4
+
5
+
This service runs a [gRPC](https://grpc.io/) server, implementing the [`signer.proto` service definition](https://github.com/ava-labs/avalanchego/blob/master/proto/signer/signer.proto). When the `gRPC` endpoints are hit, they make subsequent requests to the [CubeSigner API](https://signer-docs.cubist.dev/api) to get the requested signature.
6
+
7
+
A Cubist account is required to be able to properly use the `cube-signer-sidecar`.
10
8
11
9
## Building
12
10
13
-
The `api/` directory contains generated code from the
We use the [`spec/get-schemas.go`] script to filter the API-spec for the three
16
-
endpoints that we care about as well as all the schemas that those endpoints
17
-
use. The filtered Open-API specification is output to
18
-
`spec/filtered-openapi.json`.
11
+
The `api/` directory contains generated code from the [CubeSigner OpenAPI specification](https://raw.githubusercontent.com/cubist-labs/CubeSigner-TypeScript-SDK/main/packages/sdk/spec/openapi.json). The [`spec/get-schemas.go`] script is used to filter the API-spec for the three relevant endpoints, as well as all the schemas that those endpoints
12
+
use. The filtered Open-API specification is output to `spec/filtered-openapi.json`.
19
13
20
-
If there are changes in `spec/filtered-openapi.json`, you _must_ run
21
-
`go generate ./signerserver` to re-generate the client code in the `api/`
22
-
directory.
14
+
If there are changes in `spec/filtered-openapi.json`, the `go generate ./signerserver`_must_ be run to re-generate the client code in the `api/` directory.
23
15
24
16
## Testing
25
17
26
-
Currently, the only way to test the code is using
27
-
[this PR](https://github.com/ava-labs/avalanchego/pull/3725) where you have to
28
-
set the `--staking-rpc-signer=127.0.0.1:50051` configuration flag. You must
29
-
first start this application before starting the `avalanchego` node.
18
+
The `cube-signer-sidecar` depends on the AvalancheGo changes implemented in [this PR](https://github.com/ava-labs/avalanchego/pull/3965). In order to test it, set the `--staking-rpc-signer-endpoint=127.0.0.1:50051` configuration flag, and ensure that the `cube-signer-sidecar` application is running before starting the `avalanchego` node.
30
19
31
20
## Running
32
21
33
22
### Key Creation
34
23
35
-
To run the `cubist-signer` locally, you will need a
(sorry for the similar names). If you need an invite to see the repository,
38
-
please reach out to someone on the @ava-labs/interop team. Once installed, you
39
-
will need to set up the `CubeSigner` and login following
40
-
[the Getting Started instructions](https://signer-docs.cubist.dev/getting-started)
41
-
(the docs are password protected, the password should be in the `CubeSigner`
42
-
README). After, you will need to create a `role` with the following command:
24
+
The [`CubeSigner`](https://github.com/cubist-partners/CubeSigner/) application is needed to set up the `cube-signer-sidecar` to be run locally. Once installed, set up the `CubeSigner` and log in following the [Getting Started instructions](https://signer-docs.cubist.dev/getting-started). The following commands can then be used to set up a role, key, and signing policy.
43
25
44
26
```shell
27
+
# Create a role.
45
28
cs role create --role-name bls_signer
46
-
```
47
-
48
-
Then create a key:
49
29
50
-
```shell
30
+
# Create a key.
51
31
cs keys create --key-type=bls-ava-icm
52
-
```
53
32
54
-
Next, set the signing policy on the key:
55
-
56
-
```shell
57
-
# you can find the <key_id> using `cs keys list`
33
+
# Set the signing policy for the key.
34
+
# The `cs keys list` command can be used to find the <key_id>.
Below is a list of configuration options that can be set via a JSON config file passed in via `--config-file` flag or set through environment variables or flags. To get the environment variable corresponding to the key uppercase the key and change the delimiter from "-" to "_". The following precedence order is used, with each item taking precedence over items below it:
48
+
77
49
1. Flags
78
50
2. Environment variables
79
51
3. Config file
80
52
81
53
-`"token-file-path": string` (required)
82
54
83
-
This is the relative path (absolute paths also work) to the token file, we
84
-
created from the last step above.
55
+
This is the path to the token file, created in the last step above.
85
56
86
-
The `refresh-token` (part of the JSON output of `cs token create`) has a very
87
-
short TTL by default, so you must start the signer (this repo) before it
88
-
expires. Once started, your `<path_to_token>.json` file will be continuously
89
-
refreshed as needed. To change any of the default token parameters, see
90
-
`cs token create --help`.
57
+
The `refresh-token` (part of the JSON output of `cs token create`) has a short TTL by default, and the `cube-signer-sidecar` must be started before it expires. Once started, the `<path_to_token>.json` file will be continuously refreshed as needed. To change any of the default token parameters, see `cs token create --help`.
91
58
92
59
-`"signer-endpoint": string` (required)
93
60
94
-
This is the Cubist-API endpoint.
61
+
The CubeSigner API endpoint.
95
62
96
63
-`"key-id": string` (required)
97
64
98
-
The `cubist-signer` (this repo) can only use one key at a time as an
99
-
`avalanchego` validator is only meant to have a single BLS signing key.
100
-
Specifying the `KEY_ID` is how the Cubist-API knows what key to use for
101
-
signing. The `role` associated with the `role_id` filed in the token JSON will
102
-
need access to this key (see [Configuration](#configuration))
65
+
The `cube-signer-sidecar` can only use one key at a time, as an `avalanchego` validator is only meant to have a single BLS signing key. Specifying the `KEY_ID` is how the CubeSigner API knows what key to use for signing. The `role` associated with the `role_id` filed in the token JSON will need access to this key (see [Configuration](#configuration)).
103
66
104
67
-`"port": int` (defaults to 50051)
105
68
106
-
Port at which to start the local signer server.
69
+
The port at which to start the local signer server.
107
70
108
71
### Usage
109
72
110
-
Both the `SIGNER_ENDPOINT` and `KEY_ID` can be exported in your current shell
111
-
session as they are unlikely to change if you running the signer locally.
73
+
Both the `SIGNER_ENDPOINT` and `KEY_ID` can be exported in the current shell session as they are unlikely to change if running the signer locally.
@@ -120,11 +82,8 @@ TOKEN_FILE_PATH="./token.json" go run main/main.go
120
82
### E2E tests
121
83
122
84
#### Running Locally
123
-
To run E2E locally follow the steps in [Key Creation](#key-creation) above to generate a new key associated with the `e2e_signer` role and generate a session token file saved as `e2e_session.json`. After that the tests can be run via
85
+
To run E2E locally follow the [key creation](#key-creation)steps above to generate a new key associated with the `e2e_signer` role, and generate a session token file saved as `e2e_session.json`. After that the tests can be run via
124
86
125
87
```bash
126
88
./scripts/e2e_test.sh
127
89
```
128
-
129
-
#### CI
130
-
The base64 encoded session token is stored in Github secrets. It currently expires on 6/05/2026. When it expires, a new token can be generated and stored there.
0 commit comments