Merge pull request #41 from gaze-network/develop

Release v0.3.0
feat: add Runes API pagination (#36 )
2026-01-12 22:43:22 +08:00 · 2024-07-25 15:07:51 +07:00 · 2024-07-23 15:46:45 +07:00 · 2024-07-15 18:32:28 +07:00 · 2024-07-15 16:33:56 +07:00 · 2024-07-12 00:18:15 +07:00
46 changed files with 2405 additions and 281 deletions
--- a/.github/workflows/release-server.yml
+++ b/.github/workflows/release-server.yml
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -39,7 +39,7 @@
    "ui.completion.usePlaceholders": false,
    "ui.diagnostic.analyses": {
      // https://github.com/golang/tools/blob/master/gopls/doc/analyzers.md
-      // "fieldalignment": false,
+      "fieldalignment": false,
      "nilness": true,
      "shadow": false,
      "unusedparams": true,
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@

 # Gaze Indexer

-Gaze Indexer is an open-source and modular indexing client for Bitcoin meta-protocols. It has support for Runes out of the box, with **Unified Consistent APIs** across fungible token protocols.
+Gaze Indexer is an open-source and modular indexing client for Bitcoin meta-protocols with **Unified Consistent APIs** across fungible token protocols.

 Gaze Indexer is built with **modularity** in mind, allowing users to run all modules in one monolithic instance with a single command, or as a distributed cluster of micro-services.

--- a/cmd/cmd_run.go
+++ b/cmd/cmd_run.go
@@ -19,9 +19,9 @@ import (
 	"github.com/gaze-network/indexer-network/internal/config"
 	"github.com/gaze-network/indexer-network/modules/runes"
 	"github.com/gaze-network/indexer-network/pkg/automaxprocs"
-	"github.com/gaze-network/indexer-network/pkg/errorhandler"
 	"github.com/gaze-network/indexer-network/pkg/logger"
 	"github.com/gaze-network/indexer-network/pkg/logger/slogx"
+	"github.com/gaze-network/indexer-network/pkg/middleware/errorhandler"
 	"github.com/gaze-network/indexer-network/pkg/middleware/requestcontext"
 	"github.com/gaze-network/indexer-network/pkg/middleware/requestlogger"
 	"github.com/gaze-network/indexer-network/pkg/reportingclient"
@@ -136,8 +136,16 @@ func runHandler(cmd *cobra.Command, _ []string) error {
 	// Initialize HTTP server
 	do.Provide(injector, func(i do.Injector) (*fiber.App, error) {
 		app := fiber.New(fiber.Config{
-			AppName:      "Gaze Indexer",
-			ErrorHandler: errorhandler.NewHTTPErrorHandler(),
+			AppName: "Gaze Indexer",
+			ErrorHandler: func(c *fiber.Ctx, err error) error {
+				logger.ErrorContext(c.UserContext(), "Something went wrong, unhandled api error",
+					slogx.String("event", "api_unhandled_error"),
+					slogx.Error(err),
+				)
+				return errors.WithStack(c.Status(http.StatusInternalServerError).JSON(fiber.Map{
+					"error": "Internal Server Error",
+				}))
+			},
 		})
 		app.
 			Use(favicon.New()).
@@ -156,6 +164,7 @@ func runHandler(cmd *cobra.Command, _ []string) error {
 					logger.ErrorContext(c.UserContext(), "Something went wrong, panic in http handler", slogx.Any("panic", e), slog.String("stacktrace", string(buf)))
 				},
 			})).
+			Use(errorhandler.New()).
 			Use(compress.New(compress.Config{
 				Level: compress.LevelDefault,
 			}))
--- a/core/datasources/bitcoin_node.go
+++ b/core/datasources/bitcoin_node.go
@@ -243,39 +243,32 @@ func (d *BitcoinNodeDatasource) prepareRange(fromHeight, toHeight int64) (start,
 }

 // GetTransaction fetch transaction from Bitcoin node
-func (d *BitcoinNodeDatasource) GetTransactionByHash(ctx context.Context, txHash chainhash.Hash) (*types.Transaction, error) {
+func (d *BitcoinNodeDatasource) GetRawTransactionAndHeightByTxHash(ctx context.Context, txHash chainhash.Hash) (*wire.MsgTx, int64, error) {
 	rawTxVerbose, err := d.btcclient.GetRawTransactionVerbose(&txHash)
 	if err != nil {
-		return nil, errors.Wrap(err, "failed to get raw transaction")
+		return nil, 0, errors.Wrap(err, "failed to get raw transaction")
 	}

 	blockHash, err := chainhash.NewHashFromStr(rawTxVerbose.BlockHash)
 	if err != nil {
-		return nil, errors.Wrap(err, "failed to parse block hash")
+		return nil, 0, errors.Wrap(err, "failed to parse block hash")
 	}
-	block, err := d.btcclient.GetBlockVerboseTx(blockHash)
+	block, err := d.btcclient.GetBlockVerbose(blockHash)
 	if err != nil {
-		return nil, errors.Wrap(err, "failed to get block header")
+		return nil, 0, errors.Wrap(err, "failed to get block header")
 	}

 	// parse tx
 	txBytes, err := hex.DecodeString(rawTxVerbose.Hex)
 	if err != nil {
-		return nil, errors.Wrap(err, "failed to decode transaction hex")
+		return nil, 0, errors.Wrap(err, "failed to decode transaction hex")
 	}
 	var msgTx wire.MsgTx
 	if err := msgTx.Deserialize(bytes.NewReader(txBytes)); err != nil {
-		return nil, errors.Wrap(err, "failed to deserialize transaction")
-	}
-	var txIndex uint32
-	for i, tx := range block.Tx {
-		if tx.Hex == rawTxVerbose.Hex {
-			txIndex = uint32(i)
-			break
-		}
+		return nil, 0, errors.Wrap(err, "failed to deserialize transaction")
 	}

-	return types.ParseMsgTx(&msgTx, block.Height, *blockHash, txIndex), nil
+	return &msgTx, block.Height, nil
 }

 // GetBlockHeader fetch block header from Bitcoin node
--- a/go.mod
+++ b/go.mod
@@ -6,6 +6,7 @@ require (
 	github.com/Cleverse/go-utilities/utils v0.0.0-20240119201306-d71eb577ef11
 	github.com/btcsuite/btcd v0.24.0
 	github.com/btcsuite/btcd/btcutil v1.1.5
+	github.com/btcsuite/btcd/btcutil/psbt v1.1.9
 	github.com/btcsuite/btcd/chaincfg/chainhash v1.1.0
 	github.com/cockroachdb/errors v1.11.1
 	github.com/gaze-network/uint128 v1.3.0
@@ -20,23 +21,24 @@ require (
 	github.com/spf13/cobra v1.8.0
 	github.com/spf13/pflag v1.0.5
 	github.com/spf13/viper v1.18.2
-	github.com/stretchr/testify v1.8.4
+	github.com/stretchr/testify v1.9.0
 	github.com/valyala/fasthttp v1.51.0
 	go.uber.org/automaxprocs v1.5.3
-	golang.org/x/sync v0.5.0
+	golang.org/x/sync v0.7.0
 )

 require (
 	github.com/andybalholm/brotli v1.0.5 // indirect
-	github.com/btcsuite/btcd/btcec/v2 v2.1.3 // indirect
+	github.com/bitonicnl/verify-signed-message v0.7.1
+	github.com/btcsuite/btcd/btcec/v2 v2.3.3 // indirect
 	github.com/btcsuite/btclog v0.0.0-20170628155309-84c8d2346e9f // indirect
 	github.com/btcsuite/go-socks v0.0.0-20170105172521-4720035b7bfd // indirect
 	github.com/btcsuite/websocket v0.0.0-20150119174127-31079b680792 // indirect
 	github.com/cockroachdb/logtags v0.0.0-20230118201751-21c54148d20b // indirect
 	github.com/cockroachdb/redact v1.1.5 // indirect
 	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
-	github.com/decred/dcrd/crypto/blake256 v1.0.0 // indirect
-	github.com/decred/dcrd/dcrec/secp256k1/v4 v4.0.1 // indirect
+	github.com/decred/dcrd/crypto/blake256 v1.0.1 // indirect
+	github.com/decred/dcrd/dcrec/secp256k1/v4 v4.3.0 // indirect
 	github.com/fsnotify/fsnotify v1.7.0 // indirect
 	github.com/getsentry/sentry-go v0.18.0 // indirect
 	github.com/gogo/protobuf v1.3.2 // indirect
@@ -74,10 +76,10 @@ require (
 	github.com/valyala/tcplisten v1.0.0 // indirect
 	go.uber.org/atomic v1.9.0 // indirect
 	go.uber.org/multierr v1.9.0 // indirect
-	golang.org/x/crypto v0.20.0 // indirect
-	golang.org/x/exp v0.0.0-20230905200255-921286631fa9 // indirect
-	golang.org/x/sys v0.17.0 // indirect
-	golang.org/x/text v0.14.0 // indirect
+	golang.org/x/crypto v0.23.0 // indirect
+	golang.org/x/exp v0.0.0-20240525044651-4c93da0ed11d // indirect
+	golang.org/x/sys v0.20.0 // indirect
+	golang.org/x/text v0.15.0 // indirect
 	gopkg.in/ini.v1 v1.67.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )
--- a/go.sum
+++ b/go.sum
@@ -7,18 +7,23 @@ github.com/Microsoft/go-winio v0.6.1/go.mod h1:LRdKpFKfdobln8UmuiYcKPot9D2v6svN5
 github.com/aead/siphash v1.0.1/go.mod h1:Nywa3cDsYNNK3gaciGTWPwHt0wlpNV15vwmswBAUSII=
 github.com/andybalholm/brotli v1.0.5 h1:8uQZIdzKmjc/iuPu7O2ioW48L81FgatrcpfFmiq/cCs=
 github.com/andybalholm/brotli v1.0.5/go.mod h1:fO7iG3H7G2nSZ7m0zPUDn85XEX2GTukHGRSepvi9Eig=
+github.com/bitonicnl/verify-signed-message v0.7.1 h1:1Qku9k9WgzobjqBY7tT3CLjWxtTJZxkYNhOV6QeCTjY=
+github.com/bitonicnl/verify-signed-message v0.7.1/go.mod h1:PR60twfJIaHEo9Wb6eJBh8nBHEZIQQx8CvRwh0YmEPk=
 github.com/btcsuite/btcd v0.20.1-beta/go.mod h1:wVuoA8VJLEcwgqHBwHmzLRazpKxTv13Px/pDuV7OomQ=
 github.com/btcsuite/btcd v0.22.0-beta.0.20220111032746-97732e52810c/go.mod h1:tjmYdS6MLJ5/s0Fj4DbLgSbDHbEqLJrtnHecBFkdz5M=
 github.com/btcsuite/btcd v0.23.5-0.20231215221805-96c9fd8078fd/go.mod h1:nm3Bko6zh6bWP60UxwoT5LzdGJsQJaPo6HjduXq9p6A=
 github.com/btcsuite/btcd v0.24.0 h1:gL3uHE/IaFj6fcZSu03SvqPMSx7s/dPzfpG/atRwWdo=
 github.com/btcsuite/btcd v0.24.0/go.mod h1:K4IDc1593s8jKXIF7yS7yCTSxrknB9z0STzc2j6XgE4=
 github.com/btcsuite/btcd/btcec/v2 v2.1.0/go.mod h1:2VzYrv4Gm4apmbVVsSq5bqf1Ec8v56E48Vt0Y/umPgA=
-github.com/btcsuite/btcd/btcec/v2 v2.1.3 h1:xM/n3yIhHAhHy04z4i43C8p4ehixJZMsnrVJkgl+MTE=
 github.com/btcsuite/btcd/btcec/v2 v2.1.3/go.mod h1:ctjw4H1kknNJmRN4iP1R7bTQ+v3GJkZBd6mui8ZsAZE=
+github.com/btcsuite/btcd/btcec/v2 v2.3.3 h1:6+iXlDKE8RMtKsvK0gshlXIuPbyWM/h84Ensb7o3sC0=
+github.com/btcsuite/btcd/btcec/v2 v2.3.3/go.mod h1:zYzJ8etWJQIv1Ogk7OzpWjowwOdXY1W/17j2MW85J04=
 github.com/btcsuite/btcd/btcutil v1.0.0/go.mod h1:Uoxwv0pqYWhD//tfTiipkxNfdhG9UrLwaeswfjfdF0A=
 github.com/btcsuite/btcd/btcutil v1.1.0/go.mod h1:5OapHB7A2hBBWLm48mmw4MOHNJCcUBTwmWH/0Jn8VHE=
 github.com/btcsuite/btcd/btcutil v1.1.5 h1:+wER79R5670vs/ZusMTF1yTcRYE5GUsFbdjdisflzM8=
 github.com/btcsuite/btcd/btcutil v1.1.5/go.mod h1:PSZZ4UitpLBWzxGd5VGOrLnmOjtPP/a6HaFo12zMs00=
+github.com/btcsuite/btcd/btcutil/psbt v1.1.9 h1:UmfOIiWMZcVMOLaN+lxbbLSuoINGS1WmK1TZNI0b4yk=
+github.com/btcsuite/btcd/btcutil/psbt v1.1.9/go.mod h1:ehBEvU91lxSlXtA+zZz3iFYx7Yq9eqnKx4/kSrnsvMY=
 github.com/btcsuite/btcd/chaincfg/chainhash v1.0.0/go.mod h1:7SFka0XMvUgj3hfZtydOrQY2mwhPclbT2snogU7SQQc=
 github.com/btcsuite/btcd/chaincfg/chainhash v1.0.1/go.mod h1:7SFka0XMvUgj3hfZtydOrQY2mwhPclbT2snogU7SQQc=
 github.com/btcsuite/btcd/chaincfg/chainhash v1.1.0 h1:59Kx4K6lzOW5w6nFlA0v5+lk/6sjybR934QNHSJZPTQ=
@@ -50,10 +55,12 @@ github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSs
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
 github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/decred/dcrd/crypto/blake256 v1.0.0 h1:/8DMNYp9SGi5f0w7uCm6d6M4OU2rGFK09Y2A4Xv7EE0=
 github.com/decred/dcrd/crypto/blake256 v1.0.0/go.mod h1:sQl2p6Y26YV+ZOcSTP6thNdn47hh8kt6rqSlvmrXFAc=
-github.com/decred/dcrd/dcrec/secp256k1/v4 v4.0.1 h1:YLtO71vCjJRCBcrPMtQ9nqBsqpA1m5sE92cU+pd5Mcc=
+github.com/decred/dcrd/crypto/blake256 v1.0.1 h1:7PltbUIQB7u/FfZ39+DGa/ShuMyJ5ilcvdfma9wOH6Y=
+github.com/decred/dcrd/crypto/blake256 v1.0.1/go.mod h1:2OfgNZ5wDpcsFmHmCK5gZTPcCXqlm2ArzUIkw9czNJo=
 github.com/decred/dcrd/dcrec/secp256k1/v4 v4.0.1/go.mod h1:hyedUtir6IdtD/7lIxGeCxkaw7y45JueMRL4DIyJDKs=
+github.com/decred/dcrd/dcrec/secp256k1/v4 v4.3.0 h1:rpfIENRNNilwHwZeG5+P150SMrnNEcHYvcCuK6dPZSg=
+github.com/decred/dcrd/dcrec/secp256k1/v4 v4.3.0/go.mod h1:v57UDF4pDQJcEfFUCRop3lJL149eHGSe9Jvczhzjo/0=
 github.com/decred/dcrd/lru v1.0.0/go.mod h1:mxKOwFd7lFjN2GZYsiz/ecgqR6kkYAl+0pz0tEMk218=
 github.com/dhui/dktest v0.4.1 h1:/w+IWuDXVymg3IrRJCHHOkMK10m9aNVMOyD0X12YVTg=
 github.com/dhui/dktest v0.4.1/go.mod h1:DdOqcUpL7vgyP4GlF3X3w7HbSlz8cEQzwewPveYEQbA=
@@ -96,8 +103,8 @@ github.com/golang/snappy v0.0.4/go.mod h1:/XxbfmMg8lxefKM7IXC3fBNl/7bRcc72aCRzEW
 github.com/google/go-cmp v0.3.0/go.mod h1:8QqcDgzrUqlUb/G2PQTWiueGozuR1884gddMywk6iLU=
 github.com/google/go-cmp v0.3.1/go.mod h1:8QqcDgzrUqlUb/G2PQTWiueGozuR1884gddMywk6iLU=
 github.com/google/go-cmp v0.4.0/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
-github.com/google/go-cmp v0.5.9 h1:O2Tfq5qg4qc4AmwVlvv0oLiVAGB7enBSJ2x2DqQFi38=
-github.com/google/go-cmp v0.5.9/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
+github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
 github.com/google/uuid v1.5.0 h1:1p67kYwdtXjb0gL0BPiP1Av9wiZPo5A8z2cWkTZ+eyU=
 github.com/google/uuid v1.5.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/gorilla/websocket v1.5.0 h1:PPwGk2jz7EePpoHN/+ClbZu8SPxiqlu12wZP/3sWmnc=
@@ -218,8 +225,9 @@ github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UV
 github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
-github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk=
 github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
+github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
+github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
 github.com/subosito/gotenv v1.6.0 h1:9NlTDc1FTs4qu0DDq7AEtTPNw6SVm7uBMsUCUjABIf8=
 github.com/subosito/gotenv v1.6.0/go.mod h1:Dk4QP5c2W3ibzajGcXpNraDfq2IrhjMIvMSWPKKo0FU=
 github.com/syndtr/goleveldb v1.0.1-0.20210819022825-2ae1ddf74ef7/go.mod h1:q4W45IWZaF22tdD+VEXcAWRA037jwmWEB5VWYORlTpc=
@@ -243,14 +251,14 @@ golang.org/x/crypto v0.0.0-20170930174604-9419663f5a44/go.mod h1:6SG95UA2DQfeDnf
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
 golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
 golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
-golang.org/x/crypto v0.20.0 h1:jmAMJJZXr5KiCw05dfYK9QnqaqKLYXijU23lsEdcQqg=
-golang.org/x/crypto v0.20.0/go.mod h1:Xwo95rrVNIoSMx9wa1JroENMToLWn3RNVrTBpLHgZPQ=
-golang.org/x/exp v0.0.0-20230905200255-921286631fa9 h1:GoHiUyI/Tp2nVkLI2mCxVkOjsbSXD66ic0XW0js0R9g=
-golang.org/x/exp v0.0.0-20230905200255-921286631fa9/go.mod h1:S2oDrQGGwySpoQPVqRShND87VCbxmc6bL1Yd2oYrm6k=
+golang.org/x/crypto v0.23.0 h1:dIJU/v2J8Mdglj/8rJ6UUOM3Zc9zLZxVZwwxMooUSAI=
+golang.org/x/crypto v0.23.0/go.mod h1:CKFgDieR+mRhux2Lsu27y0fO304Db0wZe70UKqHu0v8=
+golang.org/x/exp v0.0.0-20240525044651-4c93da0ed11d h1:N0hmiNbwsSNwHBAvR3QB5w25pUwH4tK0Y/RltD1j1h4=
+golang.org/x/exp v0.0.0-20240525044651-4c93da0ed11d/go.mod h1:XtvwrStGgqGPLc4cjQfWqZHG1YFdYs6swckp8vpsjnc=
 golang.org/x/mod v0.2.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
 golang.org/x/mod v0.3.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
-golang.org/x/mod v0.12.0 h1:rmsUpXtvNzj340zd98LZ4KntptpfRHwpFOHG188oHXc=
-golang.org/x/mod v0.12.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
+golang.org/x/mod v0.17.0 h1:zY54UmvipHiNd+pm+m0x9KhZ9hl1/7QNMyxXbc6ICqA=
+golang.org/x/mod v0.17.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=
 golang.org/x/net v0.0.0-20180719180050-a680a1efc54d/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
 golang.org/x/net v0.0.0-20180906233101-161cd47e91fd/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
 golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
@@ -265,8 +273,8 @@ golang.org/x/sync v0.0.0-20180314180146-1d60e4601c6f/go.mod h1:RxMgew5VJxzue5/jJ
 golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20190911185100-cd5d95a43a6e/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20201020160332-67f06af15bc9/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
-golang.org/x/sync v0.5.0 h1:60k92dhOjHxJkrqnwsfl8KuaHbn/5dl0lUPUklKo3qE=
-golang.org/x/sync v0.5.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
+golang.org/x/sync v0.7.0 h1:YsImfSBoP9QPYL0xyKJPq0gcaJdG3rInoqxTWbfQu9M=
+golang.org/x/sync v0.7.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
 golang.org/x/sys v0.0.0-20180909124046-d0be0721c37e/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
@@ -279,19 +287,19 @@ golang.org/x/sys v0.0.0-20200814200057-3d37ad5750ed/go.mod h1:h1NjWce9XRLGQEsW7w
 golang.org/x/sys v0.0.0-20200930185726-fdedc70b468f/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.17.0 h1:25cE3gD+tdBA7lp7QfhuV+rJiE9YXTcS3VG1SqssI/Y=
-golang.org/x/sys v0.17.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/sys v0.20.0 h1:Od9JTbYCk261bKm4M/mw7AklTlFYIa0bIp9BgSm1S8Y=
+golang.org/x/sys v0.20.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.3.2/go.mod h1:bEr9sfX3Q8Zfm5fL9x+3itogRgK3+ptLWKqgva+5dAk=
 golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
-golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ=
-golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
+golang.org/x/text v0.15.0 h1:h1V/4gjBv8v9cjcR6+AR5+/cIYK5N/WAgiv4xlsEtAk=
+golang.org/x/text v0.15.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
 golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
 golang.org/x/tools v0.0.0-20200619180055-7c47624df98f/go.mod h1:EkVYQZoAsY45+roYkvgYkIh4xh/qjgUK9TdY2XT94GE=
 golang.org/x/tools v0.0.0-20210106214847-113979e3529a/go.mod h1:emZCQorbCU4vsT4fOWvOPXz4eW1wZW4PmDk9uLelYpA=
-golang.org/x/tools v0.13.0 h1:Iey4qkscZuv0VvIt8E0neZjtPVQFSc870HQ448QgEmQ=
-golang.org/x/tools v0.13.0/go.mod h1:HvlwmtVNQAhOuCjW7xxvovg8wbNq7LwfXh/k7wXUl58=
+golang.org/x/tools v0.21.0 h1:qc0xYgIbsSDt9EyWz05J5wfa7LOVW0YTLOXrqdLAWIw=
+golang.org/x/tools v0.21.0/go.mod h1:aiJjzUbINMkxbQROHiO6hDPo2LHcIPhhQsa9DLh0yGk=
 golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
--- a/modules/runes/api/httphandler/get_balances_by_address.go
+++ b/modules/runes/api/httphandler/get_balances_by_address.go
@@ -1,23 +1,29 @@
 package httphandler

 import (
-	"slices"
-
 	"github.com/cockroachdb/errors"
 	"github.com/gaze-network/indexer-network/common/errs"
+	"github.com/gaze-network/indexer-network/modules/runes/internal/entity"
 	"github.com/gaze-network/indexer-network/modules/runes/runes"
 	"github.com/gaze-network/uint128"
 	"github.com/gofiber/fiber/v2"
 	"github.com/samber/lo"
 )

-type getBalancesByAddressRequest struct {
+type getBalancesRequest struct {
 	Wallet      string `params:"wallet"`
 	Id          string `query:"id"`
 	BlockHeight uint64 `query:"blockHeight"`
+	Limit       int32  `query:"limit"`
+	Offset      int32  `query:"offset"`
 }

-func (r getBalancesByAddressRequest) Validate() error {
+const (
+	getBalancesMaxLimit     = 5000
+	getBalancesDefaultLimit = 100
+)
+
+func (r getBalancesRequest) Validate() error {
 	var errList []error
 	if r.Wallet == "" {
 		errList = append(errList, errors.New("'wallet' is required"))
@@ -25,6 +31,12 @@ func (r getBalancesByAddressRequest) Validate() error {
 	if r.Id != "" && !isRuneIdOrRuneName(r.Id) {
 		errList = append(errList, errors.New("'id' is not valid rune id or rune name"))
 	}
+	if r.Limit < 0 {
+		errList = append(errList, errors.New("'limit' must be non-negative"))
+	}
+	if r.Limit > getBalancesMaxLimit {
+		errList = append(errList, errors.Errorf("'limit' cannot exceed %d", getBalancesMaxLimit))
+	}
 	return errs.WithPublicMessage(errors.Join(errList...), "validation error")
 }

@@ -36,15 +48,15 @@ type balance struct {
 	Decimals uint8            `json:"decimals"`
 }

-type getBalancesByAddressResult struct {
+type getBalancesResult struct {
 	List        []balance `json:"list"`
 	BlockHeight uint64    `json:"blockHeight"`
 }

-type getBalancesByAddressResponse = HttpResponse[getBalancesByAddressResult]
+type getBalancesResponse = HttpResponse[getBalancesResult]

-func (h *HttpHandler) GetBalancesByAddress(ctx *fiber.Ctx) (err error) {
-	var req getBalancesByAddressRequest
+func (h *HttpHandler) GetBalances(ctx *fiber.Ctx) (err error) {
+	var req getBalancesRequest
 	if err := ctx.ParamsParser(&req); err != nil {
 		return errors.WithStack(err)
 	}
@@ -54,6 +66,9 @@ func (h *HttpHandler) GetBalancesByAddress(ctx *fiber.Ctx) (err error) {
 	if err := req.Validate(); err != nil {
 		return errors.WithStack(err)
 	}
+	if req.Limit == 0 {
+		req.Limit = getBalancesDefaultLimit
+	}

 	pkScript, ok := resolvePkScript(h.network, req.Wallet)
 	if !ok {
@@ -64,49 +79,52 @@ func (h *HttpHandler) GetBalancesByAddress(ctx *fiber.Ctx) (err error) {
 	if blockHeight == 0 {
 		blockHeader, err := h.usecase.GetLatestBlock(ctx.UserContext())
 		if err != nil {
+			if errors.Is(err, errs.NotFound) {
+				return errs.NewPublicError("latest block not found")
+			}
 			return errors.Wrap(err, "error during GetLatestBlock")
 		}
 		blockHeight = uint64(blockHeader.Height)
 	}

-	balances, err := h.usecase.GetBalancesByPkScript(ctx.UserContext(), pkScript, blockHeight)
+	balances, err := h.usecase.GetBalancesByPkScript(ctx.UserContext(), pkScript, blockHeight, req.Limit, req.Offset)
 	if err != nil {
+		if errors.Is(err, errs.NotFound) {
+			return errs.NewPublicError("balances not found")
+		}
 		return errors.Wrap(err, "error during GetBalancesByPkScript")
 	}

 	runeId, ok := h.resolveRuneId(ctx.UserContext(), req.Id)
 	if ok {
 		// filter out balances that don't match the requested rune id
-		for key := range balances {
-			if key != runeId {
-				delete(balances, key)
-			}
-		}
+		balances = lo.Filter(balances, func(b *entity.Balance, _ int) bool {
+			return b.RuneId == runeId
+		})
 	}

-	balanceRuneIds := lo.Keys(balances)
+	balanceRuneIds := lo.Map(balances, func(b *entity.Balance, _ int) runes.RuneId {
+		return b.RuneId
+	})
 	runeEntries, err := h.usecase.GetRuneEntryByRuneIdBatch(ctx.UserContext(), balanceRuneIds)
 	if err != nil {
 		return errors.Wrap(err, "error during GetRuneEntryByRuneIdBatch")
 	}

 	balanceList := make([]balance, 0, len(balances))
-	for id, b := range balances {
-		runeEntry := runeEntries[id]
+	for _, b := range balances {
+		runeEntry := runeEntries[b.RuneId]
 		balanceList = append(balanceList, balance{
 			Amount:   b.Amount,
-			Id:       id,
+			Id:       b.RuneId,
 			Name:     runeEntry.SpacedRune,
 			Symbol:   string(runeEntry.Symbol),
 			Decimals: runeEntry.Divisibility,
 		})
 	}
-	slices.SortFunc(balanceList, func(i, j balance) int {
-		return j.Amount.Cmp(i.Amount)
-	})

-	resp := getBalancesByAddressResponse{
-		Result: &getBalancesByAddressResult{
+	resp := getBalancesResponse{
+		Result: &getBalancesResult{
 			BlockHeight: blockHeight,
 			List:        balanceList,
 		},
--- a/modules/runes/api/httphandler/get_balances_by_address_batch.go
+++ b/modules/runes/api/httphandler/get_balances_by_address_batch.go
@@ -3,10 +3,11 @@ package httphandler
 import (
 	"context"
 	"fmt"
-	"slices"

 	"github.com/cockroachdb/errors"
 	"github.com/gaze-network/indexer-network/common/errs"
+	"github.com/gaze-network/indexer-network/modules/runes/internal/entity"
+	"github.com/gaze-network/indexer-network/modules/runes/runes"
 	"github.com/gofiber/fiber/v2"
 	"github.com/samber/lo"
 	"golang.org/x/sync/errgroup"
@@ -16,33 +17,49 @@ type getBalanceQuery struct {
 	Wallet      string `json:"wallet"`
 	Id          string `json:"id"`
 	BlockHeight uint64 `json:"blockHeight"`
+	Limit       int32  `json:"limit"`
+	Offset      int32  `json:"offset"`
 }

-type getBalancesByAddressBatchRequest struct {
+type getBalancesBatchRequest struct {
 	Queries []getBalanceQuery `json:"queries"`
 }

-func (r getBalancesByAddressBatchRequest) Validate() error {
+const getBalancesBatchMaxQueries = 100
+
+func (r getBalancesBatchRequest) Validate() error {
 	var errList []error
-	for _, query := range r.Queries {
+	if len(r.Queries) == 0 {
+		errList = append(errList, errors.New("at least one query is required"))
+	}
+	if len(r.Queries) > getBalancesBatchMaxQueries {
+		errList = append(errList, errors.Errorf("cannot exceed %d queries", getBalancesBatchMaxQueries))
+	}
+	for i, query := range r.Queries {
 		if query.Wallet == "" {
-			errList = append(errList, errors.Errorf("queries[%d]: 'wallet' is required"))
+			errList = append(errList, errors.Errorf("queries[%d]: 'wallet' is required", i))
 		}
 		if query.Id != "" && !isRuneIdOrRuneName(query.Id) {
-			errList = append(errList, errors.Errorf("queries[%d]: 'id' is not valid rune id or rune name"))
+			errList = append(errList, errors.Errorf("queries[%d]: 'id' is not valid rune id or rune name", i))
+		}
+		if query.Limit < 0 {
+			errList = append(errList, errors.Errorf("queries[%d]: 'limit' must be non-negative", i))
+		}
+		if query.Limit > getBalancesMaxLimit {
+			errList = append(errList, errors.Errorf("queries[%d]: 'limit' cannot exceed %d", i, getBalancesMaxLimit))
 		}
 	}
 	return errs.WithPublicMessage(errors.Join(errList...), "validation error")
 }

-type getBalancesByAddressBatchResult struct {
-	List []*getBalancesByAddressResult `json:"list"`
+type getBalancesBatchResult struct {
+	List []*getBalancesResult `json:"list"`
 }

-type getBalancesByAddressBatchResponse = HttpResponse[getBalancesByAddressBatchResult]
+type getBalancesBatchResponse = HttpResponse[getBalancesBatchResult]

-func (h *HttpHandler) GetBalancesByAddressBatch(ctx *fiber.Ctx) (err error) {
-	var req getBalancesByAddressBatchRequest
+func (h *HttpHandler) GetBalancesBatch(ctx *fiber.Ctx) (err error) {
+	var req getBalancesBatchRequest
 	if err := ctx.BodyParser(&req); err != nil {
 		return errors.WithStack(err)
 	}
@@ -53,11 +70,14 @@ func (h *HttpHandler) GetBalancesByAddressBatch(ctx *fiber.Ctx) (err error) {
 	var latestBlockHeight uint64
 	blockHeader, err := h.usecase.GetLatestBlock(ctx.UserContext())
 	if err != nil {
+		if errors.Is(err, errs.NotFound) {
+			return errs.NewPublicError("latest block not found")
+		}
 		return errors.Wrap(err, "error during GetLatestBlock")
 	}
 	latestBlockHeight = uint64(blockHeader.Height)

-	processQuery := func(ctx context.Context, query getBalanceQuery, queryIndex int) (*getBalancesByAddressResult, error) {
+	processQuery := func(ctx context.Context, query getBalanceQuery, queryIndex int) (*getBalancesResult, error) {
 		pkScript, ok := resolvePkScript(h.network, query.Wallet)
 		if !ok {
 			return nil, errs.NewPublicError(fmt.Sprintf("unable to resolve pkscript from \"queries[%d].wallet\"", queryIndex))
@@ -68,50 +88,57 @@ func (h *HttpHandler) GetBalancesByAddressBatch(ctx *fiber.Ctx) (err error) {
 			blockHeight = latestBlockHeight
 		}

-		balances, err := h.usecase.GetBalancesByPkScript(ctx, pkScript, blockHeight)
+		if query.Limit == 0 {
+			query.Limit = getBalancesMaxLimit
+		}
+
+		balances, err := h.usecase.GetBalancesByPkScript(ctx, pkScript, blockHeight, query.Limit, query.Offset)
 		if err != nil {
+			if errors.Is(err, errs.NotFound) {
+				return nil, errs.NewPublicError("balances not found")
+			}
 			return nil, errors.Wrap(err, "error during GetBalancesByPkScript")
 		}

 		runeId, ok := h.resolveRuneId(ctx, query.Id)
 		if ok {
 			// filter out balances that don't match the requested rune id
-			for key := range balances {
-				if key != runeId {
-					delete(balances, key)
-				}
-			}
+			balances = lo.Filter(balances, func(b *entity.Balance, _ int) bool {
+				return b.RuneId == runeId
+			})
 		}

-		balanceRuneIds := lo.Keys(balances)
+		balanceRuneIds := lo.Map(balances, func(b *entity.Balance, _ int) runes.RuneId {
+			return b.RuneId
+		})
 		runeEntries, err := h.usecase.GetRuneEntryByRuneIdBatch(ctx, balanceRuneIds)
 		if err != nil {
+			if errors.Is(err, errs.NotFound) {
+				return nil, errs.NewPublicError("rune not found")
+			}
 			return nil, errors.Wrap(err, "error during GetRuneEntryByRuneIdBatch")
 		}

 		balanceList := make([]balance, 0, len(balances))
-		for id, b := range balances {
-			runeEntry := runeEntries[id]
+		for _, b := range balances {
+			runeEntry := runeEntries[b.RuneId]
 			balanceList = append(balanceList, balance{
 				Amount:   b.Amount,
-				Id:       id,
+				Id:       b.RuneId,
 				Name:     runeEntry.SpacedRune,
 				Symbol:   string(runeEntry.Symbol),
 				Decimals: runeEntry.Divisibility,
 			})
 		}
-		slices.SortFunc(balanceList, func(i, j balance) int {
-			return j.Amount.Cmp(i.Amount)
-		})

-		result := getBalancesByAddressResult{
+		result := getBalancesResult{
 			BlockHeight: blockHeight,
 			List:        balanceList,
 		}
 		return &result, nil
 	}

-	results := make([]*getBalancesByAddressResult, len(req.Queries))
+	results := make([]*getBalancesResult, len(req.Queries))
 	eg, ectx := errgroup.WithContext(ctx.UserContext())
 	for i, query := range req.Queries {
 		i := i
@@ -129,8 +156,8 @@ func (h *HttpHandler) GetBalancesByAddressBatch(ctx *fiber.Ctx) (err error) {
 		return errors.WithStack(err)
 	}

-	resp := getBalancesByAddressBatchResponse{
-		Result: &getBalancesByAddressBatchResult{
+	resp := getBalancesBatchResponse{
+		Result: &getBalancesBatchResult{
 			List: results,
 		},
 	}
--- a/modules/runes/api/httphandler/get_holders.go
+++ b/modules/runes/api/httphandler/get_holders.go
@@ -1,10 +1,13 @@
 package httphandler

 import (
+	"bytes"
 	"encoding/hex"
+	"slices"

 	"github.com/cockroachdb/errors"
 	"github.com/gaze-network/indexer-network/common/errs"
+	"github.com/gaze-network/indexer-network/modules/runes/internal/entity"
 	"github.com/gaze-network/indexer-network/modules/runes/runes"
 	"github.com/gaze-network/uint128"
 	"github.com/gofiber/fiber/v2"
@@ -14,13 +17,26 @@ import (
 type getHoldersRequest struct {
 	Id          string `params:"id"`
 	BlockHeight uint64 `query:"blockHeight"`
+	Limit       int32  `json:"limit"`
+	Offset      int32  `json:"offset"`
 }

+const (
+	getHoldersMaxLimit     = 1000
+	getHoldersDefaultLimit = 100
+)
+
 func (r getHoldersRequest) Validate() error {
 	var errList []error
 	if !isRuneIdOrRuneName(r.Id) {
 		errList = append(errList, errors.New("'id' is not valid rune id or rune name"))
 	}
+	if r.Limit < 0 {
+		errList = append(errList, errors.New("'limit' must be non-negative"))
+	}
+	if r.Limit > getHoldersMaxLimit {
+		errList = append(errList, errors.Errorf("'limit' cannot exceed %d", getHoldersMaxLimit))
+	}
 	return errs.WithPublicMessage(errors.Join(errList...), "validation error")
 }

@@ -61,6 +77,10 @@ func (h *HttpHandler) GetHolders(ctx *fiber.Ctx) (err error) {
 		blockHeight = uint64(blockHeader.Height)
 	}

+	if req.Limit == 0 {
+		req.Limit = getHoldersDefaultLimit
+	}
+
 	var runeId runes.RuneId
 	if req.Id != "" {
 		var ok bool
@@ -72,10 +92,16 @@ func (h *HttpHandler) GetHolders(ctx *fiber.Ctx) (err error) {

 	runeEntry, err := h.usecase.GetRuneEntryByRuneIdAndHeight(ctx.UserContext(), runeId, blockHeight)
 	if err != nil {
-		return errors.Wrap(err, "error during GetHoldersByHeight")
+		if errors.Is(err, errs.NotFound) {
+			return errs.NewPublicError("rune not found")
+		}
+		return errors.Wrap(err, "error during GetRuneEntryByRuneIdAndHeight")
 	}
-	holdingBalances, err := h.usecase.GetBalancesByRuneId(ctx.UserContext(), runeId, blockHeight)
+	holdingBalances, err := h.usecase.GetBalancesByRuneId(ctx.UserContext(), runeId, blockHeight, req.Limit, req.Offset)
 	if err != nil {
+		if errors.Is(err, errs.NotFound) {
+			return errs.NewPublicError("balances not found")
+		}
 		return errors.Wrap(err, "error during GetBalancesByRuneId")
 	}

@@ -101,6 +127,14 @@ func (h *HttpHandler) GetHolders(ctx *fiber.Ctx) (err error) {
 		})
 	}

+	// sort by amount descending, then pk script ascending
+	slices.SortFunc(holdingBalances, func(b1, b2 *entity.Balance) int {
+		if b1.Amount.Cmp(b2.Amount) == 0 {
+			return bytes.Compare(b1.PkScript, b2.PkScript)
+		}
+		return b2.Amount.Cmp(b1.Amount)
+	})
+
 	resp := getHoldersResponse{
 		Result: &getHoldersResult{
 			BlockHeight:  blockHeight,
--- a/modules/runes/api/httphandler/get_token_info.go
+++ b/modules/runes/api/httphandler/get_token_info.go
@@ -83,6 +83,9 @@ func (h *HttpHandler) GetTokenInfo(ctx *fiber.Ctx) (err error) {
 	if blockHeight == 0 {
 		blockHeader, err := h.usecase.GetLatestBlock(ctx.UserContext())
 		if err != nil {
+			if errors.Is(err, errs.NotFound) {
+				return errs.NewPublicError("latest block not found")
+			}
 			return errors.Wrap(err, "error during GetLatestBlock")
 		}
 		blockHeight = uint64(blockHeader.Height)
@@ -99,10 +102,16 @@ func (h *HttpHandler) GetTokenInfo(ctx *fiber.Ctx) (err error) {

 	runeEntry, err := h.usecase.GetRuneEntryByRuneIdAndHeight(ctx.UserContext(), runeId, blockHeight)
 	if err != nil {
+		if errors.Is(err, errs.NotFound) {
+			return errs.NewPublicError("rune not found")
+		}
 		return errors.Wrap(err, "error during GetTokenInfoByHeight")
 	}
-	holdingBalances, err := h.usecase.GetBalancesByRuneId(ctx.UserContext(), runeId, blockHeight)
+	holdingBalances, err := h.usecase.GetBalancesByRuneId(ctx.UserContext(), runeId, blockHeight, -1, 0) // get all balances
 	if err != nil {
+		if errors.Is(err, errs.NotFound) {
+			return errs.NewPublicError("rune not found")
+		}
 		return errors.Wrap(err, "error during GetBalancesByRuneId")
 	}

--- a/modules/runes/api/httphandler/get_transactions.go
+++ b/modules/runes/api/httphandler/get_transactions.go
@@ -1,7 +1,9 @@
 package httphandler

 import (
+	"cmp"
 	"encoding/hex"
+	"fmt"
 	"slices"

 	"github.com/btcsuite/btcd/chaincfg/chainhash"
@@ -14,16 +16,36 @@ import (
 )

 type getTransactionsRequest struct {
-	Wallet      string `query:"wallet"`
-	Id          string `query:"id"`
-	BlockHeight uint64 `query:"blockHeight"`
+	Wallet    string `query:"wallet"`
+	Id        string `query:"id"`
+	FromBlock int64  `query:"fromBlock"`
+	ToBlock   int64  `query:"toBlock"`
+	Limit     int32  `query:"limit"`
+	Offset    int32  `query:"offset"`
 }

+const (
+	getTransactionsMaxLimit     = 3000
+	getTransactionsDefaultLimit = 100
+)
+
 func (r getTransactionsRequest) Validate() error {
 	var errList []error
 	if r.Id != "" && !isRuneIdOrRuneName(r.Id) {
 		errList = append(errList, errors.New("'id' is not valid rune id or rune name"))
 	}
+	if r.FromBlock < -1 {
+		errList = append(errList, errors.Errorf("invalid fromBlock range"))
+	}
+	if r.ToBlock < -1 {
+		errList = append(errList, errors.Errorf("invalid toBlock range"))
+	}
+	if r.Limit < 0 {
+		errList = append(errList, errors.New("'limit' must be non-negative"))
+	}
+	if r.Limit > getTransactionsMaxLimit {
+		errList = append(errList, errors.Errorf("'limit' cannot exceed %d", getTransactionsMaxLimit))
+	}
 	return errs.WithPublicMessage(errors.Join(errList...), "validation error")
 }

@@ -124,19 +146,42 @@ func (h *HttpHandler) GetTransactions(ctx *fiber.Ctx) (err error) {
 			return errs.NewPublicError("unable to resolve rune id from \"id\"")
 		}
 	}
-
-	blockHeight := req.BlockHeight
-	// set blockHeight to the latest block height blockHeight, pkScript, and runeId are not provided
-	if blockHeight == 0 && pkScript == nil && runeId == (runes.RuneId{}) {
-		blockHeader, err := h.usecase.GetLatestBlock(ctx.UserContext())
-		if err != nil {
-			return errors.Wrap(err, "error during GetLatestBlock")
-		}
-		blockHeight = uint64(blockHeader.Height)
+	if req.Limit == 0 {
+		req.Limit = getTransactionsDefaultLimit
 	}

-	txs, err := h.usecase.GetRuneTransactions(ctx.UserContext(), pkScript, runeId, blockHeight)
+	// default to latest block
+	if req.ToBlock == 0 {
+		req.ToBlock = -1
+	}
+
+	// get latest block height if block height is -1
+	if req.FromBlock == -1 || req.ToBlock == -1 {
+		blockHeader, err := h.usecase.GetLatestBlock(ctx.UserContext())
+		if err != nil {
+			if errors.Is(err, errs.NotFound) {
+				return errs.NewPublicError("latest block not found")
+			}
+			return errors.Wrap(err, "error during GetLatestBlock")
+		}
+		if req.FromBlock == -1 {
+			req.FromBlock = blockHeader.Height
+		}
+		if req.ToBlock == -1 {
+			req.ToBlock = blockHeader.Height
+		}
+	}
+
+	// validate block height range
+	if req.FromBlock > req.ToBlock {
+		return errs.NewPublicError(fmt.Sprintf("fromBlock must be less than or equal to toBlock, got fromBlock=%d, toBlock=%d", req.FromBlock, req.ToBlock))
+	}
+
+	txs, err := h.usecase.GetRuneTransactions(ctx.UserContext(), pkScript, runeId, uint64(req.FromBlock), uint64(req.ToBlock), req.Limit, req.Offset)
 	if err != nil {
+		if errors.Is(err, errs.NotFound) {
+			return errs.NewPublicError("transactions not found")
+		}
 		return errors.Wrap(err, "error during GetRuneTransactions")
 	}

@@ -158,6 +203,9 @@ func (h *HttpHandler) GetTransactions(ctx *fiber.Ctx) (err error) {
 	allRuneIds = lo.Uniq(allRuneIds)
 	runeEntries, err := h.usecase.GetRuneEntryByRuneIdBatch(ctx.UserContext(), allRuneIds)
 	if err != nil {
+		if errors.Is(err, errs.NotFound) {
+			return errs.NewPublicError("rune entries not found")
+		}
 		return errors.Wrap(err, "error during GetRuneEntryByRuneIdBatch")
 	}

@@ -256,12 +304,12 @@ func (h *HttpHandler) GetTransactions(ctx *fiber.Ctx) (err error) {
 		}
 		txList = append(txList, respTx)
 	}
-	// sort by block height ASC, then index ASC
+	// sort by block height DESC, then index DESC
 	slices.SortFunc(txList, func(t1, t2 transaction) int {
 		if t1.BlockHeight != t2.BlockHeight {
-			return int(t1.BlockHeight - t2.BlockHeight)
+			return cmp.Compare(t2.BlockHeight, t1.BlockHeight)
 		}
-		return int(t1.Index - t2.Index)
+		return cmp.Compare(t2.Index, t1.Index)
 	})

 	resp := getTransactionsResponse{
--- a/modules/runes/api/httphandler/get_utxos_by_address.go
+++ b/modules/runes/api/httphandler/get_utxos_by_address.go
@@ -2,7 +2,6 @@ package httphandler

 import (
 	"github.com/btcsuite/btcd/chaincfg/chainhash"
-	"github.com/btcsuite/btcd/wire"
 	"github.com/cockroachdb/errors"
 	"github.com/gaze-network/indexer-network/common/errs"
 	"github.com/gaze-network/indexer-network/modules/runes/internal/entity"
@@ -12,13 +11,20 @@ import (
 	"github.com/samber/lo"
 )

-type getUTXOsByAddressRequest struct {
+type getUTXOsRequest struct {
 	Wallet      string `params:"wallet"`
 	Id          string `query:"id"`
 	BlockHeight uint64 `query:"blockHeight"`
+	Limit       int32  `query:"limit"`
+	Offset      int32  `query:"offset"`
 }

-func (r getUTXOsByAddressRequest) Validate() error {
+const (
+	getUTXOsMaxLimit     = 3000
+	getUTXOsDefaultLimit = 100
+)
+
+func (r getUTXOsRequest) Validate() error {
 	var errList []error
 	if r.Wallet == "" {
 		errList = append(errList, errors.New("'wallet' is required"))
@@ -26,6 +32,12 @@ func (r getUTXOsByAddressRequest) Validate() error {
 	if r.Id != "" && !isRuneIdOrRuneName(r.Id) {
 		errList = append(errList, errors.New("'id' is not valid rune id or rune name"))
 	}
+	if r.Limit < 0 {
+		errList = append(errList, errors.New("'limit' must be non-negative"))
+	}
+	if r.Limit > getUTXOsMaxLimit {
+		errList = append(errList, errors.Errorf("'limit' cannot exceed %d", getUTXOsMaxLimit))
+	}
 	return errs.WithPublicMessage(errors.Join(errList...), "validation error")
 }

@@ -41,21 +53,21 @@ type utxoExtend struct {
 	Runes []runeBalance `json:"runes"`
 }

-type utxo struct {
+type utxoItem struct {
 	TxHash      chainhash.Hash `json:"txHash"`
 	OutputIndex uint32         `json:"outputIndex"`
 	Extend      utxoExtend     `json:"extend"`
 }

-type getUTXOsByAddressResult struct {
-	List        []utxo `json:"list"`
-	BlockHeight uint64 `json:"blockHeight"`
+type getUTXOsResult struct {
+	List        []utxoItem `json:"list"`
+	BlockHeight uint64     `json:"blockHeight"`
 }

-type getUTXOsByAddressResponse = HttpResponse[getUTXOsByAddressResult]
+type getUTXOsResponse = HttpResponse[getUTXOsResult]

-func (h *HttpHandler) GetUTXOsByAddress(ctx *fiber.Ctx) (err error) {
-	var req getUTXOsByAddressRequest
+func (h *HttpHandler) GetUTXOs(ctx *fiber.Ctx) (err error) {
+	var req getUTXOsRequest
 	if err := ctx.ParamsParser(&req); err != nil {
 		return errors.WithStack(err)
 	}
@@ -71,36 +83,60 @@ func (h *HttpHandler) GetUTXOsByAddress(ctx *fiber.Ctx) (err error) {
 		return errs.NewPublicError("unable to resolve pkscript from \"wallet\"")
 	}

+	if req.Limit == 0 {
+		req.Limit = getUTXOsDefaultLimit
+	}
+
 	blockHeight := req.BlockHeight
 	if blockHeight == 0 {
 		blockHeader, err := h.usecase.GetLatestBlock(ctx.UserContext())
 		if err != nil {
+			if errors.Is(err, errs.NotFound) {
+				return errs.NewPublicError("latest block not found")
+			}
 			return errors.Wrap(err, "error during GetLatestBlock")
 		}
 		blockHeight = uint64(blockHeader.Height)
 	}

-	outPointBalances, err := h.usecase.GetUnspentOutPointBalancesByPkScript(ctx.UserContext(), pkScript, blockHeight)
-	if err != nil {
-		return errors.Wrap(err, "error during GetBalancesByPkScript")
+	var utxos []*entity.RunesUTXO
+	if runeId, ok := h.resolveRuneId(ctx.UserContext(), req.Id); ok {
+		utxos, err = h.usecase.GetRunesUTXOsByRuneIdAndPkScript(ctx.UserContext(), runeId, pkScript, blockHeight, req.Limit, req.Offset)
+		if err != nil {
+			if errors.Is(err, errs.NotFound) {
+				return errs.NewPublicError("utxos not found")
+			}
+			return errors.Wrap(err, "error during GetBalancesByPkScript")
+		}
+	} else {
+		utxos, err = h.usecase.GetRunesUTXOsByPkScript(ctx.UserContext(), pkScript, blockHeight, req.Limit, req.Offset)
+		if err != nil {
+			if errors.Is(err, errs.NotFound) {
+				return errs.NewPublicError("utxos not found")
+			}
+			return errors.Wrap(err, "error during GetBalancesByPkScript")
+		}
 	}

-	outPointBalanceRuneIds := lo.Map(outPointBalances, func(outPointBalance *entity.OutPointBalance, _ int) runes.RuneId {
-		return outPointBalance.RuneId
-	})
-	runeEntries, err := h.usecase.GetRuneEntryByRuneIdBatch(ctx.UserContext(), outPointBalanceRuneIds)
+	runeIds := make(map[runes.RuneId]struct{}, 0)
+	for _, utxo := range utxos {
+		for _, balance := range utxo.RuneBalances {
+			runeIds[balance.RuneId] = struct{}{}
+		}
+	}
+	runeIdsList := lo.Keys(runeIds)
+	runeEntries, err := h.usecase.GetRuneEntryByRuneIdBatch(ctx.UserContext(), runeIdsList)
 	if err != nil {
+		if errors.Is(err, errs.NotFound) {
+			return errs.NewPublicError("rune entries not found")
+		}
 		return errors.Wrap(err, "error during GetRuneEntryByRuneIdBatch")
 	}

-	groupedBalances := lo.GroupBy(outPointBalances, func(outPointBalance *entity.OutPointBalance) wire.OutPoint {
-		return outPointBalance.OutPoint
-	})
-
-	utxoList := make([]utxo, 0, len(groupedBalances))
-	for outPoint, balances := range groupedBalances {
-		runeBalances := make([]runeBalance, 0, len(balances))
-		for _, balance := range balances {
+	utxoRespList := make([]utxoItem, 0, len(utxos))
+	for _, utxo := range utxos {
+		runeBalances := make([]runeBalance, 0, len(utxo.RuneBalances))
+		for _, balance := range utxo.RuneBalances {
 			runeEntry := runeEntries[balance.RuneId]
 			runeBalances = append(runeBalances, runeBalance{
 				RuneId:       balance.RuneId,
@@ -111,34 +147,19 @@ func (h *HttpHandler) GetUTXOsByAddress(ctx *fiber.Ctx) (err error) {
 			})
 		}

-		utxoList = append(utxoList, utxo{
-			TxHash:      outPoint.Hash,
-			OutputIndex: outPoint.Index,
+		utxoRespList = append(utxoRespList, utxoItem{
+			TxHash:      utxo.OutPoint.Hash,
+			OutputIndex: utxo.OutPoint.Index,
 			Extend: utxoExtend{
 				Runes: runeBalances,
 			},
 		})
 	}

-	// filter by req.Id if exists
-	{
-		runeId, ok := h.resolveRuneId(ctx.UserContext(), req.Id)
-		if ok {
-			utxoList = lo.Filter(utxoList, func(u utxo, _ int) bool {
-				for _, runeBalance := range u.Extend.Runes {
-					if runeBalance.RuneId == runeId {
-						return true
-					}
-				}
-				return false
-			})
-		}
-	}
-
-	resp := getUTXOsByAddressResponse{
-		Result: &getUTXOsByAddressResult{
+	resp := getUTXOsResponse{
+		Result: &getUTXOsResult{
 			BlockHeight: blockHeight,
-			List:        utxoList,
+			List:        utxoRespList,
 		},
 	}

--- a/modules/runes/api/httphandler/routes.go
+++ b/modules/runes/api/httphandler/routes.go
@@ -7,12 +7,12 @@ import (
 func (h *HttpHandler) Mount(router fiber.Router) error {
 	r := router.Group("/v2/runes")

-	r.Post("/balances/wallet/batch", h.GetBalancesByAddressBatch)
-	r.Get("/balances/wallet/:wallet", h.GetBalancesByAddress)
+	r.Post("/balances/wallet/batch", h.GetBalancesBatch)
+	r.Get("/balances/wallet/:wallet", h.GetBalances)
 	r.Get("/transactions", h.GetTransactions)
 	r.Get("/holders/:id", h.GetHolders)
 	r.Get("/info/:id", h.GetTokenInfo)
-	r.Get("/utxos/wallet/:wallet", h.GetUTXOsByAddress)
+	r.Get("/utxos/wallet/:wallet", h.GetUTXOs)
 	r.Get("/block", h.GetCurrentBlock)
 	return nil
 }
--- a/modules/runes/database/postgresql/migrations/000001_initialize_tables.up.sql
+++ b/modules/runes/database/postgresql/migrations/000001_initialize_tables.up.sql
@@ -118,5 +118,7 @@ CREATE TABLE IF NOT EXISTS "runes_balances" (
 	"amount" DECIMAL NOT NULL,
 	PRIMARY KEY ("pkscript", "rune_id", "block_height")
 );
+CREATE INDEX IF NOT EXISTS runes_balances_rune_id_block_height_idx ON "runes_balances" USING BTREE ("rune_id", "block_height");
+CREATE INDEX IF NOT EXISTS runes_balances_pkscript_block_height_idx ON "runes_balances" USING BTREE ("pkscript", "block_height");

 COMMIT;
--- a/modules/runes/database/postgresql/queries/data.sql
+++ b/modules/runes/database/postgresql/queries/data.sql
@@ -2,13 +2,13 @@
 WITH balances AS (
  SELECT DISTINCT ON (rune_id) * FROM runes_balances WHERE pkscript = $1 AND block_height <= $2 ORDER BY rune_id, block_height DESC
 )
-SELECT * FROM balances WHERE amount > 0;
+SELECT * FROM balances WHERE amount > 0 ORDER BY amount DESC, rune_id LIMIT $3 OFFSET $4;

 -- name: GetBalancesByRuneId :many
 WITH balances AS (
  SELECT DISTINCT ON (pkscript) * FROM runes_balances WHERE rune_id = $1 AND block_height <= $2 ORDER BY pkscript, block_height DESC
 )
-SELECT * FROM balances WHERE amount > 0;
+SELECT * FROM balances WHERE amount > 0 ORDER BY amount DESC, pkscript LIMIT $3 OFFSET $4;

 -- name: GetBalanceByPkScriptAndRuneId :one
 SELECT * FROM runes_balances WHERE pkscript = $1 AND rune_id = $2 AND block_height <= $3 ORDER BY block_height DESC LIMIT 1;
@@ -16,8 +16,28 @@ SELECT * FROM runes_balances WHERE pkscript = $1 AND rune_id = $2 AND block_heig
 -- name: GetOutPointBalancesAtOutPoint :many
 SELECT * FROM runes_outpoint_balances WHERE tx_hash = $1 AND tx_idx = $2;

-- name: GetUnspentOutPointBalancesByPkScript :many
-SELECT * FROM runes_outpoint_balances WHERE pkscript = @pkScript AND block_height <= @block_height AND (spent_height IS NULL OR spent_height > @block_height);
+-- name: GetRunesUTXOsByPkScript :many
+SELECT tx_hash, tx_idx, max("pkscript") as pkscript, array_agg("rune_id") as rune_ids, array_agg("amount") as amounts 
+  FROM runes_outpoint_balances 
+  WHERE
+    pkscript = @pkScript AND
+    block_height <= @block_height AND
+    (spent_height IS NULL OR spent_height > @block_height)
+  GROUP BY tx_hash, tx_idx
+  ORDER BY tx_hash, tx_idx 
+  LIMIT $1 OFFSET $2;
+
+-- name: GetRunesUTXOsByRuneIdAndPkScript :many
+SELECT tx_hash, tx_idx, max("pkscript") as pkscript, array_agg("rune_id") as rune_ids, array_agg("amount") as amounts 
+  FROM runes_outpoint_balances 
+  WHERE
+    pkscript = @pkScript AND 
+    block_height <= @block_height AND 
+    (spent_height IS NULL OR spent_height > @block_height)
+  GROUP BY tx_hash, tx_idx
+  HAVING array_agg("rune_id") @> @rune_ids::text[] 
+  ORDER BY tx_hash, tx_idx 
+  LIMIT $1 OFFSET $2;

 -- name: GetRuneEntriesByRuneIds :many
 WITH states AS (
@@ -55,8 +75,9 @@ SELECT * FROM runes_transactions
    OR runes_transactions.burns ? @rune_id
    OR (runes_transactions.rune_etched = TRUE AND runes_transactions.block_height = @rune_id_block_height AND runes_transactions.index = @rune_id_tx_index)
  ) AND (
-    @block_height::INT = 0 OR runes_transactions.block_height = @block_height::INT -- if @block_height > 0, apply block_height filter
-  );
+    @from_block <= runes_transactions.block_height AND runes_transactions.block_height <= @to_block
+  )
+ORDER BY runes_transactions.block_height DESC, runes_transactions.index DESC LIMIT $1 OFFSET $2;

 -- name: CountRuneEntries :one
 SELECT COUNT(*) FROM runes_entries;
--- a/modules/runes/datagateway/runes.go
+++ b/modules/runes/datagateway/runes.go
@@ -27,10 +27,11 @@ type RunesReaderDataGateway interface {
 	GetLatestBlock(ctx context.Context) (types.BlockHeader, error)
 	GetIndexedBlockByHeight(ctx context.Context, height int64) (*entity.IndexedBlock, error)
 	// GetRuneTransactions returns the runes transactions, filterable by pkScript, runeId and height. If pkScript, runeId or height is zero value, that filter is ignored.
-	GetRuneTransactions(ctx context.Context, pkScript []byte, runeId runes.RuneId, height uint64) ([]*entity.RuneTransaction, error)
+	GetRuneTransactions(ctx context.Context, pkScript []byte, runeId runes.RuneId, fromBlock, toBlock uint64, limit int32, offset int32) ([]*entity.RuneTransaction, error)

 	GetRunesBalancesAtOutPoint(ctx context.Context, outPoint wire.OutPoint) (map[runes.RuneId]*entity.OutPointBalance, error)
-	GetUnspentOutPointBalancesByPkScript(ctx context.Context, pkScript []byte, blockHeight uint64) ([]*entity.OutPointBalance, error)
+	GetRunesUTXOsByRuneIdAndPkScript(ctx context.Context, runeId runes.RuneId, pkScript []byte, blockHeight uint64, limit int32, offset int32) ([]*entity.RunesUTXO, error)
+	GetRunesUTXOsByPkScript(ctx context.Context, pkScript []byte, blockHeight uint64, limit int32, offset int32) ([]*entity.RunesUTXO, error)
 	// GetRuneIdFromRune returns the RuneId for the given rune. Returns errs.NotFound if the rune entry is not found.
 	GetRuneIdFromRune(ctx context.Context, rune runes.Rune) (runes.RuneId, error)
 	// GetRuneEntryByRuneId returns the RuneEntry for the given runeId. Returns errs.NotFound if the rune entry is not found.
@@ -45,10 +46,12 @@ type RunesReaderDataGateway interface {
 	CountRuneEntries(ctx context.Context) (uint64, error)

 	// GetBalancesByPkScript returns the balances for the given pkScript at the given blockHeight.
-	GetBalancesByPkScript(ctx context.Context, pkScript []byte, blockHeight uint64) (map[runes.RuneId]*entity.Balance, error)
+	// Use limit = -1 as no limit.
+	GetBalancesByPkScript(ctx context.Context, pkScript []byte, blockHeight uint64, limit int32, offset int32) ([]*entity.Balance, error)
 	// GetBalancesByRuneId returns the balances for the given runeId at the given blockHeight.
 	// Cannot use []byte as map key, so we're returning as slice.
-	GetBalancesByRuneId(ctx context.Context, runeId runes.RuneId, blockHeight uint64) ([]*entity.Balance, error)
+	// Use limit = -1 as no limit.
+	GetBalancesByRuneId(ctx context.Context, runeId runes.RuneId, blockHeight uint64, limit int32, offset int32) ([]*entity.Balance, error)
 	// GetBalancesByPkScriptAndRuneId returns the balance for the given pkScript and runeId at the given blockHeight.
 	GetBalanceByPkScriptAndRuneId(ctx context.Context, pkScript []byte, runeId runes.RuneId, blockHeight uint64) (*entity.Balance, error)
 }
--- a/modules/runes/internal/entity/runes_utxo.go
+++ b/modules/runes/internal/entity/runes_utxo.go
@@ -0,0 +1,18 @@
+package entity
+
+import (
+	"github.com/btcsuite/btcd/wire"
+	"github.com/gaze-network/indexer-network/modules/runes/runes"
+	"github.com/gaze-network/uint128"
+)
+
+type RunesUTXOBalance struct {
+	RuneId runes.RuneId
+	Amount uint128.Uint128
+}
+
+type RunesUTXO struct {
+	PkScript     []byte
+	OutPoint     wire.OutPoint
+	RuneBalances []RunesUTXOBalance
+}
--- a/modules/runes/processor_process.go
+++ b/modules/runes/processor_process.go
@@ -146,7 +146,7 @@ func (p *Processor) processTx(ctx context.Context, tx *types.Transaction, blockH
 					// find all non-OP_RETURN outputs
 					var destinations []int
 					for i, txOut := range tx.TxOut {
-						if txOut.IsOpReturn() {
+						if !txOut.IsOpReturn() {
 							destinations = append(destinations, i)
 						}
 					}
@@ -466,7 +466,7 @@ func (p *Processor) txCommitsToRune(ctx context.Context, tx *types.Transaction,
 			// It is impossible to verify that input utxo is a P2TR output with just the input.
 			// Need to verify with utxo's pk script.

-			prevTx, err := p.bitcoinClient.GetTransactionByHash(ctx, txIn.PreviousOutTxHash)
+			prevTx, blockHeight, err := p.bitcoinClient.GetRawTransactionAndHeightByTxHash(ctx, txIn.PreviousOutTxHash)
 			if err != nil && errors.Is(err, errs.NotFound) {
 				continue
 			}
@@ -479,7 +479,7 @@ func (p *Processor) txCommitsToRune(ctx context.Context, tx *types.Transaction,
 				break
 			}
 			// input must be mature enough
-			confirmations := tx.BlockHeight - prevTx.BlockHeight + 1
+			confirmations := tx.BlockHeight - blockHeight + 1
 			if confirmations < runes.RUNE_COMMIT_BLOCKS {
 				continue
 			}
--- a/modules/runes/repository/postgres/gen/data.sql.go
+++ b/modules/runes/repository/postgres/gen/data.sql.go
@@ -296,12 +296,14 @@ const getBalancesByPkScript = `-- name: GetBalancesByPkScript :many
 WITH balances AS (
  SELECT DISTINCT ON (rune_id) pkscript, block_height, rune_id, amount FROM runes_balances WHERE pkscript = $1 AND block_height <= $2 ORDER BY rune_id, block_height DESC
 )
-SELECT pkscript, block_height, rune_id, amount FROM balances WHERE amount > 0
+SELECT pkscript, block_height, rune_id, amount FROM balances WHERE amount > 0 ORDER BY amount DESC, rune_id LIMIT $3 OFFSET $4
 `

 type GetBalancesByPkScriptParams struct {
 	Pkscript    string
 	BlockHeight int32
+	Limit       int32
+	Offset      int32
 }

 type GetBalancesByPkScriptRow struct {
@@ -312,7 +314,12 @@ type GetBalancesByPkScriptRow struct {
 }

 func (q *Queries) GetBalancesByPkScript(ctx context.Context, arg GetBalancesByPkScriptParams) ([]GetBalancesByPkScriptRow, error) {
-	rows, err := q.db.Query(ctx, getBalancesByPkScript, arg.Pkscript, arg.BlockHeight)
+	rows, err := q.db.Query(ctx, getBalancesByPkScript,
+		arg.Pkscript,
+		arg.BlockHeight,
+		arg.Limit,
+		arg.Offset,
+	)
 	if err != nil {
 		return nil, err
 	}
@@ -340,12 +347,14 @@ const getBalancesByRuneId = `-- name: GetBalancesByRuneId :many
 WITH balances AS (
  SELECT DISTINCT ON (pkscript) pkscript, block_height, rune_id, amount FROM runes_balances WHERE rune_id = $1 AND block_height <= $2 ORDER BY pkscript, block_height DESC
 )
-SELECT pkscript, block_height, rune_id, amount FROM balances WHERE amount > 0
+SELECT pkscript, block_height, rune_id, amount FROM balances WHERE amount > 0 ORDER BY amount DESC, pkscript LIMIT $3 OFFSET $4
 `

 type GetBalancesByRuneIdParams struct {
 	RuneID      string
 	BlockHeight int32
+	Limit       int32
+	Offset      int32
 }

 type GetBalancesByRuneIdRow struct {
@@ -356,7 +365,12 @@ type GetBalancesByRuneIdRow struct {
 }

 func (q *Queries) GetBalancesByRuneId(ctx context.Context, arg GetBalancesByRuneIdParams) ([]GetBalancesByRuneIdRow, error) {
-	rows, err := q.db.Query(ctx, getBalancesByRuneId, arg.RuneID, arg.BlockHeight)
+	rows, err := q.db.Query(ctx, getBalancesByRuneId,
+		arg.RuneID,
+		arg.BlockHeight,
+		arg.Limit,
+		arg.Offset,
+	)
 	if err != nil {
 		return nil, err
 	}
@@ -635,22 +649,25 @@ const getRuneTransactions = `-- name: GetRuneTransactions :many
 SELECT hash, runes_transactions.block_height, index, timestamp, inputs, outputs, mints, burns, rune_etched, tx_hash, runes_runestones.block_height, etching, etching_divisibility, etching_premine, etching_rune, etching_spacers, etching_symbol, etching_terms, etching_terms_amount, etching_terms_cap, etching_terms_height_start, etching_terms_height_end, etching_terms_offset_start, etching_terms_offset_end, etching_turbo, edicts, mint, pointer, cenotaph, flaws FROM runes_transactions
 	LEFT JOIN runes_runestones ON runes_transactions.hash = runes_runestones.tx_hash
 	WHERE (
-    $1::BOOLEAN = FALSE -- if @filter_pk_script is TRUE, apply pk_script filter
-    OR runes_transactions.outputs @> $2::JSONB 
-    OR runes_transactions.inputs @> $2::JSONB
-  ) AND (
-    $3::BOOLEAN = FALSE -- if @filter_rune_id is TRUE, apply rune_id filter
+    $3::BOOLEAN = FALSE -- if @filter_pk_script is TRUE, apply pk_script filter
    OR runes_transactions.outputs @> $4::JSONB 
-    OR runes_transactions.inputs @> $4::JSONB 
-    OR runes_transactions.mints ? $5 
-    OR runes_transactions.burns ? $5
-    OR (runes_transactions.rune_etched = TRUE AND runes_transactions.block_height = $6 AND runes_transactions.index = $7)
+    OR runes_transactions.inputs @> $4::JSONB
  ) AND (
-    $8::INT = 0 OR runes_transactions.block_height = $8::INT -- if @block_height > 0, apply block_height filter
+    $5::BOOLEAN = FALSE -- if @filter_rune_id is TRUE, apply rune_id filter
+    OR runes_transactions.outputs @> $6::JSONB 
+    OR runes_transactions.inputs @> $6::JSONB 
+    OR runes_transactions.mints ? $7 
+    OR runes_transactions.burns ? $7
+    OR (runes_transactions.rune_etched = TRUE AND runes_transactions.block_height = $8 AND runes_transactions.index = $9)
+  ) AND (
+    $10 <= runes_transactions.block_height AND runes_transactions.block_height <= $11
  )
+ORDER BY runes_transactions.block_height DESC, runes_transactions.index DESC LIMIT $1 OFFSET $2
 `

 type GetRuneTransactionsParams struct {
+	Limit             int32
+	Offset            int32
 	FilterPkScript    bool
 	PkScriptParam     []byte
 	FilterRuneID      bool
@@ -658,7 +675,8 @@ type GetRuneTransactionsParams struct {
 	RuneID            []byte
 	RuneIDBlockHeight int32
 	RuneIDTxIndex     int32
-	BlockHeight       int32
+	FromBlock         int32
+	ToBlock           int32
 }

 type GetRuneTransactionsRow struct {
@@ -696,6 +714,8 @@ type GetRuneTransactionsRow struct {

 func (q *Queries) GetRuneTransactions(ctx context.Context, arg GetRuneTransactionsParams) ([]GetRuneTransactionsRow, error) {
 	rows, err := q.db.Query(ctx, getRuneTransactions,
+		arg.Limit,
+		arg.Offset,
 		arg.FilterPkScript,
 		arg.PkScriptParam,
 		arg.FilterRuneID,
@@ -703,7 +723,8 @@ func (q *Queries) GetRuneTransactions(ctx context.Context, arg GetRuneTransactio
 		arg.RuneID,
 		arg.RuneIDBlockHeight,
 		arg.RuneIDTxIndex,
-		arg.BlockHeight,
+		arg.FromBlock,
+		arg.ToBlock,
 	)
 	if err != nil {
 		return nil, err
@@ -754,32 +775,114 @@ func (q *Queries) GetRuneTransactions(ctx context.Context, arg GetRuneTransactio
 	return items, nil
 }

-const getUnspentOutPointBalancesByPkScript = `-- name: GetUnspentOutPointBalancesByPkScript :many
-SELECT rune_id, pkscript, tx_hash, tx_idx, amount, block_height, spent_height FROM runes_outpoint_balances WHERE pkscript = $1 AND block_height <= $2 AND (spent_height IS NULL OR spent_height > $2)
+const getRunesUTXOsByPkScript = `-- name: GetRunesUTXOsByPkScript :many
+SELECT tx_hash, tx_idx, max("pkscript") as pkscript, array_agg("rune_id") as rune_ids, array_agg("amount") as amounts 
+  FROM runes_outpoint_balances 
+  WHERE
+    pkscript = $3 AND
+    block_height <= $4 AND
+    (spent_height IS NULL OR spent_height > $4)
+  GROUP BY tx_hash, tx_idx
+  ORDER BY tx_hash, tx_idx 
+  LIMIT $1 OFFSET $2
 `

-type GetUnspentOutPointBalancesByPkScriptParams struct {
+type GetRunesUTXOsByPkScriptParams struct {
+	Limit       int32
+	Offset      int32
 	Pkscript    string
 	BlockHeight int32
 }

-func (q *Queries) GetUnspentOutPointBalancesByPkScript(ctx context.Context, arg GetUnspentOutPointBalancesByPkScriptParams) ([]RunesOutpointBalance, error) {
-	rows, err := q.db.Query(ctx, getUnspentOutPointBalancesByPkScript, arg.Pkscript, arg.BlockHeight)
+type GetRunesUTXOsByPkScriptRow struct {
+	TxHash   string
+	TxIdx    int32
+	Pkscript interface{}
+	RuneIds  interface{}
+	Amounts  interface{}
+}
+
+func (q *Queries) GetRunesUTXOsByPkScript(ctx context.Context, arg GetRunesUTXOsByPkScriptParams) ([]GetRunesUTXOsByPkScriptRow, error) {
+	rows, err := q.db.Query(ctx, getRunesUTXOsByPkScript,
+		arg.Limit,
+		arg.Offset,
+		arg.Pkscript,
+		arg.BlockHeight,
+	)
 	if err != nil {
 		return nil, err
 	}
 	defer rows.Close()
-	var items []RunesOutpointBalance
+	var items []GetRunesUTXOsByPkScriptRow
 	for rows.Next() {
-		var i RunesOutpointBalance
+		var i GetRunesUTXOsByPkScriptRow
 		if err := rows.Scan(
-			&i.RuneID,
-			&i.Pkscript,
 			&i.TxHash,
 			&i.TxIdx,
-			&i.Amount,
-			&i.BlockHeight,
-			&i.SpentHeight,
+			&i.Pkscript,
+			&i.RuneIds,
+			&i.Amounts,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const getRunesUTXOsByRuneIdAndPkScript = `-- name: GetRunesUTXOsByRuneIdAndPkScript :many
+SELECT tx_hash, tx_idx, max("pkscript") as pkscript, array_agg("rune_id") as rune_ids, array_agg("amount") as amounts 
+  FROM runes_outpoint_balances 
+  WHERE
+    pkscript = $3 AND 
+    block_height <= $4 AND 
+    (spent_height IS NULL OR spent_height > $4)
+  GROUP BY tx_hash, tx_idx
+  HAVING array_agg("rune_id") @> $5::text[] 
+  ORDER BY tx_hash, tx_idx 
+  LIMIT $1 OFFSET $2
+`
+
+type GetRunesUTXOsByRuneIdAndPkScriptParams struct {
+	Limit       int32
+	Offset      int32
+	Pkscript    string
+	BlockHeight int32
+	RuneIds     []string
+}
+
+type GetRunesUTXOsByRuneIdAndPkScriptRow struct {
+	TxHash   string
+	TxIdx    int32
+	Pkscript interface{}
+	RuneIds  interface{}
+	Amounts  interface{}
+}
+
+func (q *Queries) GetRunesUTXOsByRuneIdAndPkScript(ctx context.Context, arg GetRunesUTXOsByRuneIdAndPkScriptParams) ([]GetRunesUTXOsByRuneIdAndPkScriptRow, error) {
+	rows, err := q.db.Query(ctx, getRunesUTXOsByRuneIdAndPkScript,
+		arg.Limit,
+		arg.Offset,
+		arg.Pkscript,
+		arg.BlockHeight,
+		arg.RuneIds,
+	)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []GetRunesUTXOsByRuneIdAndPkScriptRow
+	for rows.Next() {
+		var i GetRunesUTXOsByRuneIdAndPkScriptRow
+		if err := rows.Scan(
+			&i.TxHash,
+			&i.TxIdx,
+			&i.Pkscript,
+			&i.RuneIds,
+			&i.Amounts,
 		); err != nil {
 			return nil, err
 		}
--- a/modules/runes/repository/postgres/mapper.go
+++ b/modules/runes/repository/postgres/mapper.go
@@ -638,6 +638,72 @@ func mapIndexedBlockTypeToParams(src entity.IndexedBlock) (gen.CreateIndexedBloc
 	}, nil
 }

+func mapRunesUTXOModelToType(src gen.GetRunesUTXOsByPkScriptRow) (entity.RunesUTXO, error) {
+	pkScriptRaw, ok := src.Pkscript.(string)
+	if !ok {
+		return entity.RunesUTXO{}, errors.New("pkscript from database is not string")
+	}
+	pkScript, err := hex.DecodeString(pkScriptRaw)
+	if err != nil {
+		return entity.RunesUTXO{}, errors.Wrap(err, "failed to parse pkscript")
+	}
+	txHash, err := chainhash.NewHashFromStr(src.TxHash)
+	if err != nil {
+		return entity.RunesUTXO{}, errors.Wrap(err, "failed to parse tx hash")
+	}
+	runeIdsRaw, ok := src.RuneIds.([]interface{})
+	if !ok {
+		return entity.RunesUTXO{}, errors.New("src.RuneIds is not a slice")
+	}
+	runeIds := make([]string, 0, len(runeIdsRaw))
+	for i, raw := range runeIdsRaw {
+		runeId, ok := raw.(string)
+		if !ok {
+			return entity.RunesUTXO{}, errors.Errorf("src.RuneIds[%d] is not a string", i)
+		}
+		runeIds = append(runeIds, runeId)
+	}
+	amountsRaw, ok := src.Amounts.([]interface{})
+	if !ok {
+		return entity.RunesUTXO{}, errors.New("amounts from database is not a slice")
+	}
+	amounts := make([]pgtype.Numeric, 0, len(amountsRaw))
+	for i, raw := range amountsRaw {
+		amount, ok := raw.(pgtype.Numeric)
+		if !ok {
+			return entity.RunesUTXO{}, errors.Errorf("src.Amounts[%d] is not pgtype.Numeric", i)
+		}
+		amounts = append(amounts, amount)
+	}
+	if len(runeIds) != len(amounts) {
+		return entity.RunesUTXO{}, errors.New("rune ids and amounts have different lengths")
+	}
+
+	runesBalances := make([]entity.RunesUTXOBalance, 0, len(runeIds))
+	for i := range runeIds {
+		runeId, err := runes.NewRuneIdFromString(runeIds[i])
+		if err != nil {
+			return entity.RunesUTXO{}, errors.Wrap(err, "failed to parse rune id")
+		}
+		amount, err := uint128FromNumeric(amounts[i])
+		if err != nil {
+			return entity.RunesUTXO{}, errors.Wrap(err, "failed to parse amount")
+		}
+		runesBalances = append(runesBalances, entity.RunesUTXOBalance{
+			RuneId: runeId,
+			Amount: lo.FromPtr(amount),
+		})
+	}
+	return entity.RunesUTXO{
+		PkScript: pkScript,
+		OutPoint: wire.OutPoint{
+			Hash:  *txHash,
+			Index: uint32(src.TxIdx),
+		},
+		RuneBalances: runesBalances,
+	}, nil
+}
+
 func mapOutPointBalanceModelToType(src gen.RunesOutpointBalance) (entity.OutPointBalance, error) {
 	runeId, err := runes.NewRuneIdFromString(src.RuneID)
 	if err != nil {
--- a/modules/runes/repository/postgres/runes.go
+++ b/modules/runes/repository/postgres/runes.go
@@ -4,6 +4,7 @@ import (
 	"context"
 	"encoding/hex"
 	"fmt"
+	"math"

 	"github.com/btcsuite/btcd/chaincfg/chainhash"
 	"github.com/btcsuite/btcd/wire"
@@ -62,7 +63,18 @@ func (r *Repository) GetIndexedBlockByHeight(ctx context.Context, height int64)
 	return indexedBlock, nil
 }

-func (r *Repository) GetRuneTransactions(ctx context.Context, pkScript []byte, runeId runes.RuneId, height uint64) ([]*entity.RuneTransaction, error) {
+const maxRuneTransactionsLimit = 10000 // temporary limit to prevent large queries from overwhelming the database
+
+func (r *Repository) GetRuneTransactions(ctx context.Context, pkScript []byte, runeId runes.RuneId, fromBlock, toBlock uint64, limit int32, offset int32) ([]*entity.RuneTransaction, error) {
+	if limit == -1 {
+		limit = maxRuneTransactionsLimit
+	}
+	if limit < 0 {
+		return nil, errors.Wrap(errs.InvalidArgument, "limit must be -1 or non-negative")
+	}
+	if limit > maxRuneTransactionsLimit {
+		return nil, errors.Wrapf(errs.InvalidArgument, "limit cannot exceed %d", maxRuneTransactionsLimit)
+	}
 	pkScriptParam := []byte(fmt.Sprintf(`[{"pkScript":"%s"}]`, hex.EncodeToString(pkScript)))
 	runeIdParam := []byte(fmt.Sprintf(`[{"runeId":"%s"}]`, runeId.String()))
 	rows, err := r.queries.GetRuneTransactions(ctx, gen.GetRuneTransactionsParams{
@@ -75,7 +87,11 @@ func (r *Repository) GetRuneTransactions(ctx context.Context, pkScript []byte, r
 		RuneIDBlockHeight: int32(runeId.BlockHeight),
 		RuneIDTxIndex:     int32(runeId.TxIndex),

-		BlockHeight: int32(height),
+		FromBlock: int32(fromBlock),
+		ToBlock:   int32(toBlock),
+
+		Limit:  limit,
+		Offset: offset,
 	})
 	if err != nil {
 		return nil, errors.Wrap(err, "error during query")
@@ -124,22 +140,59 @@ func (r *Repository) GetRunesBalancesAtOutPoint(ctx context.Context, outPoint wi
 	return result, nil
 }

-func (r *Repository) GetUnspentOutPointBalancesByPkScript(ctx context.Context, pkScript []byte, blockHeight uint64) ([]*entity.OutPointBalance, error) {
-	balances, err := r.queries.GetUnspentOutPointBalancesByPkScript(ctx, gen.GetUnspentOutPointBalancesByPkScriptParams{
+func (r *Repository) GetRunesUTXOsByPkScript(ctx context.Context, pkScript []byte, blockHeight uint64, limit int32, offset int32) ([]*entity.RunesUTXO, error) {
+	if limit == -1 {
+		limit = math.MaxInt32
+	}
+	if limit < 0 {
+		return nil, errors.Wrap(errs.InvalidArgument, "limit must be -1 or non-negative")
+	}
+	rows, err := r.queries.GetRunesUTXOsByPkScript(ctx, gen.GetRunesUTXOsByPkScriptParams{
 		Pkscript:    hex.EncodeToString(pkScript),
 		BlockHeight: int32(blockHeight),
+		Limit:       limit,
+		Offset:      offset,
 	})
 	if err != nil {
 		return nil, errors.Wrap(err, "error during query")
 	}

-	result := make([]*entity.OutPointBalance, 0, len(balances))
-	for _, balanceModel := range balances {
-		balance, err := mapOutPointBalanceModelToType(balanceModel)
+	result := make([]*entity.RunesUTXO, 0, len(rows))
+	for _, row := range rows {
+		utxo, err := mapRunesUTXOModelToType(row)
 		if err != nil {
-			return nil, errors.Wrap(err, "failed to parse balance model")
+			return nil, errors.Wrap(err, "failed to parse row model")
 		}
-		result = append(result, &balance)
+		result = append(result, &utxo)
+	}
+	return result, nil
+}
+
+func (r *Repository) GetRunesUTXOsByRuneIdAndPkScript(ctx context.Context, runeId runes.RuneId, pkScript []byte, blockHeight uint64, limit int32, offset int32) ([]*entity.RunesUTXO, error) {
+	if limit == -1 {
+		limit = math.MaxInt32
+	}
+	if limit < 0 {
+		return nil, errors.Wrap(errs.InvalidArgument, "limit must be -1 or non-negative")
+	}
+	rows, err := r.queries.GetRunesUTXOsByRuneIdAndPkScript(ctx, gen.GetRunesUTXOsByRuneIdAndPkScriptParams{
+		Pkscript:    hex.EncodeToString(pkScript),
+		BlockHeight: int32(blockHeight),
+		RuneIds:     []string{runeId.String()},
+		Limit:       limit,
+		Offset:      offset,
+	})
+	if err != nil {
+		return nil, errors.Wrap(err, "error during query")
+	}
+
+	result := make([]*entity.RunesUTXO, 0, len(rows))
+	for _, row := range rows {
+		utxo, err := mapRunesUTXOModelToType(gen.GetRunesUTXOsByPkScriptRow(row))
+		if err != nil {
+			return nil, errors.Wrap(err, "failed to parse row")
+		}
+		result = append(result, &utxo)
 	}
 	return result, nil
 }
@@ -244,30 +297,46 @@ func (r *Repository) CountRuneEntries(ctx context.Context) (uint64, error) {
 	return uint64(count), nil
 }

-func (r *Repository) GetBalancesByPkScript(ctx context.Context, pkScript []byte, blockHeight uint64) (map[runes.RuneId]*entity.Balance, error) {
+func (r *Repository) GetBalancesByPkScript(ctx context.Context, pkScript []byte, blockHeight uint64, limit int32, offset int32) ([]*entity.Balance, error) {
+	if limit == -1 {
+		limit = math.MaxInt32
+	}
+	if limit < 0 {
+		return nil, errors.Wrap(errs.InvalidArgument, "limit must be -1 or non-negative")
+	}
 	balances, err := r.queries.GetBalancesByPkScript(ctx, gen.GetBalancesByPkScriptParams{
 		Pkscript:    hex.EncodeToString(pkScript),
 		BlockHeight: int32(blockHeight),
+		Limit:       limit,
+		Offset:      offset,
 	})
 	if err != nil {
 		return nil, errors.Wrap(err, "error during query")
 	}

-	result := make(map[runes.RuneId]*entity.Balance, len(balances))
+	result := make([]*entity.Balance, 0, len(balances))
 	for _, balanceModel := range balances {
 		balance, err := mapBalanceModelToType(gen.RunesBalance(balanceModel))
 		if err != nil {
 			return nil, errors.Wrap(err, "failed to parse balance model")
 		}
-		result[balance.RuneId] = balance
+		result = append(result, balance)
 	}
 	return result, nil
 }

-func (r *Repository) GetBalancesByRuneId(ctx context.Context, runeId runes.RuneId, blockHeight uint64) ([]*entity.Balance, error) {
+func (r *Repository) GetBalancesByRuneId(ctx context.Context, runeId runes.RuneId, blockHeight uint64, limit int32, offset int32) ([]*entity.Balance, error) {
+	if limit == -1 {
+		limit = math.MaxInt32
+	}
+	if limit < 0 {
+		return nil, errors.Wrap(errs.InvalidArgument, "limit must be -1 or non-negative")
+	}
 	balances, err := r.queries.GetBalancesByRuneId(ctx, gen.GetBalancesByRuneIdParams{
 		RuneID:      runeId.String(),
 		BlockHeight: int32(blockHeight),
+		Limit:       limit,
+		Offset:      offset,
 	})
 	if err != nil {
 		return nil, errors.Wrap(err, "error during query")
--- a/modules/runes/runes/rune.go
+++ b/modules/runes/runes/rune.go
@@ -29,6 +29,10 @@ var ErrInvalidBase26 = errors.New("invalid base-26 character: must be in the ran
 func NewRuneFromString(value string) (Rune, error) {
 	n := uint128.From64(0)
 	for i, char := range value {
+		// skip spacers
+		if char == '.' || char == '•' {
+			continue
+		}
 		if i > 0 {
 			n = n.Add(uint128.From64(1))
 		}
--- a/modules/runes/usecase/get_balances.go
+++ b/modules/runes/usecase/get_balances.go
@@ -8,16 +8,18 @@ import (
 	"github.com/gaze-network/indexer-network/modules/runes/runes"
 )

-func (u *Usecase) GetBalancesByPkScript(ctx context.Context, pkScript []byte, blockHeight uint64) (map[runes.RuneId]*entity.Balance, error) {
-	balances, err := u.runesDg.GetBalancesByPkScript(ctx, pkScript, blockHeight)
+// Use limit = -1 as no limit.
+func (u *Usecase) GetBalancesByPkScript(ctx context.Context, pkScript []byte, blockHeight uint64, limit int32, offset int32) ([]*entity.Balance, error) {
+	balances, err := u.runesDg.GetBalancesByPkScript(ctx, pkScript, blockHeight, limit, offset)
 	if err != nil {
 		return nil, errors.Wrap(err, "error during GetBalancesByPkScript")
 	}
 	return balances, nil
 }

-func (u *Usecase) GetBalancesByRuneId(ctx context.Context, runeId runes.RuneId, blockHeight uint64) ([]*entity.Balance, error) {
-	balances, err := u.runesDg.GetBalancesByRuneId(ctx, runeId, blockHeight)
+// Use limit = -1 as no limit.
+func (u *Usecase) GetBalancesByRuneId(ctx context.Context, runeId runes.RuneId, blockHeight uint64, limit int32, offset int32) ([]*entity.Balance, error) {
+	balances, err := u.runesDg.GetBalancesByRuneId(ctx, runeId, blockHeight, limit, offset)
 	if err != nil {
 		return nil, errors.Wrap(err, "failed to get rune holders by rune id")
 	}
--- a/modules/runes/usecase/get_outpoint_balances.go
+++ b/modules/runes/usecase/get_outpoint_balances.go
@@ -1,16 +0,0 @@
-package usecase
-
-import (
-	"context"
-
-	"github.com/cockroachdb/errors"
-	"github.com/gaze-network/indexer-network/modules/runes/internal/entity"
-)
-
-func (u *Usecase) GetUnspentOutPointBalancesByPkScript(ctx context.Context, pkScript []byte, blockHeight uint64) ([]*entity.OutPointBalance, error) {
-	balances, err := u.runesDg.GetUnspentOutPointBalancesByPkScript(ctx, pkScript, blockHeight)
-	if err != nil {
-		return nil, errors.Wrap(err, "error during GetBalancesByPkScript")
-	}
-	return balances, nil
-}
--- a/modules/runes/usecase/get_transactions.go
+++ b/modules/runes/usecase/get_transactions.go
@@ -8,8 +8,9 @@ import (
 	"github.com/gaze-network/indexer-network/modules/runes/runes"
 )

-func (u *Usecase) GetRuneTransactions(ctx context.Context, pkScript []byte, runeId runes.RuneId, height uint64) ([]*entity.RuneTransaction, error) {
-	txs, err := u.runesDg.GetRuneTransactions(ctx, pkScript, runeId, height)
+// Use limit = -1 as no limit.
+func (u *Usecase) GetRuneTransactions(ctx context.Context, pkScript []byte, runeId runes.RuneId, fromBlock, toBlock uint64, limit int32, offset int32) ([]*entity.RuneTransaction, error) {
+	txs, err := u.runesDg.GetRuneTransactions(ctx, pkScript, runeId, fromBlock, toBlock, limit, offset)
 	if err != nil {
 		return nil, errors.Wrap(err, "error during GetTransactionsByHeight")
 	}
--- a/modules/runes/usecase/get_utxos.go
+++ b/modules/runes/usecase/get_utxos.go
@@ -0,0 +1,25 @@
+package usecase
+
+import (
+	"context"
+
+	"github.com/cockroachdb/errors"
+	"github.com/gaze-network/indexer-network/modules/runes/internal/entity"
+	"github.com/gaze-network/indexer-network/modules/runes/runes"
+)
+
+func (u *Usecase) GetRunesUTXOsByPkScript(ctx context.Context, pkScript []byte, blockHeight uint64, limit int32, offset int32) ([]*entity.RunesUTXO, error) {
+	balances, err := u.runesDg.GetRunesUTXOsByPkScript(ctx, pkScript, blockHeight, limit, offset)
+	if err != nil {
+		return nil, errors.Wrap(err, "error during GetBalancesByPkScript")
+	}
+	return balances, nil
+}
+
+func (u *Usecase) GetRunesUTXOsByRuneIdAndPkScript(ctx context.Context, runeId runes.RuneId, pkScript []byte, blockHeight uint64, limit int32, offset int32) ([]*entity.RunesUTXO, error) {
+	balances, err := u.runesDg.GetRunesUTXOsByRuneIdAndPkScript(ctx, runeId, pkScript, blockHeight, limit, offset)
+	if err != nil {
+		return nil, errors.Wrap(err, "error during GetBalancesByPkScript")
+	}
+	return balances, nil
+}
--- a/pkg/btcclient/contract.go
+++ b/pkg/btcclient/contract.go
@@ -4,9 +4,9 @@ import (
 	"context"

 	"github.com/btcsuite/btcd/chaincfg/chainhash"
-	"github.com/gaze-network/indexer-network/core/types"
+	"github.com/btcsuite/btcd/wire"
 )

 type Contract interface {
-	GetTransactionByHash(ctx context.Context, txHash chainhash.Hash) (*types.Transaction, error)
+	GetRawTransactionAndHeightByTxHash(ctx context.Context, txHash chainhash.Hash) (*wire.MsgTx, int64, error)
 }
--- a/pkg/btcutils/address.go
+++ b/pkg/btcutils/address.go
@@ -0,0 +1,212 @@
+package btcutils
+
+import (
+	"encoding/json"
+	"reflect"
+
+	"github.com/Cleverse/go-utilities/utils"
+	"github.com/btcsuite/btcd/btcutil"
+	"github.com/btcsuite/btcd/chaincfg"
+	"github.com/btcsuite/btcd/txscript"
+	"github.com/cockroachdb/errors"
+	"github.com/gaze-network/indexer-network/common/errs"
+	"github.com/gaze-network/indexer-network/pkg/logger"
+	"github.com/gaze-network/indexer-network/pkg/logger/slogx"
+)
+
+const (
+	// MaxSupportedPkScriptSize is the maximum supported size of a pkScript.
+	MaxSupportedPkScriptSize = 40
+)
+
+// IsAddress returns whether or not the passed string is a valid bitcoin address and valid supported type.
+//
+// NetParams is optional. If provided, we only check for that network,
+// otherwise, we check for all supported networks.
+func IsAddress(address string, defaultNet ...*chaincfg.Params) bool {
+	if len(address) == 0 {
+		return false
+	}
+
+	// If defaultNet is provided, we only check for that network.
+	net, ok := utils.Optional(defaultNet)
+	if ok {
+		_, _, err := parseAddress(address, net)
+		return err == nil
+	}
+
+	// Otherwise, we check for all supported networks.
+	for _, net := range supportedNetworks {
+		_, _, err := parseAddress(address, net)
+		if err == nil {
+			return true
+		}
+	}
+	return false
+}
+
+// TODO: create GetAddressNetwork
+// check `Bech32HRPSegwit` prefix or netID for P2SH/P2PKH is equal to `PubKeyHashAddrID/ScriptHashAddrID`
+
+// GetAddressType returns the address type of the passed address.
+func GetAddressType(address string, net *chaincfg.Params) (AddressType, error) {
+	_, addrType, err := parseAddress(address, net)
+	return addrType, errors.WithStack(err)
+}
+
+type Address struct {
+	decoded          btcutil.Address
+	net              *chaincfg.Params
+	encoded          string
+	encodedType      AddressType
+	scriptPubKey     [MaxSupportedPkScriptSize]byte
+	scriptPubKeySize int
+}
+
+// NewAddress creates a new address from the given address string.
+//
+// defaultNet is required if your address is P2SH or P2PKH (legacy or nested segwit)
+// If your address is P2WSH, P2WPKH or P2TR, defaultNet is not required.
+func NewAddress(address string, defaultNet ...*chaincfg.Params) Address {
+	addr, err := SafeNewAddress(address, defaultNet...)
+	if err != nil {
+		logger.Panic("can't create parse address", slogx.Error(err), slogx.String("package", "btcutils"))
+	}
+	return addr
+}
+
+// SafeNewAddress creates a new address from the given address string.
+// It returns an error if the address is invalid.
+//
+// defaultNet is required if your address is P2SH or P2PKH (legacy or nested segwit)
+// If your address is P2WSH, P2WPKH or P2TR, defaultNet is not required.
+func SafeNewAddress(address string, defaultNet ...*chaincfg.Params) (Address, error) {
+	net := utils.DefaultOptional(defaultNet, &chaincfg.MainNetParams)
+
+	decoded, addrType, err := parseAddress(address, net)
+	if err != nil {
+		return Address{}, errors.Wrap(err, "can't parse address")
+	}
+
+	scriptPubkey, err := txscript.PayToAddrScript(decoded)
+	if err != nil {
+		return Address{}, errors.Wrap(err, "can't get script pubkey")
+	}
+
+	fixedPkScript := [MaxSupportedPkScriptSize]byte{}
+	copy(fixedPkScript[:], scriptPubkey)
+	return Address{
+		decoded:          decoded,
+		net:              net,
+		encoded:          decoded.EncodeAddress(),
+		encodedType:      addrType,
+		scriptPubKey:     fixedPkScript,
+		scriptPubKeySize: len(scriptPubkey),
+	}, nil
+}
+
+// String returns the address string.
+func (a Address) String() string {
+	return a.encoded
+}
+
+// Type returns the address type.
+func (a Address) Type() AddressType {
+	return a.encodedType
+}
+
+// Decoded returns the btcutil.Address
+func (a Address) Decoded() btcutil.Address {
+	return a.decoded
+}
+
+// IsForNet returns whether or not the address is associated with the passed bitcoin network.
+func (a Address) IsForNet(net *chaincfg.Params) bool {
+	return a.decoded.IsForNet(net)
+}
+
+// ScriptAddress returns the raw bytes of the address to be used when inserting the address into a txout's script.
+func (a Address) ScriptAddress() []byte {
+	return a.decoded.ScriptAddress()
+}
+
+// Net returns the address network params.
+func (a Address) Net() *chaincfg.Params {
+	return a.net
+}
+
+// NetworkName
+func (a Address) NetworkName() string {
+	return a.net.Name
+}
+
+// ScriptPubKey or pubkey script
+func (a Address) ScriptPubKey() []byte {
+	return a.scriptPubKey[:a.scriptPubKeySize]
+}
+
+// Equal return true if addresses are equal
+func (a Address) Equal(b Address) bool {
+	return a.encoded == b.encoded
+}
+
+// MarshalText implements the encoding.TextMarshaler interface.
+func (a Address) MarshalText() ([]byte, error) {
+	return []byte(a.encoded), nil
+}
+
+// UnmarshalText implements the encoding.TextUnmarshaler interface.
+func (a *Address) UnmarshalText(input []byte) error {
+	address := string(input)
+	addr, err := SafeNewAddress(address)
+	if err == nil {
+		*a = addr
+		return nil
+	}
+	return errors.Wrapf(errs.InvalidArgument, "invalid address `%s`", address)
+}
+
+// MarshalJSON implements the json.Marshaler interface.
+func (a Address) MarshalJSON() ([]byte, error) {
+	t, err := a.MarshalText()
+	if err != nil {
+		return nil, &json.MarshalerError{Type: reflect.TypeOf(a), Err: err}
+	}
+	b := make([]byte, len(t)+2)
+	b[0], b[len(b)-1] = '"', '"' // add quotes
+	copy(b[1:], t)
+	return b, nil
+}
+
+// UnmarshalJSON parses a hash in hex syntax.
+func (a *Address) UnmarshalJSON(input []byte) error {
+	if !(len(input) >= 2 && input[0] == '"' && input[len(input)-1] == '"') {
+		return &json.UnmarshalTypeError{Value: "non-string", Type: reflect.TypeOf(Address{})}
+	}
+	if err := a.UnmarshalText(input[1 : len(input)-1]); err != nil {
+		return err
+	}
+	return nil
+}
+
+func parseAddress(address string, params *chaincfg.Params) (btcutil.Address, AddressType, error) {
+	decoded, err := btcutil.DecodeAddress(address, params)
+	if err != nil {
+		return nil, 0, errors.Wrapf(err, "can't decode address `%s` for network `%s`", address, params.Name)
+	}
+
+	switch decoded.(type) {
+	case *btcutil.AddressWitnessPubKeyHash:
+		return decoded, AddressP2WPKH, nil
+	case *btcutil.AddressTaproot:
+		return decoded, AddressP2TR, nil
+	case *btcutil.AddressScriptHash:
+		return decoded, AddressP2SH, nil
+	case *btcutil.AddressPubKeyHash:
+		return decoded, AddressP2PKH, nil
+	case *btcutil.AddressWitnessScriptHash:
+		return decoded, AddressP2WSH, nil
+	default:
+		return nil, 0, errors.Wrap(errs.Unsupported, "unsupported address type")
+	}
+}
--- a/pkg/btcutils/address_bench_test.go
+++ b/pkg/btcutils/address_bench_test.go
@@ -0,0 +1,80 @@
+package btcutils_test
+
+import (
+	"testing"
+
+	"github.com/btcsuite/btcd/chaincfg"
+	"github.com/gaze-network/indexer-network/pkg/btcutils"
+)
+
+/*
+NOTE:
+
+# Compare this benchmark to go-ethereum/common.Address utils
+- go-ethereum/common.HexToAddress speed: 45 ns/op, 48 B/op, 1 allocs/op
+- go-ethereum/common.IsHexAddress speed: 25 ns/op, 0 B/op, 0 allocs/op
+
+It's slower than go-ethereum/common.Address utils because ethereum wallet address is Hex string 20 bytes,
+but Bitcoin has many types of address and each type has complex algorithm to solve (can't solve and validate address type directly from address string)
+
+20/Jan/2024 @Planxnx Macbook Air M1 16GB
+BenchmarkIsAddress/specific-network/mainnet/P2WPKH-8         	 1776146	       625.6 ns/op	     120 B/op	       3 allocs/op
+BenchmarkIsAddress/specific-network/testnet3/P2WPKH-8        	 1917876	       623.2 ns/op	     120 B/op	       3 allocs/op
+BenchmarkIsAddress/specific-network/mainnet/P2TR-8           	 1330348	       915.4 ns/op	     160 B/op	       3 allocs/op
+BenchmarkIsAddress/specific-network/testnet3/P2TR-8          	 1235806	       931.1 ns/op	     160 B/op	       3 allocs/op
+BenchmarkIsAddress/specific-network/mainnet/P2WSH-8          	 1261730	       960.9 ns/op	     160 B/op	       3 allocs/op
+BenchmarkIsAddress/specific-network/testnet3/P2WSH-8         	 1307851	       916.1 ns/op	     160 B/op	       3 allocs/op
+BenchmarkIsAddress/specific-network/mainnet/P2SH-8           	 3081762	       402.0 ns/op	     192 B/op	       8 allocs/op
+BenchmarkIsAddress/specific-network/testnet3/P2SH-8          	 3245838	       344.9 ns/op	     176 B/op	       7 allocs/op
+BenchmarkIsAddress/specific-network/mainnet/P2PKH-8          	 2904252	       410.4 ns/op	     184 B/op	       8 allocs/op
+BenchmarkIsAddress/specific-network/testnet3/P2PKH-8         	 3522332	       342.8 ns/op	     176 B/op	       7 allocs/op
+BenchmarkIsAddress/automate-network/mainnet/P2WPKH-8         	 1882059	       637.6 ns/op	     120 B/op	       3 allocs/op
+BenchmarkIsAddress/automate-network/testnet3/P2WPKH-8        	 1626151	       664.8 ns/op	     120 B/op	       3 allocs/op
+BenchmarkIsAddress/automate-network/mainnet/P2TR-8           	 1250253	       952.1 ns/op	     160 B/op	       3 allocs/op
+BenchmarkIsAddress/automate-network/testnet3/P2TR-8          	 1257901	       993.7 ns/op	     160 B/op	       3 allocs/op
+BenchmarkIsAddress/automate-network/mainnet/P2WSH-8          	 1000000	      1005 ns/op	     160 B/op	       3 allocs/op
+BenchmarkIsAddress/automate-network/testnet3/P2WSH-8         	 1209108	       971.2 ns/op	     160 B/op	       3 allocs/op
+BenchmarkIsAddress/automate-network/mainnet/P2SH-8           	 1869075	       625.0 ns/op	     268 B/op	       9 allocs/op
+BenchmarkIsAddress/automate-network/testnet3/P2SH-8          	  779496	      1609 ns/op	     694 B/op	      17 allocs/op
+BenchmarkIsAddress/automate-network/mainnet/P2PKH-8          	 1924058	       650.6 ns/op	     259 B/op	       9 allocs/op
+BenchmarkIsAddress/automate-network/testnet3/P2PKH-8         	  721510	      1690 ns/op	     694 B/op	      17 allocs/op
+*/
+func BenchmarkIsAddress(b *testing.B) {
+	cases := []btcutils.Address{
+		/* P2WPKH */ btcutils.NewAddress("bc1qfpgdxtpl7kz5qdus2pmexyjaza99c28q8uyczh", &chaincfg.MainNetParams),
+		/* P2WPKH */ btcutils.NewAddress("tb1qfpgdxtpl7kz5qdus2pmexyjaza99c28qd6ltey", &chaincfg.TestNet3Params),
+		/* P2TR */ btcutils.NewAddress("bc1p7h87kqsmpzatddzhdhuy9gmxdpvn5kvar6hhqlgau8d2ffa0pa3qvz5d38", &chaincfg.MainNetParams),
+		/* P2TR */ btcutils.NewAddress("tb1p7h87kqsmpzatddzhdhuy9gmxdpvn5kvar6hhqlgau8d2ffa0pa3qm2zztg", &chaincfg.TestNet3Params),
+		/* P2WSH */ btcutils.NewAddress("bc1qeklep85ntjz4605drds6aww9u0qr46qzrv5xswd35uhjuj8ahfcqgf6hak", &chaincfg.MainNetParams),
+		/* P2WSH */ btcutils.NewAddress("tb1qrp33g0q5c5txsp9arysrx4k6zdkfs4nce4xj0gdcccefvpysxf3q0sl5k7", &chaincfg.TestNet3Params),
+		/* P2SH */ btcutils.NewAddress("3Ccte7SJz71tcssLPZy3TdWz5DTPeNRbPw", &chaincfg.MainNetParams),
+		/* P2SH */ btcutils.NewAddress("2NCxMvHPTduZcCuUeAiWUpuwHga7Y66y9XJ", &chaincfg.TestNet3Params),
+		/* P2PKH */ btcutils.NewAddress("1KrRZSShVkdc8J71CtY4wdw46Rx3BRLKyH", &chaincfg.MainNetParams),
+		/* P2PKH */ btcutils.NewAddress("migbBPcDajPfffrhoLpYFTQNXQFbWbhpz3", &chaincfg.TestNet3Params),
+	}
+
+	b.Run("specific-network", func(b *testing.B) {
+		for _, c := range cases {
+			b.Run(c.NetworkName()+"/"+c.Type().String(), func(b *testing.B) {
+				b.ResetTimer()
+				for i := 0; i < b.N; i++ {
+					_ = btcutils.IsAddress(c.String(), c.Net())
+				}
+			})
+		}
+	})
+
+	b.Run("automate-network", func(b *testing.B) {
+		for _, c := range cases {
+			b.Run(c.NetworkName()+"/"+c.Type().String(), func(b *testing.B) {
+				b.ResetTimer()
+				for i := 0; i < b.N; i++ {
+					ok := btcutils.IsAddress(c.String())
+					if !ok {
+						b.Error("IsAddress returned false")
+					}
+				}
+			})
+		}
+	})
+}
--- a/pkg/btcutils/address_test.go
+++ b/pkg/btcutils/address_test.go
@@ -0,0 +1,449 @@
+package btcutils_test
+
+import (
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"testing"
+
+	"github.com/btcsuite/btcd/chaincfg"
+	"github.com/gaze-network/indexer-network/pkg/btcutils"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestGetAddressType(t *testing.T) {
+	type Spec struct {
+		Address    string
+		DefaultNet *chaincfg.Params
+
+		ExpectedError       error
+		ExpectedAddressType btcutils.AddressType
+	}
+
+	specs := []Spec{
+		{
+			Address:    "bc1qfpgdxtpl7kz5qdus2pmexyjaza99c28q8uyczh",
+			DefaultNet: &chaincfg.MainNetParams,
+
+			ExpectedError:       nil,
+			ExpectedAddressType: btcutils.AddressP2WPKH,
+		},
+		{
+			Address:    "tb1qfpgdxtpl7kz5qdus2pmexyjaza99c28qd6ltey",
+			DefaultNet: &chaincfg.MainNetParams,
+
+			ExpectedError:       nil,
+			ExpectedAddressType: btcutils.AddressP2WPKH,
+		},
+		{
+			Address:    "bc1p7h87kqsmpzatddzhdhuy9gmxdpvn5kvar6hhqlgau8d2ffa0pa3qvz5d38",
+			DefaultNet: &chaincfg.MainNetParams,
+
+			ExpectedError:       nil,
+			ExpectedAddressType: btcutils.AddressP2TR,
+		},
+		{
+			Address:    "tb1p7h87kqsmpzatddzhdhuy9gmxdpvn5kvar6hhqlgau8d2ffa0pa3qm2zztg",
+			DefaultNet: &chaincfg.MainNetParams,
+
+			ExpectedError:       nil,
+			ExpectedAddressType: btcutils.AddressP2TR,
+		},
+		{
+			Address:    "3Ccte7SJz71tcssLPZy3TdWz5DTPeNRbPw",
+			DefaultNet: &chaincfg.MainNetParams,
+
+			ExpectedError:       nil,
+			ExpectedAddressType: btcutils.AddressP2SH,
+		},
+		{
+			Address:    "1KrRZSShVkdc8J71CtY4wdw46Rx3BRLKyH",
+			DefaultNet: &chaincfg.MainNetParams,
+
+			ExpectedError:       nil,
+			ExpectedAddressType: btcutils.AddressP2PKH,
+		},
+		{
+			Address:    "bc1qeklep85ntjz4605drds6aww9u0qr46qzrv5xswd35uhjuj8ahfcqgf6hak",
+			DefaultNet: &chaincfg.MainNetParams,
+
+			ExpectedError:       nil,
+			ExpectedAddressType: btcutils.AddressP2WSH,
+		},
+		{
+			Address:    "migbBPcDajPfffrhoLpYFTQNXQFbWbhpz3",
+			DefaultNet: &chaincfg.TestNet3Params,
+
+			ExpectedError:       nil,
+			ExpectedAddressType: btcutils.AddressP2PKH,
+		},
+		{
+			Address:    "tb1qrp33g0q5c5txsp9arysrx4k6zdkfs4nce4xj0gdcccefvpysxf3q0sl5k7",
+			DefaultNet: &chaincfg.MainNetParams,
+
+			ExpectedError:       nil,
+			ExpectedAddressType: btcutils.AddressP2WSH,
+		},
+		{
+			Address:    "2NCxMvHPTduZcCuUeAiWUpuwHga7Y66y9XJ",
+			DefaultNet: &chaincfg.TestNet3Params,
+
+			ExpectedError:       nil,
+			ExpectedAddressType: btcutils.AddressP2SH,
+		},
+	}
+
+	for _, spec := range specs {
+		t.Run(fmt.Sprintf("address:%s", spec.Address), func(t *testing.T) {
+			actualAddressType, actualError := btcutils.GetAddressType(spec.Address, spec.DefaultNet)
+			if spec.ExpectedError != nil {
+				assert.ErrorIs(t, actualError, spec.ExpectedError)
+			} else {
+				assert.Equal(t, spec.ExpectedAddressType, actualAddressType)
+			}
+		})
+	}
+}
+
+func TestNewAddress(t *testing.T) {
+	type Spec struct {
+		Address    string
+		DefaultNet *chaincfg.Params
+
+		ExpectedAddressType btcutils.AddressType
+	}
+
+	specs := []Spec{
+		{
+			Address: "bc1qfpgdxtpl7kz5qdus2pmexyjaza99c28q8uyczh",
+			// DefaultNet: &chaincfg.MainNetParams, // Optional
+
+			ExpectedAddressType: btcutils.AddressP2WPKH,
+		},
+		{
+			Address: "tb1qfpgdxtpl7kz5qdus2pmexyjaza99c28qd6ltey",
+			// DefaultNet: &chaincfg.MainNetParams, // Optional
+
+			ExpectedAddressType: btcutils.AddressP2WPKH,
+		},
+		{
+			Address: "bc1p7h87kqsmpzatddzhdhuy9gmxdpvn5kvar6hhqlgau8d2ffa0pa3qvz5d38",
+			// DefaultNet: &chaincfg.MainNetParams, // Optional
+
+			ExpectedAddressType: btcutils.AddressP2TR,
+		},
+		{
+			Address: "tb1p7h87kqsmpzatddzhdhuy9gmxdpvn5kvar6hhqlgau8d2ffa0pa3qm2zztg",
+			// DefaultNet: &chaincfg.MainNetParams, // Optional
+
+			ExpectedAddressType: btcutils.AddressP2TR,
+		},
+		{
+			Address: "bc1qeklep85ntjz4605drds6aww9u0qr46qzrv5xswd35uhjuj8ahfcqgf6hak",
+			// DefaultNet: &chaincfg.MainNetParams, // Optional
+
+			ExpectedAddressType: btcutils.AddressP2WSH,
+		},
+		{
+			Address: "tb1qrp33g0q5c5txsp9arysrx4k6zdkfs4nce4xj0gdcccefvpysxf3q0sl5k7",
+			// DefaultNet: &chaincfg.MainNetParams, // Optional
+
+			ExpectedAddressType: btcutils.AddressP2WSH,
+		},
+		{
+			Address:    "3Ccte7SJz71tcssLPZy3TdWz5DTPeNRbPw",
+			DefaultNet: &chaincfg.MainNetParams,
+
+			ExpectedAddressType: btcutils.AddressP2SH,
+		},
+		{
+			Address:    "2NCxMvHPTduZcCuUeAiWUpuwHga7Y66y9XJ",
+			DefaultNet: &chaincfg.TestNet3Params,
+
+			ExpectedAddressType: btcutils.AddressP2SH,
+		},
+		{
+			Address:    "1KrRZSShVkdc8J71CtY4wdw46Rx3BRLKyH",
+			DefaultNet: &chaincfg.MainNetParams,
+
+			ExpectedAddressType: btcutils.AddressP2PKH,
+		},
+		{
+			Address:    "migbBPcDajPfffrhoLpYFTQNXQFbWbhpz3",
+			DefaultNet: &chaincfg.TestNet3Params,
+
+			ExpectedAddressType: btcutils.AddressP2PKH,
+		},
+	}
+
+	for _, spec := range specs {
+		t.Run(fmt.Sprintf("address:%s,type:%s", spec.Address, spec.ExpectedAddressType), func(t *testing.T) {
+			addr := btcutils.NewAddress(spec.Address, spec.DefaultNet)
+
+			assert.Equal(t, spec.ExpectedAddressType, addr.Type())
+			assert.Equal(t, spec.Address, addr.String())
+		})
+	}
+}
+
+func TestIsAddress(t *testing.T) {
+	type Spec struct {
+		Address  string
+		Expected bool
+	}
+
+	specs := []Spec{
+		{
+			Address: "bc1qfpgdxtpl7kz5qdus2pmexyjaza99c28q8uyczh",
+
+			Expected: true,
+		},
+		{
+			Address: "tb1qfpgdxtpl7kz5qdus2pmexyjaza99c28qd6ltey",
+
+			Expected: true,
+		},
+		{
+			Address: "bc1p7h87kqsmpzatddzhdhuy9gmxdpvn5kvar6hhqlgau8d2ffa0pa3qvz5d38",
+
+			Expected: true,
+		},
+		{
+			Address: "tb1p7h87kqsmpzatddzhdhuy9gmxdpvn5kvar6hhqlgau8d2ffa0pa3qm2zztg",
+
+			Expected: true,
+		},
+		{
+			Address: "bc1qeklep85ntjz4605drds6aww9u0qr46qzrv5xswd35uhjuj8ahfcqgf6hak",
+
+			Expected: true,
+		},
+		{
+			Address: "tb1qrp33g0q5c5txsp9arysrx4k6zdkfs4nce4xj0gdcccefvpysxf3q0sl5k7",
+
+			Expected: true,
+		},
+		{
+			Address: "3Ccte7SJz71tcssLPZy3TdWz5DTPeNRbPw",
+
+			Expected: true,
+		},
+		{
+			Address: "2NCxMvHPTduZcCuUeAiWUpuwHga7Y66y9XJ",
+
+			Expected: true,
+		},
+		{
+			Address: "1KrRZSShVkdc8J71CtY4wdw46Rx3BRLKyH",
+
+			Expected: true,
+		},
+		{
+			Address: "migbBPcDajPfffrhoLpYFTQNXQFbWbhpz3",
+
+			Expected: true,
+		},
+		{
+			Address: "",
+
+			Expected: false,
+		},
+		{
+			Address: "migbBPcDajPfffrhoLpYFTQNXQFbWbhpz2",
+
+			Expected: false,
+		},
+		{
+			Address: "bc1qfpgdxtpl7kz5qdus2pmexyjaza99c28q8uyczz",
+
+			Expected: false,
+		},
+	}
+
+	for _, spec := range specs {
+		t.Run(fmt.Sprintf("address:%s", spec.Address), func(t *testing.T) {
+			ok := btcutils.IsAddress(spec.Address)
+			assert.Equal(t, spec.Expected, ok)
+		})
+	}
+}
+
+func TestAddressEncoding(t *testing.T) {
+	rawAddress := "bc1qfpgdxtpl7kz5qdus2pmexyjaza99c28q8uyczh"
+	address := btcutils.NewAddress(rawAddress, &chaincfg.MainNetParams)
+
+	type Spec struct {
+		Data     interface{}
+		Expected string
+	}
+
+	specs := []Spec{
+		{
+			Data:     address,
+			Expected: fmt.Sprintf(`"%s"`, rawAddress),
+		},
+		{
+			Data: map[string]interface{}{
+				"address": rawAddress,
+			},
+			Expected: fmt.Sprintf(`{"address":"%s"}`, rawAddress),
+		},
+	}
+
+	for i, spec := range specs {
+		t.Run(fmt.Sprint(i+1), func(t *testing.T) {
+			actual, err := json.Marshal(spec.Data)
+			assert.NoError(t, err)
+			assert.Equal(t, spec.Expected, string(actual))
+		})
+	}
+}
+
+func TestAddressDecoding(t *testing.T) {
+	rawAddress := "bc1qfpgdxtpl7kz5qdus2pmexyjaza99c28q8uyczh"
+	address := btcutils.NewAddress(rawAddress, &chaincfg.MainNetParams)
+
+	// Case #1: address is a string
+	t.Run("from_string", func(t *testing.T) {
+		input := fmt.Sprintf(`"%s"`, rawAddress)
+		expected := address
+		actual := btcutils.Address{}
+
+		err := json.Unmarshal([]byte(input), &actual)
+		if !assert.NoError(t, err) {
+			t.FailNow()
+		}
+		assert.Equal(t, expected, actual)
+	})
+
+	// Case #2: address is a field of a struct
+	t.Run("from_field_string", func(t *testing.T) {
+		type Data struct {
+			Address btcutils.Address `json:"address"`
+		}
+		input := fmt.Sprintf(`{"address":"%s"}`, rawAddress)
+		expected := Data{Address: address}
+		actual := Data{}
+		err := json.Unmarshal([]byte(input), &actual)
+		if !assert.NoError(t, err) {
+			t.FailNow()
+		}
+		assert.Equal(t, expected, actual)
+	})
+
+	// Case #3: address is an element of an array
+	t.Run("from_array", func(t *testing.T) {
+		input := fmt.Sprintf(`["%s"]`, rawAddress)
+		expected := []btcutils.Address{address}
+		actual := []btcutils.Address{}
+		err := json.Unmarshal([]byte(input), &actual)
+		if !assert.NoError(t, err) {
+			t.FailNow()
+		}
+		assert.Equal(t, expected, actual)
+	})
+
+	// Case #4: not supported address type
+	t.Run("from_string/not_address", func(t *testing.T) {
+		input := fmt.Sprintf(`"%s"`, "THIS_IS_NOT_SUPPORTED_ADDRESS")
+		actual := btcutils.Address{}
+		err := json.Unmarshal([]byte(input), &actual)
+		assert.Error(t, err)
+	})
+
+	// Case #5: invalid field type
+	t.Run("from_number", func(t *testing.T) {
+		type Data struct {
+			Address btcutils.Address `json:"address"`
+		}
+		input := fmt.Sprintf(`{"address":%d}`, 123)
+		actual := Data{}
+		err := json.Unmarshal([]byte(input), &actual)
+		assert.Error(t, err)
+	})
+}
+
+func TestAddressPkScript(t *testing.T) {
+	anyErr := errors.New("any error")
+	type Spec struct {
+		Address          string
+		DefaultNet       *chaincfg.Params
+		ExpectedError    error
+		ExpectedPkScript string // hex encoded
+	}
+	specs := []Spec{
+		{
+			Address:          "some_invalid_address",
+			DefaultNet:       &chaincfg.MainNetParams,
+			ExpectedError:    anyErr,
+			ExpectedPkScript: "",
+		},
+		{
+			// P2WPKH
+			Address:          "bc1qdx72th7e3z8zc5wdrdxweswfcne974pjneyjln",
+			DefaultNet:       &chaincfg.MainNetParams,
+			ExpectedError:    nil,
+			ExpectedPkScript: "001469bca5dfd9888e2c51cd1b4cecc1c9c4f25f5432",
+		},
+		{
+			// P2WPKH
+			Address:          "bc1q7cj6gz6t3d28qg7kxhrc7h5t3h0re34fqqalga",
+			DefaultNet:       &chaincfg.MainNetParams,
+			ExpectedError:    nil,
+			ExpectedPkScript: "0014f625a40b4b8b547023d635c78f5e8b8dde3cc6a9",
+		},
+		{
+			// P2TR
+			Address:          "bc1pfd0zw2jwlpn4xckpr3dxpt7x0gw6wetuftxvrc4dt2qgn9azjuus65fug6",
+			DefaultNet:       &chaincfg.MainNetParams,
+			ExpectedError:    nil,
+			ExpectedPkScript: "51204b5e272a4ef8675362c11c5a60afc67a1da7657c4accc1e2ad5a808997a29739",
+		},
+		{
+			// P2TR
+			Address:          "bc1pxpumml545tqum5afarzlmnnez2npd35nvf0j0vnrp88nemqsn54qle05sm",
+			DefaultNet:       &chaincfg.MainNetParams,
+			ExpectedError:    nil,
+			ExpectedPkScript: "51203079bdfe95a2c1cdd3a9e8c5fdce7912a616c693625f27b26309cf3cec109d2a",
+		},
+		{
+			// P2SH
+			Address:          "3Ccte7SJz71tcssLPZy3TdWz5DTPeNRbPw",
+			DefaultNet:       &chaincfg.MainNetParams,
+			ExpectedError:    nil,
+			ExpectedPkScript: "a91477e1a3d54f545d83869ae3a6b28b071422801d7b87",
+		},
+		{
+			// P2PKH
+			Address:          "1KrRZSShVkdc8J71CtY4wdw46Rx3BRLKyH",
+			DefaultNet:       &chaincfg.MainNetParams,
+			ExpectedError:    nil,
+			ExpectedPkScript: "76a914cecb25b53809991c7beef2d27bc2be49e78c684388ac",
+		},
+		{
+			// P2WSH
+			Address:          "bc1qeklep85ntjz4605drds6aww9u0qr46qzrv5xswd35uhjuj8ahfcqgf6hak",
+			DefaultNet:       &chaincfg.MainNetParams,
+			ExpectedError:    nil,
+			ExpectedPkScript: "0020cdbf909e935c855d3e8d1b61aeb9c5e3c03ae8021b286839b1a72f2e48fdba70",
+		},
+	}
+
+	for _, spec := range specs {
+		t.Run(spec.Address, func(t *testing.T) {
+			addr, err := btcutils.SafeNewAddress(spec.Address, spec.DefaultNet)
+			if spec.ExpectedError != nil {
+				if errors.Is(spec.ExpectedError, anyErr) {
+					require.Error(t, err)
+				} else {
+					require.ErrorIs(t, err, spec.ExpectedError)
+				}
+				return
+			}
+			require.NoError(t, err)
+			assert.Equal(t, spec.ExpectedPkScript, hex.EncodeToString(addr.ScriptPubKey()))
+		})
+	}
+}
--- a/pkg/btcutils/btc.go
+++ b/pkg/btcutils/btc.go
@@ -0,0 +1,58 @@
+package btcutils
+
+import (
+	"github.com/Cleverse/go-utilities/utils"
+	"github.com/btcsuite/btcd/chaincfg"
+	"github.com/btcsuite/btcd/chaincfg/chainhash"
+	"github.com/btcsuite/btcd/txscript"
+)
+
+var (
+	// NullAddress is an address that script address is all zeros.
+	NullAddress = NewAddress("1111111111111111111114oLvT2", &chaincfg.MainNetParams)
+
+	// NullHash is a hash that all bytes are zero.
+	NullHash = utils.Must(chainhash.NewHashFromStr("0000000000000000000000000000000000000000000000000000000000000000"))
+)
+
+// TransactionType is the type of bitcoin transaction
+// It's an alias of txscript.ScriptClass
+type TransactionType = txscript.ScriptClass
+
+// AddressType is the type of bitcoin address.
+// It's an alias of txscript.ScriptClass
+type AddressType = txscript.ScriptClass
+
+// Types of bitcoin transaction
+const (
+	TransactionP2WPKH  = txscript.WitnessV0PubKeyHashTy
+	TransactionP2TR    = txscript.WitnessV1TaprootTy
+	TransactionTaproot = TransactionP2TR // Alias of P2TR
+	TransactionP2SH    = txscript.ScriptHashTy
+	TransactionP2PKH   = txscript.PubKeyHashTy
+	TransactionP2WSH   = txscript.WitnessV0ScriptHashTy
+)
+
+// Types of bitcoin address
+const (
+	AddressP2WPKH  = txscript.WitnessV0PubKeyHashTy
+	AddressP2TR    = txscript.WitnessV1TaprootTy
+	AddressTaproot = AddressP2TR // Alias of P2TR
+	AddressP2SH    = txscript.ScriptHashTy
+	AddressP2PKH   = txscript.PubKeyHashTy
+	AddressP2WSH   = txscript.WitnessV0ScriptHashTy
+)
+
+// IsSupportType returns true if the given tx/address type is supported.
+func IsSupportType(t txscript.ScriptClass) bool {
+	_, ok := supportedTypes[t]
+	return ok
+}
+
+var supportedTypes = map[txscript.ScriptClass]struct{}{
+	txscript.WitnessV0PubKeyHashTy: {},
+	txscript.WitnessV1TaprootTy:    {},
+	txscript.ScriptHashTy:          {},
+	txscript.PubKeyHashTy:          {},
+	txscript.WitnessV0ScriptHashTy: {},
+}
--- a/pkg/btcutils/btc_network.go
+++ b/pkg/btcutils/btc_network.go
@@ -0,0 +1,23 @@
+package btcutils
+
+import (
+	"github.com/btcsuite/btcd/chaincfg"
+)
+
+var supportedNetworks = map[string]*chaincfg.Params{
+	"mainnet": &chaincfg.MainNetParams,
+	"testnet": &chaincfg.TestNet3Params,
+}
+
+// IsSupportedNetwork returns true if the given network is supported.
+//
+// TODO: create enum for network
+func IsSupportedNetwork(network string) bool {
+	_, ok := supportedNetworks[network]
+	return ok
+}
+
+// GetNetParams returns the *chaincfg.Params for the given network.
+func GetNetParams(network string) *chaincfg.Params {
+	return supportedNetworks[network]
+}
--- a/pkg/btcutils/pk_script.go
+++ b/pkg/btcutils/pk_script.go
@@ -0,0 +1,69 @@
+package btcutils
+
+import (
+	"github.com/Cleverse/go-utilities/utils"
+	"github.com/btcsuite/btcd/chaincfg"
+	"github.com/btcsuite/btcd/txscript"
+	"github.com/cockroachdb/errors"
+	"github.com/gaze-network/indexer-network/common/errs"
+)
+
+// NewPkScript creates a pubkey script(or witness program) from the given address string
+//
+// see: https://en.bitcoin.it/wiki/Script
+func NewPkScript(address string, defaultNet ...*chaincfg.Params) ([]byte, error) {
+	net := utils.DefaultOptional(defaultNet, &chaincfg.MainNetParams)
+	decoded, _, err := parseAddress(address, net)
+	if err != nil {
+		return nil, errors.Wrap(err, "can't parse address")
+	}
+	scriptPubkey, err := txscript.PayToAddrScript(decoded)
+	if err != nil {
+		return nil, errors.Wrap(err, "can't get script pubkey")
+	}
+	return scriptPubkey, nil
+}
+
+// GetAddressTypeFromPkScript returns the address type from the given pubkey script/script pubkey.
+func GetAddressTypeFromPkScript(pkScript []byte, defaultNet ...*chaincfg.Params) (AddressType, error) {
+	net := utils.DefaultOptional(defaultNet, &chaincfg.MainNetParams)
+	scriptClass, _, _, err := txscript.ExtractPkScriptAddrs(pkScript, net)
+	if err != nil {
+		return txscript.NonStandardTy, errors.Wrap(err, "can't parse pkScript")
+	}
+	return scriptClass, nil
+}
+
+// ExtractAddressFromPkScript extracts address from the given pubkey script/script pubkey.
+// multi-signature script not supported
+func ExtractAddressFromPkScript(pkScript []byte, defaultNet ...*chaincfg.Params) (Address, error) {
+	if len(pkScript) == 0 {
+		return Address{}, errors.New("empty pkScript")
+	}
+	if pkScript[0] == txscript.OP_RETURN {
+		return Address{}, errors.Wrap(errs.NotSupported, "OP_RETURN script")
+	}
+	net := utils.DefaultOptional(defaultNet, &chaincfg.MainNetParams)
+	addrType, addrs, _, err := txscript.ExtractPkScriptAddrs(pkScript, net)
+	if err != nil {
+		return Address{}, errors.Wrap(err, "can't parse pkScript")
+	}
+	if !IsSupportType(addrType) {
+		return Address{}, errors.Wrapf(errs.NotSupported, "unsupported pkscript type %s", addrType)
+	}
+	if len(addrs) == 0 {
+		return Address{}, errors.New("can't extract address from pkScript")
+	}
+
+	fixedPkScript := [MaxSupportedPkScriptSize]byte{}
+	copy(fixedPkScript[:], pkScript)
+
+	return Address{
+		decoded:          addrs[0],
+		net:              net,
+		encoded:          addrs[0].EncodeAddress(),
+		encodedType:      addrType,
+		scriptPubKey:     fixedPkScript,
+		scriptPubKeySize: len(pkScript),
+	}, nil
+}
--- a/pkg/btcutils/pk_script_test.go
+++ b/pkg/btcutils/pk_script_test.go
@@ -0,0 +1,217 @@
+package btcutils_test
+
+import (
+	"encoding/hex"
+	"fmt"
+	"testing"
+
+	"github.com/Cleverse/go-utilities/utils"
+	"github.com/btcsuite/btcd/btcutil"
+	"github.com/btcsuite/btcd/chaincfg"
+	"github.com/btcsuite/btcd/txscript"
+	"github.com/cockroachdb/errors"
+	"github.com/gaze-network/indexer-network/pkg/btcutils"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestNewPkScript(t *testing.T) {
+	anyError := errors.New("any error")
+
+	type Spec struct {
+		Address          string
+		DefaultNet       *chaincfg.Params
+		ExpectedError    error
+		ExpectedPkScript string // hex encoded
+	}
+
+	specs := []Spec{
+		{
+			Address:          "some_invalid_address",
+			DefaultNet:       &chaincfg.MainNetParams,
+			ExpectedError:    anyError,
+			ExpectedPkScript: "",
+		},
+		{
+			// P2WPKH
+			Address:          "bc1qdx72th7e3z8zc5wdrdxweswfcne974pjneyjln",
+			DefaultNet:       &chaincfg.MainNetParams,
+			ExpectedError:    nil,
+			ExpectedPkScript: "001469bca5dfd9888e2c51cd1b4cecc1c9c4f25f5432",
+		},
+		{
+			// P2WPKH
+			Address:          "bc1q7cj6gz6t3d28qg7kxhrc7h5t3h0re34fqqalga",
+			DefaultNet:       &chaincfg.MainNetParams,
+			ExpectedError:    nil,
+			ExpectedPkScript: "0014f625a40b4b8b547023d635c78f5e8b8dde3cc6a9",
+		},
+		{
+			// P2TR
+			Address:          "bc1pfd0zw2jwlpn4xckpr3dxpt7x0gw6wetuftxvrc4dt2qgn9azjuus65fug6",
+			DefaultNet:       &chaincfg.MainNetParams,
+			ExpectedError:    nil,
+			ExpectedPkScript: "51204b5e272a4ef8675362c11c5a60afc67a1da7657c4accc1e2ad5a808997a29739",
+		},
+		{
+			// P2TR
+			Address:          "bc1pxpumml545tqum5afarzlmnnez2npd35nvf0j0vnrp88nemqsn54qle05sm",
+			DefaultNet:       &chaincfg.MainNetParams,
+			ExpectedError:    nil,
+			ExpectedPkScript: "51203079bdfe95a2c1cdd3a9e8c5fdce7912a616c693625f27b26309cf3cec109d2a",
+		},
+		{
+			// P2SH
+			Address:          "3Ccte7SJz71tcssLPZy3TdWz5DTPeNRbPw",
+			DefaultNet:       &chaincfg.MainNetParams,
+			ExpectedError:    nil,
+			ExpectedPkScript: "a91477e1a3d54f545d83869ae3a6b28b071422801d7b87",
+		},
+		{
+			// P2PKH
+			Address:          "1KrRZSShVkdc8J71CtY4wdw46Rx3BRLKyH",
+			DefaultNet:       &chaincfg.MainNetParams,
+			ExpectedError:    nil,
+			ExpectedPkScript: "76a914cecb25b53809991c7beef2d27bc2be49e78c684388ac",
+		},
+		{
+			// P2WSH
+			Address:          "bc1qeklep85ntjz4605drds6aww9u0qr46qzrv5xswd35uhjuj8ahfcqgf6hak",
+			DefaultNet:       &chaincfg.MainNetParams,
+			ExpectedError:    nil,
+			ExpectedPkScript: "0020cdbf909e935c855d3e8d1b61aeb9c5e3c03ae8021b286839b1a72f2e48fdba70",
+		},
+	}
+
+	for _, spec := range specs {
+		t.Run(fmt.Sprintf("address:%s", spec.Address), func(t *testing.T) {
+			// Validate Expected PkScript
+			if spec.ExpectedError == nil {
+				{
+					expectedPkScriptRaw, err := hex.DecodeString(spec.ExpectedPkScript)
+					if err != nil {
+						t.Fatalf("can't decode expected pkscript %s, Reason: %s", spec.ExpectedPkScript, err)
+					}
+					expectedPkScript, err := txscript.ParsePkScript(expectedPkScriptRaw)
+					if err != nil {
+						t.Fatalf("invalid expected pkscript %s, Reason: %s", spec.ExpectedPkScript, err)
+					}
+
+					expectedAddress, err := expectedPkScript.Address(spec.DefaultNet)
+					if err != nil {
+						t.Fatalf("can't get address from expected pkscript %s, Reason: %s", spec.ExpectedPkScript, err)
+					}
+					assert.Equal(t, spec.Address, expectedAddress.EncodeAddress())
+				}
+				{
+					address, err := btcutil.DecodeAddress(spec.Address, spec.DefaultNet)
+					if err != nil {
+						t.Fatalf("can't decode address %s(%s),Reason: %s", spec.Address, spec.DefaultNet.Name, err)
+					}
+
+					pkScript, err := txscript.PayToAddrScript(address)
+					if err != nil {
+						t.Fatalf("can't get pkscript from address %s(%s),Reason: %s", spec.Address, spec.DefaultNet.Name, err)
+					}
+
+					pkScriptStr := hex.EncodeToString(pkScript)
+					assert.Equal(t, spec.ExpectedPkScript, pkScriptStr)
+				}
+			}
+
+			pkScript, err := btcutils.NewPkScript(spec.Address, spec.DefaultNet)
+			if spec.ExpectedError == anyError {
+				assert.Error(t, err)
+			} else if spec.ExpectedError != nil {
+				assert.ErrorIs(t, err, spec.ExpectedError)
+			} else {
+				address, err := btcutils.SafeNewAddress(spec.Address, spec.DefaultNet)
+				if err != nil {
+					t.Fatalf("can't create address %s(%s),Reason: %s", spec.Address, spec.DefaultNet.Name, err)
+				}
+
+				// ScriptPubKey from address and from NewPkScript should be the same
+				assert.Equal(t, address.ScriptPubKey(), pkScript)
+
+				// Expected PkScript and New PkScript should be the same
+				pkScriptStr := hex.EncodeToString(pkScript)
+				assert.Equal(t, spec.ExpectedPkScript, pkScriptStr)
+
+				// Can convert PkScript back to same address
+				acualPkScript, err := txscript.ParsePkScript(address.ScriptPubKey())
+				if !assert.NoError(t, err) {
+					t.Fail()
+				}
+				assert.Equal(t, address.Decoded().String(), utils.Must(acualPkScript.Address(spec.DefaultNet)).String())
+			}
+		})
+	}
+}
+
+func TestGetAddressTypeFromPkScript(t *testing.T) {
+	type Spec struct {
+		PubkeyScript string
+
+		ExpectedError       error
+		ExpectedAddressType btcutils.AddressType
+	}
+
+	specs := []Spec{
+		{
+			PubkeyScript: "0014602181cc89f7c9f54cb6d7607a3445e3e022895d",
+
+			ExpectedError:       nil,
+			ExpectedAddressType: btcutils.AddressP2WPKH,
+		},
+		{
+			PubkeyScript: "5120ef8d59038dd51093fbfff794f658a07a3697b94d9e6d24e45b28abd88f10e33d",
+
+			ExpectedError:       nil,
+			ExpectedAddressType: btcutils.AddressP2TR,
+		},
+		{
+			PubkeyScript: "a91416eef7e84fb9821db1341b6ccef1c4a4e5ec21e487",
+
+			ExpectedError:       nil,
+			ExpectedAddressType: btcutils.AddressP2SH,
+		},
+		{
+			PubkeyScript: "76a914cecb25b53809991c7beef2d27bc2be49e78c684388ac",
+
+			ExpectedError:       nil,
+			ExpectedAddressType: btcutils.AddressP2PKH,
+		},
+		{
+			PubkeyScript: "0020cdbf909e935c855d3e8d1b61aeb9c5e3c03ae8021b286839b1a72f2e48fdba70",
+
+			ExpectedError:       nil,
+			ExpectedAddressType: btcutils.AddressP2WSH,
+		},
+		{
+			PubkeyScript: "0020cdbf909e935c855d3e8d1b61aeb9c5e3c03ae8021b286839b1a72f2e48fdba70",
+
+			ExpectedError:       nil,
+			ExpectedAddressType: btcutils.AddressP2WSH,
+		},
+		{
+			PubkeyScript: "6a5d0614c0a2331441",
+
+			ExpectedError:       nil,
+			ExpectedAddressType: txscript.NonStandardTy,
+		},
+	}
+
+	for _, spec := range specs {
+		t.Run(fmt.Sprintf("PkScript:%s", spec.PubkeyScript), func(t *testing.T) {
+			pkScript, err := hex.DecodeString(spec.PubkeyScript)
+			if err != nil {
+				t.Fail()
+			}
+			actualAddressType, actualError := btcutils.GetAddressTypeFromPkScript(pkScript)
+			if spec.ExpectedError != nil {
+				assert.ErrorIs(t, actualError, spec.ExpectedError)
+			} else {
+				assert.Equal(t, spec.ExpectedAddressType, actualAddressType)
+			}
+		})
+	}
+}
--- a/pkg/btcutils/psbtutils/encoding.go
+++ b/pkg/btcutils/psbtutils/encoding.go
@@ -0,0 +1,92 @@
+package psbtutils
+
+import (
+	"bytes"
+	"encoding/base64"
+	"encoding/hex"
+
+	"github.com/Cleverse/go-utilities/utils"
+	"github.com/btcsuite/btcd/btcutil/psbt"
+	"github.com/cockroachdb/errors"
+	"github.com/gaze-network/indexer-network/common/errs"
+)
+
+const (
+	// default psbt encoding is hex
+	DefaultEncoding = EncodingHex
+)
+
+type Encoding string
+
+const (
+	EncodingBase64 Encoding = "base64"
+	EncodingHex    Encoding = "hex"
+)
+
+// DecodeString decodes a psbt hex/base64 string into a psbt.Packet
+//
+// encoding is optional, default is EncodingHex
+func DecodeString(psbtStr string, encoding ...Encoding) (*psbt.Packet, error) {
+	pC, err := Decode([]byte(psbtStr), encoding...)
+	return pC, errors.WithStack(err)
+}
+
+// Decode decodes a psbt hex/base64 byte into a psbt.Packet
+//
+// encoding is optional, default is EncodingHex
+func Decode(psbtB []byte, encoding ...Encoding) (*psbt.Packet, error) {
+	enc, ok := utils.Optional(encoding)
+	if !ok {
+		enc = DefaultEncoding
+	}
+
+	var (
+		psbtBytes []byte
+		err       error
+	)
+
+	switch enc {
+	case EncodingBase64, "b64":
+		psbtBytes = make([]byte, base64.StdEncoding.DecodedLen(len(psbtB)))
+		_, err = base64.StdEncoding.Decode(psbtBytes, psbtB)
+	case EncodingHex:
+		psbtBytes = make([]byte, hex.DecodedLen(len(psbtB)))
+		_, err = hex.Decode(psbtBytes, psbtB)
+	default:
+		return nil, errors.Wrap(errs.Unsupported, "invalid encoding")
+	}
+	if err != nil {
+		return nil, errors.Wrap(err, "can't decode psbt string")
+	}
+
+	pC, err := psbt.NewFromRawBytes(bytes.NewReader(psbtBytes), false)
+	if err != nil {
+		return nil, errors.Wrap(err, "can't create psbt from given psbt")
+	}
+
+	return pC, nil
+}
+
+// EncodeToString encodes a psbt.Packet into a psbt hex/base64 string
+//
+// encoding is optional, default is EncodingHex
+func EncodeToString(pC *psbt.Packet, encoding ...Encoding) (string, error) {
+	enc, ok := utils.Optional(encoding)
+	if !ok {
+		enc = DefaultEncoding
+	}
+
+	var buf bytes.Buffer
+	if err := pC.Serialize(&buf); err != nil {
+		return "", errors.Wrap(err, "can't serialize psbt")
+	}
+
+	switch enc {
+	case EncodingBase64, "b64":
+		return base64.StdEncoding.EncodeToString(buf.Bytes()), nil
+	case EncodingHex:
+		return hex.EncodeToString(buf.Bytes()), nil
+	default:
+		return "", errors.Wrap(errs.Unsupported, "invalid encoding")
+	}
+}
--- a/pkg/btcutils/psbtutils/fee.go
+++ b/pkg/btcutils/psbtutils/fee.go
@@ -0,0 +1,110 @@
+package psbtutils
+
+import (
+	"math"
+
+	"github.com/btcsuite/btcd/btcutil/psbt"
+	"github.com/cockroachdb/errors"
+	"github.com/gaze-network/indexer-network/common/errs"
+	"github.com/gaze-network/indexer-network/pkg/btcutils"
+)
+
+// TxFee returns satoshis fee of a transaction given the fee rate (sat/vB)
+// and the number of inputs and outputs.
+func TxFee(feeRate int64, p *psbt.Packet) (int64, error) {
+	size, err := PSBTSize(p)
+	if err != nil {
+		return 0, errors.Wrap(err, "psbt size")
+	}
+	return int64(math.Ceil(size * float64(feeRate))), nil
+}
+
+func PredictTxFee(feeRate int64, inputs, outputs int) int64 {
+	/**
+	TODO: handle edge cases like:
+		1. when we predict that we need to use unnecessary UTXOs
+		2. when we predict that we need to use more value than user have, but user do have enough for the actual transaction
+
+	Idea for solving this:
+		- When trying to find the best UTXOs to use, we:
+			- Will not reject when user's balance is not enough, instead we will return all UTXOs even if it's not enough.
+			- Will be okay returning excessive UTXOs (say we predict we need 10K satoshis, but actually we only need 5K satoshis, then we will return UTXOs enough for 10K satoshis)
+		- And then we:
+			- Construct the actual PSBT, then select UTXOs to use accordingly,
+			- If the user's balance is not enough, then we will return an error,
+			- Or if when we predict we expect to use more UTXOs than the actual transaction, then we will just use what's needed.
+	*/
+	size := defaultOverhead + 148*float64(inputs) + 43*float64(outputs)
+	return int64(math.Ceil(size * float64(feeRate)))
+}
+
+type txSize struct {
+	Overhead float64
+	Inputs   float64
+	Outputs  float64
+}
+
+const defaultOverhead = 10.5
+
+// Transaction Virtual Sizes Bytes
+//
+// Reference: https://bitcoinops.org/en/tools/calc-size/
+var txSizes = map[btcutils.TransactionType]txSize{
+	btcutils.TransactionP2WPKH: {
+		Inputs:  68,
+		Outputs: 31,
+	},
+	btcutils.TransactionP2TR: {
+		Inputs:  57.5,
+		Outputs: 43,
+	},
+	btcutils.TransactionP2SH: {
+		Inputs:  91,
+		Outputs: 32,
+	},
+	btcutils.TransactionP2PKH: {
+		Inputs:  148,
+		Outputs: 34,
+	},
+	btcutils.TransactionP2WSH: {
+		Inputs:  104.5,
+		Outputs: 43,
+	},
+}
+
+func PSBTSize(psbt *psbt.Packet) (float64, error) {
+	if err := psbt.SanityCheck(); err != nil {
+		return 0, errors.Wrap(errors.Join(err, errs.InvalidArgument), "psbt sanity check")
+	}
+
+	inputs := map[btcutils.TransactionType]int{}
+	outputs := map[btcutils.TransactionType]int{}
+
+	for _, input := range psbt.Inputs {
+		addrType, err := btcutils.GetAddressTypeFromPkScript(input.WitnessUtxo.PkScript)
+		if err != nil {
+			return 0, errors.Wrap(err, "get address type from pk script")
+		}
+		inputs[addrType]++
+	}
+
+	for _, output := range psbt.UnsignedTx.TxOut {
+		addrType, err := btcutils.GetAddressTypeFromPkScript(output.PkScript)
+		if err != nil {
+			return 0, errors.Wrap(err, "get address type from pk script")
+		}
+		outputs[addrType]++
+	}
+
+	totalSize := defaultOverhead
+	for txType, txSizeData := range txSizes {
+		if inputCount, ok := inputs[txType]; ok {
+			totalSize += txSizeData.Inputs * float64(inputCount)
+		}
+		if outputCount, ok := outputs[txType]; ok {
+			totalSize += txSizeData.Outputs * float64(outputCount)
+		}
+	}
+
+	return totalSize, nil
+}
--- a/pkg/btcutils/psbtutils/fee_test.go
+++ b/pkg/btcutils/psbtutils/fee_test.go
@@ -0,0 +1,131 @@
+package psbtutils_test
+
+import (
+	"fmt"
+	"math"
+	"testing"
+
+	"github.com/gaze-network/indexer-network/pkg/btcutils/psbtutils"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestPSBTSize(t *testing.T) {
+	type Spec struct {
+		Name          string
+		PSBTString    string
+		ExpectedError error
+		ExpectedSize  float64
+	}
+
+	specs := []Spec{
+		{
+			Name:          "3-inputs-3-outputs-taproot",
+			PSBTString:    "70736274ff0100fd06010100000003866c72cfeef533940eaee49b68778e6223914ea671411ec387bdb61f620889910000000000ffffffff866c72cfeef533940eaee49b68778e6223914ea671411ec387bdb61f620889910100000000ffffffff866c72cfeef533940eaee49b68778e6223914ea671411ec387bdb61f620889910200000000ffffffff03b0040000000000002251205b954b2f91ded08c553551037bc71265a69a7586855ba4fdcf785a2494f0c37f22020000000000002251205b954b2f91ded08c553551037bc71265a69a7586855ba4fdcf785a2494f0c37f4d370f00000000002251205b954b2f91ded08c553551037bc71265a69a7586855ba4fdcf785a2494f0c37f000000000001012b58020000000000002251205b954b2f91ded08c553551037bc71265a69a7586855ba4fdcf785a2494f0c37f0001012b58020000000000002251205b954b2f91ded08c553551037bc71265a69a7586855ba4fdcf785a2494f0c37f0001012bcb3c0f00000000002251205b954b2f91ded08c553551037bc71265a69a7586855ba4fdcf785a2494f0c37f00000000",
+			ExpectedError: nil,
+			ExpectedSize:  312,
+		},
+		{
+			Name:          "mixed-segwit-taproot",
+			PSBTString:    "70736274ff0100fd230202000000061f34960fef4e73c3c4c023f303c16e06f0eebb268bc0d3bac99fa78c031a45b90300000000ffffffff1f34960fef4e73c3c4c023f303c16e06f0eebb268bc0d3bac99fa78c031a45b90400000000ffffffff21c8ec368f2aff1a7baf4964e4070f52e7247ae39edfbda3976f8df4da1b72a00000000000ffffffff969e65b705e3d5071f1743a63381b3aa1ec31e1dbbbd63ab594a19ca399a58af0000000000ffffffffcca5cfd28bd6c54a851d97d029560b3047f7c6482fda7b2f2603d56ade8c95890000000000ffffffff1f34960fef4e73c3c4c023f303c16e06f0eebb268bc0d3bac99fa78c031a45b90500000000ffffffff0908070000000000001600144850d32c3ff585403790507793125d174a5c28e022020000000000001600144850d32c3ff585403790507793125d174a5c28e022020000000000001600144850d32c3ff585403790507793125d174a5c28e0b03600000000000016001459805fc1fdb9f05e190db569987c95c4f9deaa532a680000000000002251203a9ddeb6a2a327fed0f50d18778b28168e3ddb7fdfd4b05f4e438c9174d76a8d58020000000000001600144850d32c3ff585403790507793125d174a5c28e058020000000000001600144850d32c3ff585403790507793125d174a5c28e058020000000000001600144850d32c3ff585403790507793125d174a5c28e0b21f1e00000000001600144850d32c3ff585403790507793125d174a5c28e0000000000001011f58020000000000001600144850d32c3ff585403790507793125d174a5c28e00001011f58020000000000001600144850d32c3ff585403790507793125d174a5c28e00001011f58020000000000001600144850d32c3ff585403790507793125d174a5c28e00001011f220200000000000016001459805fc1fdb9f05e190db569987c95c4f9deaa53010304830000000001012b22020000000000002251203a9ddeb6a2a327fed0f50d18778b28168e3ddb7fdfd4b05f4e438c9174d76a8d010304830000000001011f06432000000000001600144850d32c3ff585403790507793125d174a5c28e000000000000000000000",
+			ExpectedError: nil,
+			ExpectedSize:  699,
+		},
+		{
+			Name:          "segwit-transfer-to-legacy",
+			PSBTString:    "70736274ff010074020000000124ba4becfc732f3b4729784a3dd0cc2494ae890d826377fd98aeb0607feb1ace0100000000ffffffff0210270000000000001976a91422bae94117be666b593916527d55bdaf030d756e88ac25f62e000000000016001476d1e072c9b8a18fa1e4be697c175e0c642026ac000000000001011fc51d2f000000000016001476d1e072c9b8a18fa1e4be697c175e0c642026ac01086b024730440220759df9d109298a1ef69b9faa1786f4118f0d4d63a68cd2061e217b6090573f62022053ffa117fc21e5bf20e7d16bb786de52dc0214c9a21af87b4e92a639ef66e997012103e0cb213a46a68b1f463a4858635ee44694ce4b512788833d629840341b1219c9000000",
+			ExpectedError: nil,
+			ExpectedSize:  143.5,
+		},
+	}
+
+	for _, spec := range specs {
+		t.Run(spec.Name, func(t *testing.T) {
+			p, err := psbtutils.DecodeString(spec.PSBTString)
+			assert.NoError(t, err)
+			size, err := psbtutils.PSBTSize(p)
+			if spec.ExpectedError != nil {
+				assert.ErrorIs(t, err, spec.ExpectedError)
+			} else {
+				assert.Equal(t, spec.ExpectedSize, size)
+			}
+		})
+	}
+}
+
+func TestPredictTxFee(t *testing.T) {
+	type Spec struct {
+		FeeRate      int64
+		InputsCount  int
+		OutputsCount int
+		ExpectedFee  int64
+	}
+
+	specs := []Spec{
+		{
+			FeeRate:      100,
+			InputsCount:  1,
+			OutputsCount: 1,
+			ExpectedFee:  int64(math.Ceil((10.5 + 148 + 43) * 100)),
+		},
+		{
+			FeeRate:      1,
+			InputsCount:  99,
+			OutputsCount: 99,
+			ExpectedFee:  int64(math.Ceil((10.5 + (99 * 148) + (99 * 43)) * 1)),
+		},
+	}
+
+	for _, spec := range specs {
+		t.Run(fmt.Sprintf("feeRate=%d:inputs=%d:outputs=%d", spec.FeeRate, spec.InputsCount, spec.OutputsCount), func(t *testing.T) {
+			fee := psbtutils.PredictTxFee(spec.FeeRate, spec.InputsCount, spec.OutputsCount)
+			assert.Equal(t, spec.ExpectedFee, fee)
+		})
+	}
+}
+
+func TestTxFee(t *testing.T) {
+	type Spec struct {
+		Name          string
+		FeeRate       int64
+		PSBTString    string
+		ExpectedError error
+		ExpectedFee   int64
+	}
+
+	specs := []Spec{
+		{
+			Name:          "3-inputs-3-outputs-taproot",
+			FeeRate:       10,
+			PSBTString:    "70736274ff0100fd06010100000003866c72cfeef533940eaee49b68778e6223914ea671411ec387bdb61f620889910000000000ffffffff866c72cfeef533940eaee49b68778e6223914ea671411ec387bdb61f620889910100000000ffffffff866c72cfeef533940eaee49b68778e6223914ea671411ec387bdb61f620889910200000000ffffffff03b0040000000000002251205b954b2f91ded08c553551037bc71265a69a7586855ba4fdcf785a2494f0c37f22020000000000002251205b954b2f91ded08c553551037bc71265a69a7586855ba4fdcf785a2494f0c37f4d370f00000000002251205b954b2f91ded08c553551037bc71265a69a7586855ba4fdcf785a2494f0c37f000000000001012b58020000000000002251205b954b2f91ded08c553551037bc71265a69a7586855ba4fdcf785a2494f0c37f0001012b58020000000000002251205b954b2f91ded08c553551037bc71265a69a7586855ba4fdcf785a2494f0c37f0001012bcb3c0f00000000002251205b954b2f91ded08c553551037bc71265a69a7586855ba4fdcf785a2494f0c37f00000000",
+			ExpectedError: nil,
+			ExpectedFee:   312 * 10,
+		},
+		{
+			Name:          "mixed-segwit-taproot",
+			FeeRate:       20,
+			PSBTString:    "70736274ff0100fd230202000000061f34960fef4e73c3c4c023f303c16e06f0eebb268bc0d3bac99fa78c031a45b90300000000ffffffff1f34960fef4e73c3c4c023f303c16e06f0eebb268bc0d3bac99fa78c031a45b90400000000ffffffff21c8ec368f2aff1a7baf4964e4070f52e7247ae39edfbda3976f8df4da1b72a00000000000ffffffff969e65b705e3d5071f1743a63381b3aa1ec31e1dbbbd63ab594a19ca399a58af0000000000ffffffffcca5cfd28bd6c54a851d97d029560b3047f7c6482fda7b2f2603d56ade8c95890000000000ffffffff1f34960fef4e73c3c4c023f303c16e06f0eebb268bc0d3bac99fa78c031a45b90500000000ffffffff0908070000000000001600144850d32c3ff585403790507793125d174a5c28e022020000000000001600144850d32c3ff585403790507793125d174a5c28e022020000000000001600144850d32c3ff585403790507793125d174a5c28e0b03600000000000016001459805fc1fdb9f05e190db569987c95c4f9deaa532a680000000000002251203a9ddeb6a2a327fed0f50d18778b28168e3ddb7fdfd4b05f4e438c9174d76a8d58020000000000001600144850d32c3ff585403790507793125d174a5c28e058020000000000001600144850d32c3ff585403790507793125d174a5c28e058020000000000001600144850d32c3ff585403790507793125d174a5c28e0b21f1e00000000001600144850d32c3ff585403790507793125d174a5c28e0000000000001011f58020000000000001600144850d32c3ff585403790507793125d174a5c28e00001011f58020000000000001600144850d32c3ff585403790507793125d174a5c28e00001011f58020000000000001600144850d32c3ff585403790507793125d174a5c28e00001011f220200000000000016001459805fc1fdb9f05e190db569987c95c4f9deaa53010304830000000001012b22020000000000002251203a9ddeb6a2a327fed0f50d18778b28168e3ddb7fdfd4b05f4e438c9174d76a8d010304830000000001011f06432000000000001600144850d32c3ff585403790507793125d174a5c28e000000000000000000000",
+			ExpectedError: nil,
+			ExpectedFee:   699 * 20,
+		},
+		{
+			Name:          "segwit-transfer-to-legacy",
+			FeeRate:       99,
+			PSBTString:    "70736274ff010074020000000124ba4becfc732f3b4729784a3dd0cc2494ae890d826377fd98aeb0607feb1ace0100000000ffffffff0210270000000000001976a91422bae94117be666b593916527d55bdaf030d756e88ac25f62e000000000016001476d1e072c9b8a18fa1e4be697c175e0c642026ac000000000001011fc51d2f000000000016001476d1e072c9b8a18fa1e4be697c175e0c642026ac01086b024730440220759df9d109298a1ef69b9faa1786f4118f0d4d63a68cd2061e217b6090573f62022053ffa117fc21e5bf20e7d16bb786de52dc0214c9a21af87b4e92a639ef66e997012103e0cb213a46a68b1f463a4858635ee44694ce4b512788833d629840341b1219c9000000",
+			ExpectedError: nil,
+			ExpectedFee:   int64(math.Ceil((143.5) * 99)),
+		},
+	}
+
+	for _, spec := range specs {
+		t.Run(spec.Name, func(t *testing.T) {
+			p, err := psbtutils.DecodeString(spec.PSBTString)
+			assert.NoError(t, err)
+			fee, err := psbtutils.TxFee(spec.FeeRate, p)
+			if spec.ExpectedError != nil {
+				assert.ErrorIs(t, err, spec.ExpectedError)
+			} else {
+				assert.Equal(t, spec.ExpectedFee, fee)
+			}
+		})
+	}
+}
--- a/pkg/btcutils/psbtutils/is_ready.go
+++ b/pkg/btcutils/psbtutils/is_ready.go
@@ -0,0 +1,35 @@
+package psbtutils
+
+import (
+	"github.com/btcsuite/btcd/btcutil/psbt"
+	"github.com/btcsuite/btcd/wire"
+	"github.com/cockroachdb/errors"
+	"github.com/samber/lo"
+)
+
+func IsReadyPSBT(pC *psbt.Packet, feeRate int64) (bool, error) {
+	// if input = output + fee then it's ready
+
+	// Calculate tx fee
+	fee, err := TxFee(feeRate, pC)
+	if err != nil {
+		return false, errors.Wrap(err, "calculate fee")
+	}
+
+	// sum total input and output
+	totalInputValue := lo.SumBy(pC.Inputs, func(input psbt.PInput) int64 { return input.WitnessUtxo.Value })
+	totalOutputValue := lo.SumBy(pC.UnsignedTx.TxOut, func(txout *wire.TxOut) int64 { return txout.Value }) + fee
+
+	// it's perfect match
+	if totalInputValue == totalOutputValue {
+		return true, nil
+	}
+
+	// if input is more than output + fee but not more than 1000 satoshi,
+	// then it's ready
+	if totalInputValue > totalOutputValue && totalInputValue-totalOutputValue < 1000 {
+		return true, nil
+	}
+
+	return false, nil
+}
--- a/pkg/btcutils/signature.go
+++ b/pkg/btcutils/signature.go
@@ -0,0 +1,21 @@
+package btcutils
+
+import (
+	"github.com/Cleverse/go-utilities/utils"
+	verifier "github.com/bitonicnl/verify-signed-message/pkg"
+	"github.com/btcsuite/btcd/chaincfg"
+	"github.com/cockroachdb/errors"
+)
+
+func VerifySignature(address string, message string, sigBase64 string, defaultNet ...*chaincfg.Params) error {
+	net := utils.DefaultOptional(defaultNet, &chaincfg.MainNetParams)
+	_, err := verifier.VerifyWithChain(verifier.SignedMessage{
+		Address:   address,
+		Message:   message,
+		Signature: sigBase64,
+	}, net)
+	if err != nil {
+		return errors.WithStack(err)
+	}
+	return nil
+}
--- a/pkg/btcutils/signature_test.go
+++ b/pkg/btcutils/signature_test.go
@@ -0,0 +1,69 @@
+package btcutils
+
+import (
+	"testing"
+
+	"github.com/btcsuite/btcd/chaincfg"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestVerifySignature(t *testing.T) {
+	{
+		message := "Test123"
+		address := "18J72YSM9pKLvyXX1XAjFXA98zeEvxBYmw"
+		signature := "Gzhfsw0ItSrrTCChykFhPujeTyAcvVxiXwywxpHmkwFiKuUR2ETbaoFcocmcSshrtdIjfm8oXlJoTOLosZp3Yc8="
+		network := &chaincfg.MainNetParams
+
+		err := VerifySignature(address, message, signature, network)
+		assert.NoError(t, err)
+	}
+	{
+		address := "tb1qr97cuq4kvq7plfetmxnl6kls46xaka78n2288z"
+		message := "The outage comes at a time when bitcoin has been fast approaching new highs not seen since June 26, 2019."
+		signature := "H/bSByRH7BW1YydfZlEx9x/nt4EAx/4A691CFlK1URbPEU5tJnTIu4emuzkgZFwC0ptvKuCnyBThnyLDCqPqT10="
+		network := &chaincfg.TestNet3Params
+
+		err := VerifySignature(address, message, signature, network)
+		assert.NoError(t, err)
+	}
+	{
+		// Missmatch address
+		address := "tb1qp7y2ywgrv8a4t9h47yphtgj8w759rk6vgd9ran"
+		message := "The outage comes at a time when bitcoin has been fast approaching new highs not seen since June 26, 2019."
+		signature := "H/bSByRH7BW1YydfZlEx9x/nt4EAx/4A691CFlK1URbPEU5tJnTIu4emuzkgZFwC0ptvKuCnyBThnyLDCqPqT10="
+		network := &chaincfg.TestNet3Params
+
+		err := VerifySignature(address, message, signature, network)
+		assert.Error(t, err)
+	}
+	{
+		// Missmatch signature
+		address := "tb1qr97cuq4kvq7plfetmxnl6kls46xaka78n2288z"
+		message := "The outage comes at a time when bitcoin has been fast approaching new highs not seen since June 26, 2019."
+		signature := "Gzhfsw0ItSrrTCChykFhPujeTyAcvVxiXwywxpHmkwFiKuUR2ETbaoFcocmcSshrtdIjfm8oXlJoTOLosZp3Yc8="
+		network := &chaincfg.TestNet3Params
+
+		err := VerifySignature(address, message, signature, network)
+		assert.Error(t, err)
+	}
+	{
+		// Missmatch message
+		address := "tb1qr97cuq4kvq7plfetmxnl6kls46xaka78n2288z"
+		message := "Hello World"
+		signature := "H/bSByRH7BW1YydfZlEx9x/nt4EAx/4A691CFlK1URbPEU5tJnTIu4emuzkgZFwC0ptvKuCnyBThnyLDCqPqT10="
+		network := &chaincfg.TestNet3Params
+
+		err := VerifySignature(address, message, signature, network)
+		assert.Error(t, err)
+	}
+	{
+		// Missmatch network
+		address := "tb1qr97cuq4kvq7plfetmxnl6kls46xaka78n2288z"
+		message := "The outage comes at a time when bitcoin has been fast approaching new highs not seen since June 26, 2019."
+		signature := "H/bSByRH7BW1YydfZlEx9x/nt4EAx/4A691CFlK1URbPEU5tJnTIu4emuzkgZFwC0ptvKuCnyBThnyLDCqPqT10="
+		network := &chaincfg.MainNetParams
+
+		err := VerifySignature(address, message, signature, network)
+		assert.Error(t, err)
+	}
+}
--- a/pkg/btcutils/transaction.go
+++ b/pkg/btcutils/transaction.go
@@ -0,0 +1,10 @@
+package btcutils
+
+const (
+	// TxVersion is the current latest supported transaction version.
+	TxVersion = 2
+
+	// MaxTxInSequenceNum is the maximum sequence number the sequence field
+	// of a transaction input can be.
+	MaxTxInSequenceNum uint32 = 0xffffffff
+)
--- a/pkg/httpclient/httpclient.go
+++ b/pkg/httpclient/httpclient.go
@@ -5,12 +5,11 @@ import (
 	"encoding/json"
 	"log/slog"
 	"net/url"
+	"path"
 	"strings"
 	"time"

-	"github.com/Cleverse/go-utilities/utils"
 	"github.com/cockroachdb/errors"
-	"github.com/gaze-network/indexer-network/common/errs"
 	"github.com/gaze-network/indexer-network/pkg/logger"
 	"github.com/valyala/fasthttp"
 )
@@ -24,13 +23,14 @@ type Config struct {
 }

 type Client struct {
-	baseURL string
+	baseURL *url.URL
 	Config
 }

 func New(baseURL string, config ...Config) (*Client, error) {
-	if _, err := url.Parse(baseURL); err != nil {
-		return nil, errors.Join(errs.InvalidArgument, errors.Wrap(err, "can't parse base url"))
+	parsedBaseURL, err := url.Parse(baseURL)
+	if err != nil {
+		return nil, errors.Wrap(err, "can't parse base url")
 	}
 	var cf Config
 	if len(config) > 0 {
@@ -40,7 +40,7 @@ func New(baseURL string, config ...Config) (*Client, error) {
 		cf.Headers = make(map[string]string)
 	}
 	return &Client{
-		baseURL: baseURL,
+		baseURL: parsedBaseURL,
 		Config:  cf,
 	}, nil
 }
@@ -60,11 +60,21 @@ type HttpResponse struct {
 }

 func (r *HttpResponse) UnmarshalBody(out any) error {
-	err := json.Unmarshal(r.Body(), out)
+	body, err := r.BodyUncompressed()
 	if err != nil {
-		return errors.Wrapf(err, "can't unmarshal json body from %v, %v", r.URL, string(r.Body()))
+		return errors.Wrapf(err, "can't uncompress body from %v", r.URL)
+	}
+	switch strings.ToLower(string(r.Header.ContentType())) {
+	case "application/json", "application/json; charset=utf-8":
+		if err := json.Unmarshal(body, out); err != nil {
+			return errors.Wrapf(err, "can't unmarshal json body from %s, %q", r.URL, string(body))
+		}
+		return nil
+	case "text/plain", "text/plain; charset=utf-8":
+		return errors.Errorf("can't unmarshal plain text %q", string(body))
+	default:
+		return errors.Errorf("unsupported content type: %s, contents: %v", r.Header.ContentType(), string(r.Body()))
 	}
-	return nil
 }

 func (h *Client) request(ctx context.Context, reqOptions RequestOptions) (*HttpResponse, error) {
@@ -77,9 +87,14 @@ func (h *Client) request(ctx context.Context, reqOptions RequestOptions) (*HttpR
 	for k, v := range reqOptions.Header {
 		req.Header.Set(k, v)
 	}
-	parsedUrl := utils.Must(url.Parse(h.baseURL)) // checked in httpclient.New
-	parsedUrl.Path = reqOptions.path
-	parsedUrl.RawQuery = reqOptions.Query.Encode()
+
+	parsedUrl := h.BaseURL()
+	parsedUrl.Path = path.Join(parsedUrl.Path, reqOptions.path)
+	baseQuery := parsedUrl.Query()
+	for k, v := range reqOptions.Query {
+		baseQuery[k] = v
+	}
+	parsedUrl.RawQuery = baseQuery.Encode()

 	// remove %20 from url (empty space)
 	url := strings.TrimSuffix(parsedUrl.String(), "%20")
@@ -111,6 +126,7 @@ func (h *Client) request(ctx context.Context, reqOptions RequestOptions) (*HttpR
 				logger = logger.With(
 					slog.Int("status_code", resp.StatusCode()),
 					slog.String("resp_content_type", string(resp.Header.ContentType())),
+					slog.String("resp_content_encoding", string(resp.Header.ContentEncoding())),
 					slog.Int("resp_content_length", len(resp.Body())),
 				)
 			}
@@ -134,6 +150,12 @@ func (h *Client) request(ctx context.Context, reqOptions RequestOptions) (*HttpR
 	return &httpResponse, nil
 }

+// BaseURL returns the cloned base URL of the client.
+func (h *Client) BaseURL() *url.URL {
+	u := *h.baseURL
+	return &u
+}
+
 func (h *Client) Do(ctx context.Context, method, path string, reqOptions RequestOptions) (*HttpResponse, error) {
 	reqOptions.path = path
 	reqOptions.method = method
--- a/pkg/logger/logger.go
+++ b/pkg/logger/logger.go
@@ -119,10 +119,10 @@ type Config struct {
 	//  - Text (default)
 	//  - JSON
 	//  - GCP: Output format for Stackdriver Logging/Cloud Logging or others GCP services.
-	Output string `mapstructure:"output"`
+	Output string `mapstructure:"output" env:"OUTPUT" envDefault:"text"`

 	// Debug is enabled logger level debug. (default: false)
-	Debug bool `mapstructure:"debug"`
+	Debug bool `mapstructure:"debug" env:"DEBUG" envDefault:"false"`
 }

 var (
--- a/pkg/middleware/errorhandler/errorhandler.go
+++ b/pkg/middleware/errorhandler/errorhandler.go
@@ -10,23 +10,28 @@ import (
 	"github.com/gofiber/fiber/v2"
 )

-func NewHTTPErrorHandler() func(ctx *fiber.Ctx, err error) error {
-	return func(ctx *fiber.Ctx, err error) error {
+// New setup error handler middleware
+func New() fiber.Handler {
+	return func(ctx *fiber.Ctx) error {
+		err := ctx.Next()
+		if err == nil {
+			return nil
+		}
 		if e := new(errs.PublicError); errors.As(err, &e) {
-			return errors.WithStack(ctx.Status(http.StatusBadRequest).JSON(map[string]any{
+			return errors.WithStack(ctx.Status(http.StatusBadRequest).JSON(fiber.Map{
 				"error": e.Message(),
 			}))
 		}
 		if e := new(fiber.Error); errors.As(err, &e) {
-			return errors.WithStack(ctx.Status(e.Code).SendString(e.Error()))
+			return errors.WithStack(ctx.Status(e.Code).JSON(fiber.Map{
+				"error": e.Error(),
+			}))
 		}
-
-		logger.ErrorContext(ctx.UserContext(), "Something went wrong, unhandled api error",
-			slogx.String("event", "api_unhandled_error"),
+		logger.ErrorContext(ctx.UserContext(), "Something went wrong, api error",
+			slogx.String("event", "api_error"),
 			slogx.Error(err),
 		)
-
-		return errors.WithStack(ctx.Status(http.StatusInternalServerError).JSON(map[string]any{
+		return errors.WithStack(ctx.Status(http.StatusInternalServerError).JSON(fiber.Map{
 			"error": "Internal Server Error",
 		}))
 	}
--- a/pkg/middleware/requestlogger/requestlogger.go
+++ b/pkg/middleware/requestlogger/requestlogger.go
@@ -13,10 +13,13 @@ import (
 )

 type Config struct {
-	WithRequestHeader    bool     `env:"REQUEST_HEADER" envDefault:"false" mapstructure:"request_header"`
-	WithRequestQuery     bool     `env:"REQUEST_QUERY" envDefault:"false" mapstructure:"request_query"`
-	Disable              bool     `env:"DISABLE" envDefault:"false" mapstructure:"disable"` // Disable logger level `INFO`
-	HiddenRequestHeaders []string `env:"HIDDEN_REQUEST_HEADERS" mapstructure:"hidden_request_headers"`
+	AllRequestHeaders    bool                   `env:"REQUEST_HEADER" envDefault:"false" mapstructure:"request_header"`   // Log all request headers
+	AllResponseHeaders   bool                   `env:"RESPONSE_HEADER" envDefault:"false" mapstructure:"response_header"` // Log all response headers
+	AllRequestQueries    bool                   `env:"REQUEST_QUERY" envDefault:"false" mapstructure:"request_query"`     // Log all request queries
+	Disable              bool                   `env:"DISABLE" envDefault:"false" mapstructure:"disable"`                 // Disable logger level `INFO`
+	HiddenRequestHeaders []string               `env:"HIDDEN_REQUEST_HEADERS" mapstructure:"hidden_request_headers"`      // Hide specific headers from log
+	WithRequestHeaders   []string               `env:"WITH_REQUEST_HEADERS" mapstructure:"with_request_headers"`          // Add specific headers to log (higher priority than `HiddenRequestHeaders`)
+	With                 map[string]interface{} `env:"WITH" mapstructure:"with"`                                          // Additional fields to log
 }

 // New setup request context and information
@@ -25,6 +28,10 @@ func New(config Config) fiber.Handler {
 	for _, header := range config.HiddenRequestHeaders {
 		hiddenRequestHeaders[strings.TrimSpace(strings.ToLower(header))] = struct{}{}
 	}
+	withRequestHeaders := make(map[string]struct{}, len(config.WithRequestHeaders))
+	for _, header := range config.WithRequestHeaders {
+		withRequestHeaders[strings.TrimSpace(strings.ToLower(header))] = struct{}{}
+	}
 	return func(c *fiber.Ctx) error {
 		start := time.Now()

@@ -41,6 +48,11 @@ func New(config Config) fiber.Handler {
 			slog.String("latencyHuman", latency.String()),
 		}

+		// add `with` fields
+		for k, v := range config.With {
+			baseAttrs = append(baseAttrs, slog.Any(k, v))
+		}
+
 		// prep request attributes
 		requestAttributes := []slog.Attr{
 			slog.Time("time", start),
@@ -53,6 +65,7 @@ func New(config Config) fiber.Handler {
 			slog.Any("x-forwarded-for", c.IPs()),
 			slog.String("user-agent", string(c.Context().UserAgent())),
 			slog.Any("params", c.AllParams()),
+			slog.Any("query", c.Queries()),
 			slog.Int("length", len((c.Body()))),
 		}

@@ -63,23 +76,64 @@ func New(config Config) fiber.Handler {
 			slog.Int("length", len(c.Response().Body())),
 		}

-		// request query
-		if config.WithRequestQuery {
-			requestAttributes = append(requestAttributes, slog.String("query", string(c.Request().URI().QueryString())))
+		// request queries
+		if config.AllRequestQueries {
+			args := c.Request().URI().QueryArgs()
+			logAttrs := make([]any, 0, args.Len())
+			args.VisitAll(func(k, v []byte) {
+				logAttrs = append(logAttrs, slog.Any(string(k), string(v)))
+			})
+			requestAttributes = append(requestAttributes, slog.Group("queries", logAttrs...))
 		}

 		// request headers
-		if config.WithRequestHeader {
+		if config.AllRequestHeaders || len(config.WithRequestHeaders) > 0 {
 			kv := []any{}

 			for k, v := range c.GetReqHeaders() {
+				h := strings.ToLower(k)
+
+				// add headers for WithRequestHeaders
+				if _, found := withRequestHeaders[h]; found {
+					goto add
+				}
+
+				// skip hidden headers
+				if _, found := hiddenRequestHeaders[h]; found {
+					continue
+				}
+
+				// skip if not AllRequestHeaders
+				if !config.AllRequestHeaders {
+					continue
+				}
+
+			add:
+				val := any(v)
+				if len(v) == 1 {
+					val = v[0]
+				}
+				kv = append(kv, slog.Any(k, val))
+			}
+
+			requestAttributes = append(requestAttributes, slog.Group("headers", kv...))
+		}
+
+		if config.AllResponseHeaders {
+			kv := []any{}
+			for k, v := range c.GetRespHeaders() {
+				// skip hidden headers
 				if _, found := hiddenRequestHeaders[strings.ToLower(k)]; found {
 					continue
 				}
-				kv = append(kv, slog.Any(k, v))
-			}

-			requestAttributes = append(requestAttributes, slog.Group("header", kv...))
+				val := any(v)
+				if len(v) == 1 {
+					val = v[0]
+				}
+				kv = append(kv, slog.Any(k, val))
+			}
+			responseAttributes = append(responseAttributes, slog.Group("headers", kv...))
 		}

 		level := slog.LevelInfo
Author	SHA1	Message	Date
gazenw	1967895d6d	Merge pull request #41 from gaze-network/develop Release v0.3.0	2024-07-25 15:07:51 +07:00
gazenw	7dcbd082ee	feat: add Runes API pagination (#36 ) * feat: implement pagination on get balance, get holders * feat: paginate get transactions * fix: remove debug * feat: implement pagination in get utxos * feat: sort response in get holders * feat: cap batch query * feat: add default limits to all endpoints * chore: rename endpoint funcs * fix: parse rune name spacers * chore: use compare.Cmp * feat: handle not found errors on all usecase	2024-07-23 15:46:45 +07:00
gazenw	880f4b2e6a	fix: handle case where input rune id is not found (#37 )	2024-07-15 18:32:28 +07:00
Gaze	3f727dc11b	Merge remote-tracking branch 'origin/main' into develop	2024-07-15 16:33:56 +07:00
Planxnx	60717ecc65	feat(requestlogger): add response headers	2024-07-12 00:18:15 +07:00
Planxnx	6998adedb0	fix(requestlogger): logging all request headers	2024-07-11 23:53:27 +07:00
Thanee Charattrakool	add0a541b5	feat: Request Logger fields (#35 ) * feat: add with request headers config * feat: add with fields config * feat: format request queries	2024-07-11 23:41:18 +07:00
gazenw	dad02bf61a	Merge pull request #34 from gaze-network/develop feat: release v0.2.7	2024-07-09 16:15:35 +07:00
Gaze	694baef0aa	chore: golangci-lint	2024-07-09 15:48:09 +07:00
gazenw	47119c3220	feat: remove unnecessary verbose query (#33 )	2024-07-09 15:44:14 +07:00
gazenw	6203b104db	Merge pull request #32 from gaze-network/develop feat: release v0.2.5	2024-07-08 14:50:40 +07:00
gazenw	b24f27ec9a	fix: incorrect condition for finding output destinations (#31 )	2024-07-08 14:32:58 +07:00
Planxnx	90f1fd0a6c	Merge branch 'fix/invalid-httpclient-path'	2024-07-04 15:39:17 +07:00
Planxnx	aace33b382	fix(httpclient): support base url query params	2024-07-04 15:39:04 +07:00
Gaze	a663f909fa	Merge remote-tracking branch 'origin/main' into develop	2024-07-04 12:46:51 +07:00
Thanee Charattrakool	0263ec5622	Merge pull request #30 from gaze-network/fix/invalid-httpclient-path	2024-07-04 04:12:19 +07:00
Planxnx	8760baf42b	chore: remive unused comment	2024-07-04 00:03:36 +07:00
Planxnx	5aca9f7f19	perf(httpclient): reduce base url parsing operation	2024-07-03 23:58:20 +07:00
Planxnx	07aa84019f	fix(httpclient): can't support baseURL path	2024-07-03 23:57:40 +07:00
Thanee Charattrakool	a5fc803371	Merge pull request #29 from gaze-network/develop feat: release v0.2.4	2024-07-02 15:57:44 +07:00
Planxnx	72ca151fd3	feat(httpclient): support content-encoding	2024-07-02 15:53:18 +07:00
Gaze	53a4d1a4c3	Merge branch 'main' into develop	2024-06-30 21:04:08 +07:00
Gaze	3322f4a034	ci: update action file name	2024-06-30 21:03:57 +07:00
Planxnx	dcb220bddb	Merge branch 'main' into develop	2024-06-30 20:17:13 +07:00
gazenw	b6ff7e41bd	docs: update README.md	2024-06-30 20:12:44 +07:00
gazenw	7cb717af11	feat(runes): get txs by block range (#28 ) * feat(runes): get txs by block range * feat(runes): validate block range * perf(runes): limit 10k txs --------- Co-authored-by: Gaze <gazenw@users.noreply.github.com>	2024-06-30 18:45:23 +07:00
Gaze	0d1ae0ef5e	Merge branch 'main' into develop	2024-06-27 00:12:13 +07:00
Thanee Charattrakool	81ba7792ea	fix: create error handler middleware (#27 )	2024-06-27 00:11:22 +07:00
Gaze	b5851a39ab	Merge branch 'main' into develop	2024-06-22 21:15:06 +07:00
Gaze	b44fb870a3	feat: add query params to req logger	2024-06-22 21:00:02 +07:00
Gaze	373ea50319	feat(logger): support env config	2024-06-20 18:52:56 +07:00
Gaze	a1d7524615	feat(btcutils): make btcutils.Address comparable support	2024-06-14 19:38:01 +07:00
Gaze	415a476478	Merge branch 'main' into develop	2024-06-14 16:55:39 +07:00
Gaze	f63505e173	feat(btcutils): use chain params instead common.network	2024-06-14 16:55:28 +07:00
Gaze	65a69ddb68	Merge remote-tracking branch 'origin/main' into develop	2024-06-14 16:48:48 +07:00
Thanee Charattrakool	4f5d1f077b	feat(btcutils): add bitcoin utility functions (#26 ) * feat(btcutils): add bitcoin utility functions * feat(btcutils): add bitcoin signature verification	2024-06-14 16:48:22 +07:00