feat: decode market data and extract prediction type (#177)

Author: MicBun

core/contractsapi/attestation_encoding.go

@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"encoding/binary"
 	"fmt"
+	"io"
 
 	"github.com/trufnetwork/kwil-db/core/types"
 )
@@ -57,3 +58,57 @@ func EncodeActionArgs(args []any) ([]byte, error) {
 
 	return buf.Bytes(), nil
 }
+
+// DecodeActionArgs decodes canonical bytes back into action arguments.
+// This is the inverse operation of EncodeActionArgs.
+//
+// Returns an error if:
+//   - Data is too short to contain arg count
+//   - Individual arguments fail to decode
+//   - Type information is invalid
+func DecodeActionArgs(data []byte) ([]any, error) {
+	if len(data) < 4 {
+		return nil, fmt.Errorf("data too short for arg count")
+	}
+
+	buf := bytes.NewReader(data)
+
+	// Read argument count (little-endian uint32)
+	var argCount uint32
+	if err := binary.Read(buf, binary.LittleEndian, &argCount); err != nil {
+		return nil, fmt.Errorf("failed to read arg count: %w", err)
+	}
+
+	args := make([]any, argCount)
+
+	// Decode each argument
+	for i := uint32(0); i < argCount; i++ {
+		// Read argument length (little-endian uint32)
+		var argLen uint32
+		if err := binary.Read(buf, binary.LittleEndian, &argLen); err != nil {
+			return nil, fmt.Errorf("failed to read arg %d length: %w", i, err)
+		}
+
+		// Read argument bytes
+		argBytes := make([]byte, argLen)
+		if _, err := io.ReadFull(buf, argBytes); err != nil {
+			return nil, fmt.Errorf("failed to read arg %d bytes: %w", i, err)
+		}
+
+		// Unmarshal EncodedValue
+		var encodedVal types.EncodedValue
+		if err := encodedVal.UnmarshalBinary(argBytes); err != nil {
+			return nil, fmt.Errorf("failed to unmarshal arg %d: %w", i, err)
+		}
+
+		// Decode to Go value
+		decodedVal, err := encodedVal.Decode()
+		if err != nil {
+			return nil, fmt.Errorf("failed to decode arg %d value: %w", i, err)
+		}
+
+		args[i] = decodedVal
+	}
+
+	return args, nil
+}

core/contractsapi/order_book_markets_test.go

@@ -371,3 +371,63 @@ func TestDecodeQueryComponents(t *testing.T) {
 	require.Equal(t, actionID, decodedActionID)
 	require.Equal(t, args, decodedArgs)
 }
+
+func TestDecodeMarketData(t *testing.T) {
+	dataProvider := "0x1111111111111111111111111111111111111111"
+	streamID := "stbtcusd000000000000000000000000"
+
+	tests := []struct {
+		name       string
+		actionID   string
+		args       []any
+		expectType string
+		expectThresh []string
+	}{
+		{
+			name:       "Price Above",
+			actionID:   "price_above_threshold",
+			args:       []any{"0x...", "stream", int64(123), "100000", nil},
+			expectType: "above",
+			expectThresh: []string{"100000"},
+		},
+		{
+			name:       "Price Below",
+			actionID:   "price_below_threshold",
+			args:       []any{"0x...", "stream", int64(123), "4.5", nil},
+			expectType: "below",
+			expectThresh: []string{"4.5"},
+		},
+		{
+			name:       "Value In Range",
+			actionID:   "value_in_range",
+			args:       []any{"0x...", "stream", int64(123), "90000", "110000", nil},
+			expectType: "between",
+			expectThresh: []string{"90000", "110000"},
+		},
+		{
+			name:       "Value Equals",
+			actionID:   "value_equals",
+			args:       []any{"0x...", "stream", int64(123), "5.25", "0.01", nil},
+			expectType: "equals",
+			expectThresh: []string{"5.25", "0.01"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			argsBytes, err := EncodeActionArgs(tt.args)
+			require.NoError(t, err)
+
+			encoded, err := EncodeQueryComponents(dataProvider, streamID, tt.actionID, argsBytes)
+			require.NoError(t, err)
+
+			market, err := DecodeMarketData(encoded)
+			require.NoError(t, err)
+
+			require.Equal(t, tt.expectType, market.Type)
+			require.Equal(t, tt.expectThresh, market.Thresholds)
+			require.Equal(t, streamID, market.StreamID)
+			require.Equal(t, tt.actionID, market.ActionID)
+		})
+	}
+}

