@blinklabs/dingo 0.6.0

package/database/plugin/metadata/sqlite/utxo.go

@@ -0,0 +1,292 @@
+// Copyright 2025 Blink Labs Software
+//
+// 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 sqlite
+
+import (
+	"fmt"
+
+	"github.com/blinklabs-io/dingo/database/plugin/metadata/sqlite/models"
+	"github.com/blinklabs-io/gouroboros/ledger"
+	"gorm.io/gorm"
+)
+
+// GetUtxo returns a Utxo by reference
+func (d *MetadataStoreSqlite) GetUtxo(
+	txId []byte,
+	idx uint32,
+	txn *gorm.DB,
+) (models.Utxo, error) {
+	ret := models.Utxo{}
+	tmpUtxo := models.Utxo{}
+	if txn != nil {
+		result := txn.Where("deleted_slot = 0").
+			First(&tmpUtxo, "tx_id = ? AND output_idx = ?", txId, idx)
+		if result.Error != nil {
+			return ret, result.Error
+		}
+	} else {
+		result := d.DB().Where("deleted_slot = 0").First(&tmpUtxo, "tx_id = ? AND output_idx = ?", txId, idx)
+		if result.Error != nil {
+			return ret, result.Error
+		}
+	}
+	ret = tmpUtxo
+	return ret, nil
+}
+
+// GetUtxosAddedAfterSlot returns a list of Utxos added after a given slot
+func (d *MetadataStoreSqlite) GetUtxosAddedAfterSlot(
+	slot uint64,
+	txn *gorm.DB,
+) ([]models.Utxo, error) {
+	var ret []models.Utxo
+	if txn != nil {
+		result := txn.Where("added_slot > 0", slot).
+			Order("id DESC").
+			Find(&ret)
+		if result.Error != nil {
+			return ret, result.Error
+		}
+	} else {
+		result := d.DB().Where("added_slot > 0", slot).
+			Order("id DESC").
+			Find(&ret)
+		if result.Error != nil {
+			return ret, result.Error
+		}
+	}
+	return ret, nil
+}
+
+// GetUtxosDeletedBeforeSlot returns a list of Utxos marked as deleted before a given slot
+func (d *MetadataStoreSqlite) GetUtxosDeletedBeforeSlot(
+	slot uint64,
+	txn *gorm.DB,
+) ([]models.Utxo, error) {
+	var ret []models.Utxo
+	if txn != nil {
+		result := txn.Where("deleted_slot > 0 AND deleted_slot <= ?", slot).
+			Order("id DESC").
+			Find(&ret)
+		if result.Error != nil {
+			return ret, result.Error
+		}
+	} else {
+		result := d.DB().Where("deleted_slot > 0 AND deleted_slot <= ?", slot).
+			Order("id DESC").
+			Find(&ret)
+		if result.Error != nil {
+			return ret, result.Error
+		}
+	}
+	return ret, nil
+}
+
+// GetUtxosByAddress returns a list of Utxos
+func (d *MetadataStoreSqlite) GetUtxosByAddress(
+	addr ledger.Address,
+	txn *gorm.DB,
+) ([]models.Utxo, error) {
+	var ret []models.Utxo
+	// Build sub-query for address
+	var addrQuery *gorm.DB
+	if addr.PaymentKeyHash() != ledger.NewBlake2b224(nil) {
+		addrQuery = txn.Where("payment_key = ?", addr.PaymentKeyHash().Bytes())
+	}
+	if addr.StakeKeyHash() != ledger.NewBlake2b224(nil) {
+		if addrQuery != nil {
+			addrQuery = addrQuery.Or(
+				"staking_key = ?",
+				addr.StakeKeyHash().Bytes(),
+			)
+		} else {
+			addrQuery = txn.Where("staking_key = ?", addr.StakeKeyHash().Bytes())
+		}
+	}
+	result := txn.
+		Where("deleted_slot = 0").
+		Where(addrQuery).
+		Find(&ret)
+	if result.Error != nil {
+		return nil, result.Error
+	}
+	return ret, nil
+}
+
+func (d *MetadataStoreSqlite) DeleteUtxo(
+	utxo any,
+	txn *gorm.DB,
+) error {
+	tmpUtxo, ok := utxo.(models.Utxo)
+	if !ok {
+		return fmt.Errorf("failed to convert utxo from %T", utxo)
+	}
+	if txn != nil {
+		result := txn.Delete(&tmpUtxo)
+		if result.Error != nil {
+			return result.Error
+		}
+	} else {
+		result := d.DB().Delete(&tmpUtxo)
+		if result.Error != nil {
+			return result.Error
+		}
+	}
+	return nil
+}
+
+func (d *MetadataStoreSqlite) DeleteUtxos(
+	utxos []any,
+	txn *gorm.DB,
+) error {
+	tmpUtxos := []models.Utxo{}
+	for _, utxo := range utxos {
+		tmpUtxo, ok := utxo.(models.Utxo)
+		if !ok {
+			return fmt.Errorf("failed to convert utxo from %T", utxo)
+		}
+		tmpUtxos = append(tmpUtxos, tmpUtxo)
+	}
+	if txn != nil {
+		result := txn.Delete(&tmpUtxos)
+		if result.Error != nil {
+			return result.Error
+		}
+	} else {
+		result := d.DB().Delete(&tmpUtxos)
+		if result.Error != nil {
+			return result.Error
+		}
+	}
+	return nil
+}
+
+func (d *MetadataStoreSqlite) DeleteUtxosAfterSlot(
+	slot uint64,
+	txn *gorm.DB,
+) error {
+	if txn != nil {
+		result := txn.Where("deleted_slot > ?", slot).
+			Delete(&models.Utxo{})
+		if result.Error != nil {
+			return result.Error
+		}
+	} else {
+		result := d.DB().Where("deleted_slot > ?", slot).
+			Delete(&models.Utxo{})
+		if result.Error != nil {
+			return result.Error
+		}
+	}
+	return nil
+}
+
+// DeleteUtxosBeforeSlot deletes Utxos marked as deleted before a given slot
+func (d *MetadataStoreSqlite) DeleteUtxosBeforeSlot(
+	slot uint64,
+	txn *gorm.DB,
+) error {
+	if txn != nil {
+		result := txn.Where("deleted_slot > 0 AND deleted_slot < ?", slot).
+			Delete(&models.Utxo{})
+		if result.Error != nil {
+			return result.Error
+		}
+	} else {
+		result := d.DB().Where("deleted_slot >0 AND deleted_slot < ?", slot).
+			Delete(&models.Utxo{})
+		if result.Error != nil {
+			return result.Error
+		}
+	}
+	return nil
+}
+
+// SetUtxo saves a UTxO
+func (d *MetadataStoreSqlite) SetUtxo(
+	txId []byte, // hash
+	idx uint32, // idx
+	slot uint64, // slot
+	payment []byte, // payment
+	stake []byte, // stake
+	txn *gorm.DB,
+) error {
+	tmpUtxo := models.Utxo{
+		TxId:       txId,
+		OutputIdx:  idx,
+		AddedSlot:  slot,
+		PaymentKey: payment,
+		StakingKey: stake,
+	}
+	if txn != nil {
+		result := txn.Create(&tmpUtxo)
+		if result.Error != nil {
+			return result.Error
+		}
+	} else {
+		result := d.DB().Create(&tmpUtxo)
+		if result.Error != nil {
+			return result.Error
+		}
+	}
+	return nil
+}
+
+// SetUtxoDeletedAtSlot marks a UTxO as deleted at a given slot
+func (d *MetadataStoreSqlite) SetUtxoDeletedAtSlot(
+	utxoId ledger.TransactionInput,
+	slot uint64,
+	txn *gorm.DB,
+) error {
+	if txn != nil {
+		result := txn.Model(models.Utxo{}).
+			Where("tx_id = ? AND output_idx = ?", utxoId.Id().Bytes(), utxoId.Index()).
+			Update("deleted_slot", slot)
+		if result.Error != nil {
+			return result.Error
+		}
+	} else {
+		result := d.DB().Model(models.Utxo{}).
+			Where("tx_id = ? AND output_idx = ?", utxoId.Id().Bytes(), utxoId.Index()).
+			Update("deleted_slot", slot)
+		if result.Error != nil {
+			return result.Error
+		}
+	}
+	return nil
+}
+
+// SetUtxosNotDeletedAfterSlot marks a list of Utxos as not deleted after a given slot
+func (d *MetadataStoreSqlite) SetUtxosNotDeletedAfterSlot(
+	slot uint64,
+	txn *gorm.DB,
+) error {
+	if txn != nil {
+		result := txn.Model(models.Utxo{}).
+			Where("deleted_slot > ?", slot).
+			Update("deleted_slot", 0)
+		if result.Error != nil {
+			return result.Error
+		}
+	} else {
+		result := d.DB().Model(models.Utxo{}).
+			Where("deleted_slot > ?", slot).
+			Update("deleted_slot", 0)
+		if result.Error != nil {
+			return result.Error
+		}
+	}
+	return nil
+}

