fip-0107: commit to API option 2 - implement new v2 APIs

Author: rvagg

FIPS/fip-0107.md

@@ -186,13 +186,43 @@ type ActorEvent struct {
 }
 ```
 
-#### New APIs for Accessing Implicit Messages
+#### v2 APIs for Accessing Implicit Messages
 
-Since existing list-based APIs cannot return implicit messages without breaking compatibility, new mechanisms are needed:
+Since existing list-based APIs cannot return implicit messages without breaking compatibility, v2 APIs will provide flexible access to implicit messages through an options parameter.
 
-**Option 1 - New API**: `ChainGetAllParentReceipts` - returns all receipts including those for implicit messages. This API would return the same results as `ChainGetParentReceipts` before activation of this FIP, but would include additional receipts for implicit messages after activation.
+As of the time of writing, development has begun on the Lotus v2 APIs. It is expected this will eventually lead to extension of [FRC-0104 Common Node APIs](https://github.com/filecoin-project/FIPs/blob/master/FRCs/frc-0104.md). This opportunity will be used to introduce an options object that allows fine-grained control over implicit message inclusion.
 
-**Option 2 - v2 API**: As of the time of writing, development has begun on the Lotus v2 APIs. It is expected this will eventually lead to extension of [FRC-0104 Common Node APIs](https://github.com/filecoin-project/FIPs/blob/master/FRCs/frc-0104.md). This opportunity could be used to break APIs and introduce an options object that would allow optional inclusion of implicit messages. e.g. `ChainGetParentReceipts` could add a new paramter that would change the returned list to prevent filtering: `{ includeImplicits: true }`.
+Relevant v2 APIs will accept an optional options parameter with an `implicits` field that controls how implicit messages are handled:
+
+```go
+type ImplicitOption string
+
+const (
+    ImplicitIgnore  ImplicitOption = "ignore"  // Returns only explicit messages (default)
+    ImplicitInclude ImplicitOption = "include" // Returns both explicit and implicit messages
+    ImplicitOnly    ImplicitOption = "only"    // Returns only implicit messages
+)
+
+// MessageOptions provides fine-grained control over message or receipt retrieval, this will be
+// optional for APIs that accept it. Currently only implicits is defined but this may be expanded
+// in the future.
+type MessageOptions struct {
+    Implicits ImplicitOption `json:"implicits,omitempty"` // defaults to "ignore" for backward compatibility
+}
+```
+
+- `"ignore"` (default): Returns only explicit messages or their receipts, maintaining compatibility with v1 behavior
+- `"include"`: Returns both explicit and implicit messages or their receipts
+- `"only"`: Returns only implicit messages or their receipts
+
+Example usage:
+- `ChainGetParentReceipts(blockCid, { "implicits": "include"})` - returns all receipts
+- `ChainGetParentMessages(tsk, { "implicits": "only"})` - returns only implicit messages
+- `ChainGetParentMessages(blockCid, { "implicits": "ignore"})` - returns only explicit messages (default)
+
+Initially the focus will be on APIs that access receipts or may logically access messages via receipts: `ChainGetParentReceipts` and `ChainGetParentMessages`. `ChainGetMessagesInTipset` is excluded initially as it currently loads messages directly from a tipset, however future consideration could be given to adding implicit messages to the returned list as well.
+
+This design provides maximum flexibility while maintaining backward compatibility and enabling specific use cases like monitoring only system operations.
 
 ## Design Rationale
 
@@ -202,7 +232,7 @@ This design was chosen to minimise disruption to existing systems while providin
 2. **Execution ordering**: Maintains consistency with current execution semantics.
 3. **Message specification**: Uses the existing Lotus implicit message format as a stable basis for all node implementations.
 4. **Gas limit approach**: Maintains existing execution patterns while clarifying that implicit messages operate outside block gas limit constraints. This ensures system operations can complete successfully regardless of user message activity or network congestion.
-5. **API compatibility**: Excludes implicit messages from most APIs by default to avoid breaking existing integrations while allowing direct access when needed.
+5. **API compatibility**: Excludes implicit messages from most APIs by default to avoid breaking existing integrations while providing a clear path forward with v2 APIs for accessing implicit messages.
 
 ### Storage Efficiency Assessment
 
@@ -233,7 +263,7 @@ This change introduces several backwards incompatibilities:
 1. **Receipt Structure Change**: The `MessageReceipt` structure modification requires updates to all code that directly accesses receipt fields; this change will take effect at the next epoch after the activation epoch of this FIP
 2. **Message/Receipt Count Mismatch**: Code assuming `length(deduped parent messages) == length(receipts)` will break and must be updated to either:
    - Use APIs that maintain the old behaviour by filtering out implicit messages
-   - Adapt to use the new `ChainGetAllParentReceipts` (or alternative v2) API when access to all receipts is needed
+   - Adapt to use v2 APIs with appropriate options when access to all receipts is needed
 
 ### API Migration Guide
 
@@ -242,7 +272,7 @@ Applications should adapt as follows:
 1. **For transaction enumeration**: Continue using existing APIs which will maintain backward compatibility
 2. **For complete chain analysis**:
    - Monitor `GetActorEventsRaw` for system events (check `implicit` field)
-   - Use new `ChainGetAllParentReceipts` (or alternative v2) API when available
+   - Use v2 APIs with `{implicits: "include"}` option when available
    - Query implicit messages directly by CID when needed
 3. **For Ethereum compatibility**: No changes needed - existing behaviour is maintained
 4. **For receipt processing**: Update code to handle both old and new receipt formats with null checks on new fields
@@ -309,7 +339,7 @@ For index-based APIs like `eth_getTransactionByBlockHashAndIndex`:
 
 Implicit messages can be discovered through:
 1. **Event-based discovery**: Events from `GetActorEventsRaw` include the emitter's actor ID and message CID
-2. **Receipt-based discovery**: Using `ChainGetAllParentReceipts` (or alternative v2 API) to iterate all receipts
+2. **Receipt-based discovery**: Using v2 APIs with `{implicits: "include"}` or `{implicits: "only"}` to iterate receipts
 3. **Direct query**: If the CID is known, query directly via `ChainGetMessage`
 
 **Important**: Not all implicit messages emit events. Reward messages currently emit no events, and cron messages only emit events for specific operations (e.g., sector terminations). Applications requiring complete implicit message visibility must use receipt-based discovery.
@@ -320,7 +350,7 @@ Tools requiring implicit message processing should:
 1. Monitor `GetActorEventsRaw` for system events
 2. Use the message CID from receipts to query message details
 3. Check the `implicit` field on events to identify system-generated events
-4. Use `ChainGetAllParentReceipts` for complete message enumeration when available
+4. Use v2 APIs with appropriate `implicits` option for complete message enumeration when available
 
 ## Test Cases
 
@@ -363,7 +393,7 @@ The following test scenarios should be implemented:
    - Verify Ethereum APIs exclude implicit messages from counts and lists
    - Verify direct query APIs return implicit messages when queried by CID/hash
    - Verify `eth_getLogs` excludes events from implicit messages
-   - Test suggested `ChainGetAllParentReceipts` or v2 variant returns all receipts
+   - Test v2 APIs with different `implicits` options
 
 ## Security Considerations
 
@@ -429,7 +459,7 @@ Implementation requires changes to:
    - Update message retrieval methods to filter implicit messages by default
    - Update receipt retrieval methods to filter implicit message receipts
    - Add `implicit` field to `ActorEvent` type
-   - Implement suggested `ChainGetAllParentReceipts` API
+   - Implement v2 APIs with options parameter supporting `implicits` enum
    - Update Ethereum APIs to maintain backward compatibility
 
 4. **FVM changes**: