Skip to content

Commit a1f1d51

Browse files
masihmasih
authored
feat: implement ChainGetTipSet in Lotus v2 APIs (#13003)
Introduce the first API for Lotus v2, focusing on `ChainGetTipSet` within the `Chain` group. Define `TipSetSelector` for advanced tipset retrieval options, and create a compact JSON-RPC call format. Gracefully accommodate both EC and F3 finalized tipsets based on node configuration, where: * EC finalized tipset is returned when F3 is turned off, has no finalized tipset or F3 isn't ready. * F3 finalized is returned otherwise. Support three categories of selectors under `TipSetSelector`: * By tag: either "latest" or "finalized." * By height: epoch, plus optional fallback to previous non-null tipset. * By tipset key. The selection falls back to tag "latest" if the user specifies no selection criterion. The JSON-RPC format is designed to use JSON Object as the parameters passed to the RPC call to remain compact, and extensible.
1 parent 9c897c5 commit a1f1d51

File tree

29 files changed

+1179
-34
lines changed

29 files changed

+1179
-34
lines changed

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
# UNRELEASED
1111

1212
- fix(eth): always return nil for eth transactions not found ([filecoin-project/lotus#12999](https://github.com/filecoin-project/lotus/pull/12999))
13+
- feat: add experimental v2 APIs that are "F3 aware." (TODO: expand this section significantly to cover where someone learns about the new APIs, how they enable them, and what expectations they should have around them—i.e., they may change)
1314

1415
# Node and Miner v1.32.2 / 2025-04-04
1516

‎api/docgen/docgen.go‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ import (
3838
"github.com/filecoin-project/lotus/api"
3939
apitypes "github.com/filecoin-project/lotus/api/types"
4040
"github.com/filecoin-project/lotus/api/v0api"
41+
"github.com/filecoin-project/lotus/api/v2api"
4142
"github.com/filecoin-project/lotus/build/buildconstants"
4243
"github.com/filecoin-project/lotus/chain/actors/builtin/miner"
4344
"github.com/filecoin-project/lotus/chain/actors/builtin/verifreg"
@@ -468,6 +469,7 @@ func init() {
468469
},
469470
Input: ecchain,
470471
})
472+
addExample(types.TipSetSelectors.Finalized)
471473
}
472474

473475
func GetAPIType(name, pkg string) (i interface{}, t reflect.Type, permStruct []reflect.Type) {
@@ -508,6 +510,15 @@ func GetAPIType(name, pkg string) (i interface{}, t reflect.Type, permStruct []r
508510
default:
509511
panic("unknown type")
510512
}
513+
case "v2api":
514+
switch name {
515+
case "FullNode":
516+
i = &v2api.FullNodeStruct{}
517+
t = reflect.TypeOf(new(struct{ v2api.FullNode })).Elem()
518+
permStruct = append(permStruct, reflect.TypeOf(v2api.FullNodeStruct{}.Internal))
519+
default:
520+
panic("unknown type")
521+
}
511522
}
512523
return
513524
}

‎api/v2api/doc.go‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
// Package v2api provides an interface for interacting with the v2 full node APIs
2+
// within the Filecoin network.
3+
//
4+
// This package is experimental and the API may change without notice.
5+
package v2api

‎api/v2api/full.go‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
package v2api
2+
3+
import (
4+
"context"
5+
6+
"github.com/filecoin-project/lotus/chain/types"
7+
)
8+
9+
//go:generate go run github.com/golang/mock/mockgen -destination=v2mocks/mock_full.go -package=v2mocks . FullNode
10+
11+
// FullNode represents an interface for the v2 full node APIs. This interface
12+
// currently consists of chain-related functionalities and the API is
13+
// experimental and subject to change.
14+
type FullNode interface {
15+
// MethodGroup: Chain
16+
// The Chain method group contains methods for interacting with
17+
// the blockchain.
18+
//
19+
// <b>Note: This API is experimental and may change in the future.<b/>
20+
//
21+
// Please see Filecoin V2 API design documentation for more details:
22+
// - https://www.notion.so/filecoindev/Lotus-F3-aware-APIs-1cfdc41950c180ae97fef580e79427d5
23+
// - https://www.notion.so/filecoindev/Filecoin-V2-APIs-1d0dc41950c1808b914de5966d501658
24+
25+
// ChainGetTipSet retrieves a tipset that corresponds to the specified selector
26+
// criteria. The criteria can be provided in the form of a tipset key, a
27+
// blockchain height including an optional fallback to previous non-null tipset,
28+
// or a designated tag such as "latest" or "finalized".
29+
//
30+
// The "Finalized" tag returns the tipset that is considered finalized based on
31+
// the consensus protocol of the current node, either Filecoin EC Finality or
32+
// Filecoin Fast Finality (F3). The finalized tipset selection gracefully falls
33+
// back to EC finality in cases where F3 isn't ready or not running.
34+
//
35+
// In a case where no selector is provided, an error is returned. The selector
36+
// must be explicitly specified.
37+
//
38+
// For more details, refer to the types.TipSetSelector and
39+
// types.NewTipSetSelector.
40+
//
41+
// Example usage:
42+
//
43+
// selector := types.TipSetSelectors.Latest
44+
// tipSet, err := node.ChainGetTipSet(context.Background(), selector)
45+
// if err != nil {
46+
// fmt.Println("Error retrieving tipset:", err)
47+
// return
48+
// }
49+
// fmt.Printf("Latest TipSet: %v\n", tipSet)
50+
//
51+
ChainGetTipSet(context.Context, types.TipSetSelector) (*types.TipSet, error) //perm:read
52+
}