package/database/plugin/metadata/store.go

@@ -0,0 +1,168 @@
+// Copyright 2025 Blink Labs Software
+//
+// 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 metadata
+
+import (
+	"log/slog"
+
+	"github.com/blinklabs-io/dingo/database/plugin/metadata/sqlite"
+	"github.com/blinklabs-io/dingo/database/plugin/metadata/sqlite/models"
+	"github.com/blinklabs-io/gouroboros/ledger"
+	lcommon "github.com/blinklabs-io/gouroboros/ledger/common"
+	ochainsync "github.com/blinklabs-io/gouroboros/protocol/chainsync"
+	"gorm.io/gorm"
+)
+
+type MetadataStore interface {
+	// Database
+	Close() error
+	DB() *gorm.DB
+	GetCommitTimestamp() (int64, error)
+	SetCommitTimestamp(*gorm.DB, int64) error
+	Transaction() *gorm.DB
+
+	// Ledger state
+	GetPoolRegistrations(
+		lcommon.PoolKeyHash,
+		*gorm.DB,
+	) ([]lcommon.PoolRegistrationCertificate, error)
+	GetStakeRegistrations(
+		[]byte, // stakeKey
+		*gorm.DB,
+	) ([]lcommon.StakeRegistrationCertificate, error)
+	GetTip(*gorm.DB) (ochainsync.Tip, error)
+
+	GetAccount(
+		[]byte, // stakeKey
+		*gorm.DB,
+	) (models.Account, error)
+	GetPParams(
+		uint64, // epoch
+		*gorm.DB,
+	) ([]models.PParams, error)
+	GetPParamUpdates(
+		uint64, // epoch
+		*gorm.DB,
+	) ([]models.PParamUpdate, error)
+	GetUtxo(
+		[]byte, // txId
+		uint32, // idx
+		*gorm.DB,
+	) (models.Utxo, error)
+
+	SetAccount(
+		[]byte, // stakeKey
+		[]byte, // pkh
+		[]byte, // drep
+		uint64, // slot
+		bool, // active
+		*gorm.DB,
+	) error
+	SetDeregistration(
+		*lcommon.DeregistrationCertificate,
+		uint64, // slot
+		*gorm.DB,
+	) error
+	SetEpoch(
+		uint64, // slot
+		uint64, // epoch
+		[]byte, // nonce
+		uint, // era
+		uint, // slotLength
+		uint, // lengthInSlots
+		*gorm.DB,
+	) error
+	SetPoolRegistration(
+		*lcommon.PoolRegistrationCertificate,
+		uint64, // slot
+		uint64, // deposit
+		*gorm.DB,
+	) error
+	SetPoolRetirement(
+		*lcommon.PoolRetirementCertificate,
+		uint64, // slot
+		*gorm.DB,
+	) error
+	SetPParams(
+		[]byte, // pparams
+		uint64, // slot
+		uint64, // epoch
+		uint, // era
+		*gorm.DB,
+	) error
+	SetPParamUpdate(
+		[]byte, // genesis
+		[]byte, // update
+		uint64, // slot
+		uint64, // epoch
+		*gorm.DB,
+	) error
+	SetRegistration(
+		*lcommon.RegistrationCertificate,
+		uint64, // slot
+		uint64, // deposit
+		*gorm.DB,
+	) error
+	SetStakeDelegation(
+		*lcommon.StakeDelegationCertificate,
+		uint64, // slot
+		*gorm.DB,
+	) error
+	SetStakeDeregistration(
+		*lcommon.StakeDeregistrationCertificate,
+		uint64, // slot
+		*gorm.DB,
+	) error
+	SetStakeRegistration(
+		*lcommon.StakeRegistrationCertificate,
+		uint64, // slot
+		uint64, // deposit
+		*gorm.DB,
+	) error
+	SetTip(
+		ochainsync.Tip,
+		*gorm.DB,
+	) error
+	SetUtxo(
+		[]byte, // hash
+		uint32, // idx
+		uint64, // slot
+		[]byte, // payment
+		[]byte, // stake
+		*gorm.DB,
+	) error
+
+	// Helpers
+	DeleteUtxo(any, *gorm.DB) error
+	DeleteUtxos([]any, *gorm.DB) error
+	DeleteUtxosAfterSlot(uint64, *gorm.DB) error
+	DeleteUtxosBeforeSlot(uint64, *gorm.DB) error
+	GetEpochLatest(*gorm.DB) (models.Epoch, error)
+	GetEpochsByEra(uint, *gorm.DB) ([]models.Epoch, error)
+	GetEpochs(*gorm.DB) ([]models.Epoch, error)
+	GetUtxosAddedAfterSlot(uint64, *gorm.DB) ([]models.Utxo, error)
+	GetUtxosByAddress(ledger.Address, *gorm.DB) ([]models.Utxo, error)
+	GetUtxosDeletedBeforeSlot(uint64, *gorm.DB) ([]models.Utxo, error)
+	SetUtxoDeletedAtSlot(ledger.TransactionInput, uint64, *gorm.DB) error
+	SetUtxosNotDeletedAfterSlot(uint64, *gorm.DB) error
+}
+
+// For now, this always returns a sqlite plugin
+func New(
+	pluginName, dataDir string,
+	logger *slog.Logger,
+) (MetadataStore, error) {
+	return sqlite.New(dataDir, logger)
+}

