Merge pull request #80 from attestantio/rework-api

Rework API

.golangci.yml

@@ -126,19 +126,13 @@ linters:
   # Disable specific linter
   # https://golangci-lint.run/usage/linters/#disabled-by-default
   disable:
-    - contextcheck
     - cyclop
     - deadcode
-    - decorder
     - depguard
     - dupl
-    - dupword
-    - errchkjson
-    - errorlint
     - exhaustive
     - exhaustivestruct
     - exhaustruct
-    - forbidigo
     - forcetypeassert
     - funlen
     - gci
@@ -147,8 +141,6 @@ linters:
     - gocognit
     - goconst
     - goerr113
-    - gofumpt
-    - goheader
     - golint
     - gomnd
     - ifshort
@@ -158,19 +150,10 @@ linters:
     - maintidx
     - maligned
     - musttag
-    - nilnil
-    - nlreturn
-    - nolintlint
     - nosnakecase
-    - promlinter
-    - rowserrcheck
     - scopelint
-    - sqlclosecheck
     - structcheck
-    - thelper
     - varcheck
     - varnamelen
-    - wastedassign
-    - whitespace
     - wrapcheck
     - wsl

README.md

@@ -10,6 +10,8 @@ Go library providing an abstraction to multiple Ethereum 2 beacon nodes.  Its ex
 
 This library is under development; expect APIs and data structures to change until it reaches version 1.0.  In addition, clients' implementations of both their own and the standard API are themselves under development so implementation of the the full API can be incomplete.
 