core/contractsapi/query_components.go

@@ -2,6 +2,7 @@ package contractsapi
 
 import (
 	"fmt"
+	"reflect"
 
 	"github.com/ethereum/go-ethereum/accounts/abi"
 	"github.com/ethereum/go-ethereum/common"
@@ -139,3 +140,88 @@ func DecodeQueryComponents(encoded []byte) (dataProvider, streamID, actionID str
 
 	return dataProvider, streamID, actionID, args, nil
 }
+
+// MarketData represents the structured content of a prediction market's query components
+type MarketData struct {
+	DataProvider string   `json:"data_provider"`
+	StreamID     string   `json:"stream_id"`
+	ActionID     string   `json:"action_id"`
+	Type         string   `json:"type"`       // "above", "below", "between", "equals"
+	Thresholds   []string `json:"thresholds"` // Formatted numeric values
+}
+
+// DecodeMarketData decodes ABI-encoded query_components into high-level MarketData
+func DecodeMarketData(encoded []byte) (*MarketData, error) {
+	dataProvider, streamID, actionID, argsBytes, err := DecodeQueryComponents(encoded)
+	if err != nil {
+		return nil, err
+	}
+
+	args, err := DecodeActionArgs(argsBytes)
+	if err != nil {
+		return nil, fmt.Errorf("failed to decode action args: %w", err)
+	}
+
+	market := &MarketData{
+		DataProvider: dataProvider,
+		StreamID:     streamID,
+		ActionID:     actionID,
+		Thresholds:   []string{},
+	}
+
+	// Helper to format arguments (handling Decimal and pointer types)
+	formatArg := func(arg any) string {
+		if arg == nil {
+			return ""
+		}
+		
+		// Handle *string directly (common in decoded results)
+		if s, ok := arg.(*string); ok {
+			if s == nil {
+				return ""
+			}
+			return *s
+		}
+
+		// Use reflection to find String() method (handles other pointer types like *Decimal)
+		v := reflect.ValueOf(arg)
+		method := v.MethodByName("String")
+		if method.IsValid() && method.Type().NumIn() == 0 && method.Type().NumOut() == 1 {
+			results := method.Call(nil)
+			if s, ok := results[0].Interface().(string); ok {
+				return s
+			}
+		}
+
+		return fmt.Sprint(arg)
+	}
+
+	// Map action_id to market type and thresholds
+	// Based on 040-binary-attestation-actions.sql
+	switch actionID {
+	case "price_above_threshold":
+		market.Type = "above"
+		if len(args) >= 4 {
+			market.Thresholds = append(market.Thresholds, formatArg(args[3]))
+		}
+	case "price_below_threshold":
+		market.Type = "below"
+		if len(args) >= 4 {
+			market.Thresholds = append(market.Thresholds, formatArg(args[3]))
+		}
+	case "value_in_range":
+		market.Type = "between"
+		if len(args) >= 5 {
+			market.Thresholds = append(market.Thresholds, formatArg(args[3]), formatArg(args[4]))
+		}
+	case "value_equals":
+		market.Type = "equals"
+		if len(args) >= 5 {
+			market.Thresholds = append(market.Thresholds, formatArg(args[3]), formatArg(args[4]))
+		}
+	default:
+		market.Type = "unknown"
+	}
+
+	return market, nil
+}

docs/api-reference.md

@@ -1679,6 +1679,77 @@ if err != nil {
 }
 ```
 
+## Prediction Market Data Decoding
+
+The `contractsapi` package provides high-level utilities for decoding prediction market query components. This is essential for extracting market types (above, below, between) and threshold values from `marketInfo.QueryComponents`.
+
+### Core Methods
+
+#### `DecodeMarketData`
+
+Decodes ABI-encoded `query_components` into a structured `MarketData` object.
+
+**Signature:**
+```go
+func DecodeMarketData(encoded []byte) (*MarketData, error)
+```
+
+**Parameters:**
+- `encoded` ([]byte): The `QueryComponents` field from a `MarketInfo` object.
+
+**Returns:**
+- `*MarketData`: Structured market information.
+- `error`: Error if decoding fails.
+
+**Example:**
+```go
+import "github.com/trufnetwork/sdk-go/core/contractsapi"
+
+// market.QueryComponents is []byte from the node
+data, err := contractsapi.DecodeMarketData(market.QueryComponents)
+if err != nil {
+    log.Fatal(err)
+}
+
+fmt.Printf("Type: %s\n", data.Type)             // e.g. "above"
+fmt.Printf("Thresholds: %v\n", data.Thresholds) // e.g. ["100000"]
+```
+
+---
+
+#### `DecodeActionArgs`
+
+Decodes Kwil-native canonical bytes back into a slice of action arguments.
+
+**Signature:**
+```go
+func DecodeActionArgs(data []byte) ([]any, error) {
+```
+
+**Example:**
+```go
+args, err := contractsapi.DecodeActionArgs(argsBytes)
+for i, arg := range args {
+    fmt.Printf("Arg %d: %v (Type: %T)\n", i, arg, arg)
+}
+```
+
+### Types
+
+#### `MarketData`
+
+```go
+type MarketData struct {
+    DataProvider string   `json:"data_provider"`
+    StreamID     string   `json:"stream_id"`
+    ActionID     string   `json:"action_id"`
+    Type         string   `json:"type"`       // "above", "below", "between", "equals" or "unknown"
+    Thresholds   []string `json:"thresholds"` // Formatted numeric values as strings
+}
+```
+
+---
+
 ## Attestation Actions Interface
 
 ### Overview

examples/decode_market_example/main.go

@@ -0,0 +1,76 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+
+	"github.com/trufnetwork/kwil-db/core/crypto"
+	"github.com/trufnetwork/kwil-db/core/crypto/auth"
+	"github.com/trufnetwork/sdk-go/core/contractsapi"
+	"github.com/trufnetwork/sdk-go/core/tnclient"
+	"github.com/trufnetwork/sdk-go/core/types"
+)
+
+func main() {
+	// Configuration
+	endpoint := "https://gateway.testnet.truf.network"
+	// Use a dummy private key for read-only operation
+	privateKeyHex := "0000000000000000000000000000000000000000000000000000000000000001"
+
+	fmt.Println("--- Prediction Market Decoding Example (Real Data) ---")
+	fmt.Printf("Endpoint: %s\n\n", endpoint)
+
+	// 1. Initialize Client
+	ctx := context.Background()
+	pk, _ := crypto.Secp256k1PrivateKeyFromHex(privateKeyHex)
+	signer := &auth.EthPersonalSigner{Key: *pk}
+
+	client, err := tnclient.NewClient(ctx, endpoint, tnclient.WithSigner(signer))
+	if err != nil {
+		log.Fatalf("Failed to create client: %v", err)
+	}
+
+	// 2. Load Order Book
+	orderBook, err := client.LoadOrderBook()
+	if err != nil {
+		log.Fatalf("Failed to load order book: %v", err)
+	}
+
+	// 3. List Latest Markets
+	limit := 3
+	markets, err := orderBook.ListMarkets(ctx, types.ListMarketsInput{
+		Limit: &limit,
+	})
+	if err != nil {
+		log.Fatalf("Failed to list markets: %v", err)
+	}
+
+	fmt.Printf("Found %d latest markets. Decoding details...\n\n", len(markets))
+
+	// 4. Fetch and Decode each market
+	for _, m := range markets {
+		fmt.Printf("Processing Market ID: %d\n", m.ID)
+
+		// Fetch full info (including queryComponents)
+		marketInfo, err := orderBook.GetMarketInfo(ctx, types.GetMarketInfoInput{
+			QueryID: m.ID,
+		})
+		if err != nil {
+			fmt.Printf("  Error fetching info: %v\n\n", err)
+			continue
+		}
+
+		// Decode components
+		data, err := contractsapi.DecodeMarketData(marketInfo.QueryComponents)
+		if err != nil {
+			fmt.Printf("  Error decoding data: %v\n\n", err)
+			continue
+		}
+
+		fmt.Printf("  Market Type:   %s\n", data.Type)
+		fmt.Printf("  Thresholds:    %v\n", data.Thresholds)
+		fmt.Printf("  Action:        %s\n", data.ActionID)
+		fmt.Printf("  Stream:        %s\n\n", data.StreamID)
+	}
+}

examples/history_example/main.go

@@ -18,10 +18,10 @@ func main() {
 	ctx := context.Background()
 
 	// 1. Initialize Client
-	// Use environment variable for private key to avoid hardcoding
+	// Use environment variable for private key or default to test key
 	privateKeyHex := os.Getenv("TN_PRIVATE_KEY")
 	if privateKeyHex == "" {
-		log.Fatal("TN_PRIVATE_KEY environment variable is required")
+		privateKeyHex = "0000000000000000000000000000000000000000000000000000000000000001"
 	}
 
 	pk, err := crypto.Secp256k1PrivateKeyFromHex(privateKeyHex)