package/database/plugin/option.go

@@ -0,0 +1,190 @@
+// Copyright 2025 Blink Labs Software
+//
+// 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 plugin
+
+import (
+	"flag"
+	"fmt"
+	"os"
+	"strconv"
+	"strings"
+)
+
+type PluginOptionType int
+
+const (
+	PluginOptionTypeString PluginOptionType = 1
+	PluginOptionTypeBool   PluginOptionType = 2
+	PluginOptionTypeInt    PluginOptionType = 3
+	PluginOptionTypeUint   PluginOptionType = 4
+)
+
+type PluginOption struct {
+	Name         string
+	Type         PluginOptionType
+	CustomEnvVar string
+	CustomFlag   string
+	Description  string
+	DefaultValue interface{}
+	Dest         interface{}
+}
+
+func (p *PluginOption) AddToFlagSet(
+	fs *flag.FlagSet,
+	pluginType string,
+	pluginName string,
+) error {
+	var flagName string
+	if p.CustomFlag != "" {
+		flagName = fmt.Sprintf("%s-%s", pluginType, p.CustomFlag)
+	} else {
+		flagName = fmt.Sprintf("%s-%s-%s", pluginType, pluginName, p.Name)
+	}
+	switch p.Type {
+	case PluginOptionTypeString:
+		fs.StringVar(
+			p.Dest.(*string),
+			flagName,
+			p.DefaultValue.(string),
+			p.Description,
+		)
+	case PluginOptionTypeBool:
+		fs.BoolVar(
+			p.Dest.(*bool),
+			flagName,
+			p.DefaultValue.(bool),
+			p.Description,
+		)
+	case PluginOptionTypeInt:
+		fs.IntVar(p.Dest.(*int), flagName, p.DefaultValue.(int), p.Description)
+	case PluginOptionTypeUint:
+		fs.UintVar(
+			p.Dest.(*uint),
+			flagName,
+			p.DefaultValue.(uint),
+			p.Description,
+		)
+	default:
+		return fmt.Errorf(
+			"unknown plugin option type %d for option %s",
+			p.Type,
+			p.Name,
+		)
+	}
+	return nil
+}
+
+func (p *PluginOption) ProcessEnvVars(envPrefix string) error {
+	envVars := []string{
+		// Automatically generate env var from specified prefix and option name
+		strings.ToUpper(
+			strings.ReplaceAll(
+				fmt.Sprintf(
+					"%s%s",
+					envPrefix,
+					p.Name,
+				),
+				"-",
+				"_",
+			),
+		),
+	}
+	// Also check any custom env var specified
+	if p.CustomEnvVar != "" {
+		envVars = append(envVars, p.CustomEnvVar)
+	}
+	for _, envVar := range envVars {
+		if value, ok := os.LookupEnv(envVar); ok {
+			switch p.Type {
+			case PluginOptionTypeString:
+				*(p.Dest.(*string)) = value
+			case PluginOptionTypeBool:
+				value, err := strconv.ParseBool(value)
+				if err != nil {
+					return fmt.Errorf("error processing env vars: %w", err)
+				}
+				*(p.Dest.(*bool)) = value
+			case PluginOptionTypeInt:
+				// We limit to 32-bit to not get inconsistent behavior on 32-bit platforms
+				value, err := strconv.ParseInt(value, 10, 32)
+				if err != nil {
+					return fmt.Errorf("error processing env vars: %w", err)
+				}
+				*(p.Dest.(*int)) = int(value)
+			case PluginOptionTypeUint:
+				// We limit to 32-bit to not get inconsistent behavior on 32-bit platforms
+				value, err := strconv.ParseUint(value, 10, 32)
+				if err != nil {
+					return fmt.Errorf("error processing env vars: %w", err)
+				}
+				*(p.Dest.(*uint)) = uint(value)
+			default:
+				return fmt.Errorf(
+					"unknown plugin option type %d for option %s",
+					p.Type,
+					p.Name,
+				)
+			}
+		}
+	}
+	return nil
+}
+
+func (p *PluginOption) ProcessConfig(
+	pluginData map[interface{}]interface{},
+) error {
+	if optionData, ok := pluginData[p.Name]; ok {
+		switch p.Type {
+		case PluginOptionTypeString:
+			switch value := optionData.(type) {
+			case string:
+				*(p.Dest.(*string)) = value
+			default:
+				return fmt.Errorf("invalid value for option '%s': expected string and got %T", p.Name, optionData)
+			}
+		case PluginOptionTypeBool:
+			switch value := optionData.(type) {
+			case bool:
+				*(p.Dest.(*bool)) = value
+			default:
+				return fmt.Errorf("invalid value for option '%s': expected bool and got %T", p.Name, optionData)
+			}
+		case PluginOptionTypeInt:
+			switch value := optionData.(type) {
+			case int:
+				*(p.Dest.(*int)) = value
+			default:
+				return fmt.Errorf("invalid value for option '%s': expected int and got %T", p.Name, optionData)
+			}
+		case PluginOptionTypeUint:
+			switch value := optionData.(type) {
+			case int:
+				if value < 0 {
+					return fmt.Errorf("invalid value for option '%s': negative value: %T", p.Name, optionData)
+				}
+				*(p.Dest.(*uint)) = uint(value)
+			default:
+				return fmt.Errorf("invalid value for option '%s': expected uint and got %T", p.Name, optionData)
+			}
+		default:
+			return fmt.Errorf(
+				"unknown plugin option type %d for option %s",
+				p.Type,
+				p.Name,
+			)
+		}
+	}
+	return nil
+}

package/database/plugin/plugin.go

@@ -0,0 +1,20 @@
+// Copyright 2025 Blink Labs Software
+//
+// 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 plugin
+
+type Plugin interface {
+	Start() error
+	Stop() error
+}