Implement token based F3 participation lease

Implemented enhanced token-based participation system for F3 consensus
in `F3Participate`. This update introduces a new design where
participation tokens grant a temporary lease, allowing storage providers
to sign as part of the F3 consensus mechanism. This design ensures that
tokens are checked for validity and issuer alignment, handling errors
robustly. If there's an issuer mismatch, the system advises miners to
retry with the existing token. If the token is invalid or expired,
miners are directed to obtain a new token via `F3GetParticipationToken`.

Fixes filecoin-project/go-f3#599

api/api_full.go

@@ -3,11 +3,14 @@ package api
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"time"
 
+	"github.com/google/uuid"
 	blocks "github.com/ipfs/go-block-format"
 	"github.com/ipfs/go-cid"
+	"github.com/libp2p/go-libp2p/core/peer"
 
 	"github.com/filecoin-project/go-address"
 	"github.com/filecoin-project/go-bitfield"
@@ -910,24 +913,25 @@ type FullNode interface {
 
 	//*********************************** ALL F3 APIs below are not stable & subject to change ***********************************
 
-	// F3Participate should be called by a storage provider to participate in signing F3 consensus.
-	// Calling this API gives the lotus node a lease to sign in F3 on behalf of given SP.
-	// The lease should be active only on one node. The lease will expire at the newLeaseExpiration.
-	// To continue participating in F3 with the given node, call F3Participate again before
-	// the newLeaseExpiration time.
-	// newLeaseExpiration cannot be further than 5 minutes in the future.
-	// It is recommended to call F3Participate every 60 seconds
-	// with newLeaseExpiration set 2min into the future.
-	// The oldLeaseExpiration has to be set to newLeaseExpiration of the last successful call.
-	// For the first call to F3Participate, set the oldLeaseExpiration to zero value/time in the past.
-	// F3Participate will return true if the lease was accepted.
-	// The minerID has to be the ID address of the miner.
-	F3Participate(ctx context.Context, minerID address.Address, newLeaseExpiration time.Time, oldLeaseExpiration time.Time) (bool, error) //perm:sign
-	// F3GetCertificate returns a finality certificate at given instance number
-	F3GetCertificate(ctx context.Context, instance uint64) (*certs.FinalityCertificate, error) //perm:read
-	// F3GetLatestCertificate returns the latest finality certificate
+	// F3GetParticipationToken retrieves a token that allows a miner to participate in the F3 consensus process.
+	// The token must be subsequently used to invoke F3Participate.
+	F3GetParticipationToken(ctx context.Context, minerID address.Address) (F3ParticipationToken, error) //perm:sign
+	// F3Participate registers a storage provider to participate in the F3 consensus
+	// using a provided participation token. The token grants a temporary lease that
+	// allows the storage provider to sign transactions as part of the F3 consensus.
+	// The function checks the validity of the token and the alignment of the issuer
+	// with the current node. If the issuer does not match
+	// (ErrF3ParticipationIssuerMismatch), the miner should retry with the same token
+	// assuming transient network issues. If the token is invalid
+	// (ErrF3ParticipationTokenInvalid) or has expired
+	// (ErrF3ParticipationTokenExpired), the miner should request a new token by
+	// invoking F3GetParticipationToken.
+	F3Participate(ctx context.Context, token F3ParticipationToken) (F3ParticipationLease, error) //perm:sign
+	// F3GetCertificate returns a finality certificate at given instance.
+	F3GetCertificate(ctx context.Context, instance uint64) (*certs.FinalityCertificate, error) //perm:sign
+	// F3GetLatestCertificate returns the latest finality certificate.
 	F3GetLatestCertificate(ctx context.Context) (*certs.FinalityCertificate, error) //perm:read
-	// F3GetGetManifest returns the current manifest being used for F3
+	// F3GetManifest returns the current manifest being used for F3 operations.
 	F3GetManifest(ctx context.Context) (*manifest.Manifest, error) //perm:read
 	// F3GetECPowerTable returns a F3 specific power table for use in standalone F3 nodes.
 	F3GetECPowerTable(ctx context.Context, tsk types.TipSetKey) (gpbft.PowerEntries, error) //perm:read
@@ -936,6 +940,37 @@ type FullNode interface {
 	// F3IsRunning returns true if the F3 instance is running, false if it's not running but
 	// it's enabled, and an error when disabled entirely.
 	F3IsRunning(ctx context.Context) (bool, error) //perm:read
+	// F3GetProgress returns the progress of the current F3 instance in terms of instance ID, round and phase.
+	F3GetProgress(ctx context.Context) (F3Progress, error) //perm:read
+}
+
+var (
+	ErrF3Disabled                    = errors.New("f3 is disabled")
+	ErrF3ParticipationTokenInvalid   = errors.New("f3 participation token is not valid")
+	ErrF3ParticipationTokenExpired   = errors.New("f3 participation token has expired")
+	ErrF3ParticipationIssuerMismatch = errors.New("f3 participation token issuer does not match current node")
+)
+
+// F3ParticipationToken represents a binary token that authorizes a miner to
+// participate in the F3 consensus.
+type F3ParticipationToken []byte
+
+// F3ParticipationLease defines the lease granted to a storage provider for
+// participating in F3 consensus, detailing the session identifier, issuer,
+// subject, and the expiration instance.
+type F3ParticipationLease struct {
+	Session             uuid.UUID
+	Issuer              peer.ID
+	Subject             uint64
+	ExpireAfterInstance uint64
+}
+
+// F3Progress encapsulates the current progress of the F3 instance, specifying
+// the instance ID, round, and the current phase of the consensus process.
+type F3Progress struct {
+	Instance uint64
+	Round    uint64
+	Phase    gpbft.Phase
 }
 
 // EthSubscriber is the reverse interface to the client, called after EthSubscribe

api/docgen/docgen.go

@@ -124,6 +124,7 @@ func init() {
 	addExample(api.FullAPIVersion1)
 	addExample(api.PCHInbound)
 	addExample(time.Minute)
+	addExample(gpbft.INITIAL_PHASE)
 
 	addExample(network.ReachabilityPublic)
 	addExample(buildconstants.TestNetworkVersion)