+> Between versions 0.18.0 and 0.19.0 the API has undergone a number of changes.  Please see [the detailed documentation](docs/0.19.0-changes.md) regarding these changes.
+
 ## Table of Contents
 
 - [Install](#install)
@@ -51,6 +53,7 @@ import (
     "fmt"
 
     eth2client "github.com/attestantio/go-eth2-client"
+    "github.com/attestantio/go-eth2-client/api"
     "github.com/attestantio/go-eth2-client/http"
     "github.com/rs/zerolog"
 )
@@ -74,20 +77,31 @@ func main() {
     // supported by all clients, so checks should be made for each function when
     // casting the service to the relevant interface.
     if provider, isProvider := client.(eth2client.GenesisProvider); isProvider {
-        genesis, err := provider.Genesis(ctx)
+        genesisResponse, err := provider.Genesis(ctx)
         if err != nil {
+            // Errors may be API errors, in which case they will have more detail
+            // about the failure.
+            var apiErr *api.Error
+            if errors.As(err, &apiErr) {
+                switch apiErr.StatusCode {
+                  case 404:
+                    panic("genesis not found")
+                  case 503:
+                    panic("node is syncing")
+                }
+            }
             panic(err)
         }
-        fmt.Printf("Genesis time is %v\n", genesis.GenesisTime)
+        fmt.Printf("Genesis time is %v\n", genesisResponse.Data.GenesisTime)
     }
 
     // You can also access the struct directly if required.
     httpClient := client.(*http.Service)
-    genesis, err := httpClient.Genesis(ctx)
+    genesisResponse, err := httpClient.Genesis(ctx)
     if err != nil {
         panic(err)
     }
-    fmt.Printf("Genesis validators root is %#x\n", genesis.GenesisValidatorsRoot)
+    fmt.Printf("Genesis validators root is %s\n", genesisResponse.Data.GenesisValidatorsRoot)
 
     // Cancelling the context passed to New() frees up resources held by the
     // client, closes connections, clears handlers, etc.

api/aggregateattestationopts.go

@@ -0,0 +1,24 @@
+// Copyright © 2023 Attestant Limited.
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package api
+
+import "github.com/attestantio/go-eth2-client/spec/phase0"
+
+// AggregateAttestationOpts are the options for obtaining aggregate attestations.
+type AggregateAttestationOpts struct {
+	// Slot is the slot for which the data is obtained.
+	Slot phase0.Slot
+	// AttestationDataRoot is the root for which the data is obtained.
+	AttestationDataRoot phase0.Root
+}

api/attestationdataopts.go

@@ -0,0 +1,24 @@
+// Copyright © 2023 Attestant Limited.
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package api
+
+import "github.com/attestantio/go-eth2-client/spec/phase0"
+
+// AttestationDataOpts are the options for obtaining attestation data.
+type AttestationDataOpts struct {
+	// Slot is the slot for which the data is obtained.
+	Slot phase0.Slot
+	// CommitteeIndex is the committee index for which the data is obtained.
+	CommitteeIndex phase0.CommitteeIndex
+}

api/attestationpoolopts.go

@@ -0,0 +1,22 @@
+// Copyright © 2023 Attestant Limited.
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package api
+
+import "github.com/attestantio/go-eth2-client/spec/phase0"
+
+// AttestationPoolOpts are the options for obtaining the attestation pool.
+type AttestationPoolOpts struct {
+	// Slot is the slot for which the data is obtained.
+	Slot phase0.Slot
+}

api/attesterdutiesopts.go

@@ -0,0 +1,24 @@
+// Copyright © 2023 Attestant Limited.
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package api
+
+import "github.com/attestantio/go-eth2-client/spec/phase0"
+
+// AttesterDutiesOpts are the options for obtaining proposer duties.
+type AttesterDutiesOpts struct {
+	// Epoch is the epoch for which the data is obtained.
+	Epoch phase0.Epoch
+	// Indices is a list of validators for which to obtain the duties.
+	Indices []phase0.ValidatorIndex
+}

api/beaconblockheaderopts.go

@@ -0,0 +1,20 @@
+// Copyright © 2023 Attestant Limited.
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package api
+
+// BeaconBlockHeaderOpts are the options for obtaining beacon block headers.
+type BeaconBlockHeaderOpts struct {
+	// Block is the ID of the block which the data is obtained.
+	Block string
+}

api/beaconblockrootopts.go

@@ -0,0 +1,20 @@
+// Copyright © 2023 Attestant Limited.
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package api
+
+// BeaconBlockRootOpts are the options for obtaining the beacon block root.
+type BeaconBlockRootOpts struct {
+	// Block is the ID of the block which the data is obtained.
+	Block string
+}

api/beaconcommitteesopts.go

@@ -0,0 +1,26 @@
+// Copyright © 2023 Attestant Limited.
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package api
+
+import "github.com/attestantio/go-eth2-client/spec/phase0"
+
+// BeaconCommitteesOpts are the options for obtaining proposer duties.
+type BeaconCommitteesOpts struct {
+	// State is the state at which the data is obtained.
+	// It can be a slot number or state root, or one of the special values "genesis", "head", "justified" or "finalized".
+	State string
+	// Epoch is the epoch for which the data is obtained.
+	// This is optional; if not supplied it will obtain the data at the epoch relating to the state.
+	Epoch *phase0.Epoch
+}

api/beaconstateopts.go

@@ -0,0 +1,21 @@
+// Copyright © 2023 Attestant Limited.
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package api
+
+// BeaconStateOpts are the options for obtaining the beacon state.
+type BeaconStateOpts struct {
+	// State is the state at which the data is obtained.
+	// It can be a slot number or state root, or one of the special values "genesis", "head", "justified" or "finalized".
+	State string
+}

api/beaconstaterandaoopts.go

@@ -0,0 +1,21 @@
+// Copyright © 2023 Attestant Limited.
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package api
+
+// BeaconStateRandaoOpts are the options for obtaining the beacon state RANDAO.
+type BeaconStateRandaoOpts struct {
+	// State is the state at which the data is obtained.
+	// It can be a slot number or state root, or one of the special values "genesis", "head", "justified" or "finalized".
+	State string
+}

api/beaconstaterootopts.go

@@ -0,0 +1,21 @@
+// Copyright © 2023 Attestant Limited.
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package api
+
+// BeaconStateRootOpts are the options for obtaining the beacon state root.
+type BeaconStateRootOpts struct {
+	// State is the state at which the data is obtained.
+	// It can be a slot number or state root, or one of the special values "genesis", "head", "justified" or "finalized".
+	State string
+}

api/blindedproposalopts.go

@@ -0,0 +1,29 @@
+// Copyright © 2023 Attestant Limited.
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package api
+
+import "github.com/attestantio/go-eth2-client/spec/phase0"
+
+// BlindedProposalOpts are the options for obtaining blinded proposals.
+type BlindedProposalOpts struct {
+	// Slot is the slot for which the proposal should be fetched.
+	Slot phase0.Slot
+	// RandaoReveal is the RANDAO reveal for the proposal.
+	RandaoReveal phase0.BLSSignature
+	// Graffit is the graffiti to be included in the beacon block body.
+	Graffiti [32]byte
+	// SkipRandaoVerification is true if we do not want the server to verify our RANDAO reveal.
+	// If this is set then the RANDAO reveal should be passed as the point at infinity (0xc0…00)
+	SkipRandaoVerification bool
+}