‎api/v2api/permissioned.go‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
package v2api
2+
3+
import (
4+
"github.com/filecoin-project/go-jsonrpc/auth"
5+
6+
"github.com/filecoin-project/lotus/api"
7+
)
8+
9+
func PermissionedFullAPI(a FullNode) FullNode {
10+
var out FullNodeStruct
11+
auth.PermissionedProxy(api.AllPermissions, api.DefaultPerms, a, &out.Internal)
12+
return &out
13+
}

‎api/v2api/proxy_gen.go‎

Lines changed: 37 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎api/v2api/v2mocks/mock_full.go‎

Lines changed: 52 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎build/openrpc/v2/full.json‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
{
2+
"openrpc": "1.2.6",
3+
"info": {
4+
"title": "Lotus RPC API",
5+
"version": "1.32.3-dev"
6+
},
7+
"methods": [
8+
{
9+
"name": "Filecoin.ChainGetTipSet",
10+
"description": "```go\nfunc (s *FullNodeStruct) ChainGetTipSet(p0 context.Context, p1 types.TipSetSelector) (*types.TipSet, error) {\n\tif s.Internal.ChainGetTipSet == nil {\n\t\treturn nil, ErrNotSupported\n\t}\n\treturn s.Internal.ChainGetTipSet(p0, p1)\n}\n```",
11+
"summary": "ChainGetTipSet retrieves a tipset that corresponds to the specified selector\ncriteria. The criteria can be provided in the form of a tipset key, a\nblockchain height including an optional fallback to previous non-null tipset,\nor a designated tag such as \"latest\" or \"finalized\".\n\nThe \"Finalized\" tag returns the tipset that is considered finalized based on\nthe consensus protocol of the current node, either Filecoin EC Finality or\nFilecoin Fast Finality (F3). The finalized tipset selection gracefully falls\nback to EC finality in cases where F3 isn't ready or not running.\n\nIn a case where no selector is provided, an error is returned. The selector\nmust be explicitly specified.\n\nFor more details, refer to the types.TipSetSelector and\ntypes.NewTipSetSelector.\n\nExample usage:\n\n\tselector := types.TipSetSelectors.Latest\n\ttipSet, err := node.ChainGetTipSet(context.Background(), selector)\n\tif err != nil {\n\t\tfmt.Println(\"Error retrieving tipset:\", err)\n\t\treturn\n\t}\n\tfmt.Printf(\"Latest TipSet: %v\\n\", tipSet)\n",
12+
"paramStructure": "by-position",
13+
"params": [
14+
{
15+
"name": "p1",
16+
"description": "types.TipSetSelector",
17+
"summary": "",
18+
"schema": {
19+
"examples": [
20+
{
21+
"tag": "finalized"
22+
}
23+
],
24+
"additionalProperties": false,
25+
"properties": {
26+
"height": {
27+
"additionalProperties": false,
28+
"properties": {
29+
"anchor": {
30+
"additionalProperties": false,
31+
"properties": {
32+
"key": {
33+
"additionalProperties": false,
34+
"type": "object"
35+
},
36+
"tag": {
37+
"type": "string"
38+
}
39+
},
40+
"type": "object"
41+
},
42+
"at": {
43+
"title": "number",
44+
"type": "number"
45+
},
46+
"previous": {
47+
"type": "boolean"
48+
}
49+
},
50+
"type": "object"
51+
},
52+
"key": {
53+
"additionalProperties": false,
54+
"type": "object"
55+
},
56+
"tag": {
57+
"type": "string"
58+
}
59+
},
60+
"type": [
61+
"object"
62+
]
63+
},
64+
"required": true,
65+
"deprecated": false
66+
}
67+
],
68+
"result": {
69+
"name": "*types.TipSet",
70+
"description": "*types.TipSet",
71+
"summary": "",
72+
"schema": {
73+
"examples": [
74+
{
75+
"Cids": null,
76+
"Blocks": null,
77+
"Height": 0
78+
}
79+
],
80+
"additionalProperties": false,
81+
"type": [
82+
"object"
83+
]
84+
},
85+
"required": true,
86+
"deprecated": false
87+
},
88+
"deprecated": false,
89+
"externalDocs": {
90+
"description": "Github remote link",
91+
"url": "https://github.com/filecoin-project/lotus/blob/master/api/v2api/proxy_gen.go#L26"
92+
}
93+
}
94+
]
95+
}

‎chain/lf3/f3.go‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,21 @@ import (
2929
"github.com/filecoin-project/lotus/node/repo"
3030
)
3131

32+
var _ F3Backend = (*F3)(nil)
33+
34+
type F3Backend interface {
35+
GetOrRenewParticipationTicket(_ context.Context, minerID uint64, previous api.F3ParticipationTicket, instances uint64) (api.F3ParticipationTicket, error)
36+
Participate(_ context.Context, ticket api.F3ParticipationTicket) (api.F3ParticipationLease, error)
37+
ListParticipants() []api.F3Participant
38+
GetManifest(ctx context.Context) (*manifest.Manifest, error)
39+
GetCert(ctx context.Context, instance uint64) (*certs.FinalityCertificate, error)
40+
GetLatestCert(ctx context.Context) (*certs.FinalityCertificate, error)
41+
GetPowerTable(ctx context.Context, tsk types.TipSetKey) (gpbft.PowerEntries, error)
42+
GetF3PowerTable(ctx context.Context, tsk types.TipSetKey) (gpbft.PowerEntries, error)
43+
IsRunning() bool
44+
Progress() gpbft.InstanceProgress
45+
}
46+
3247
type F3 struct {
3348
inner *f3.F3
3449
ec *ecWrapper

0 commit comments

Comments
 (0)