Merge pull request #197 from kpitapeersyst/xrpl/feat/contains-flag-util

feat(xrpl): add contains flag utility

Author: GuillemGarciaDev

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+#### xrpl
+
+- Added `flag` package with `Contains` utility function to check if a flag is fully set within a combined flag value.
+
 ### Fixed
 
 #### xrpl

docs/docs/xrpl/flag.md

@@ -0,0 +1,67 @@
+# flag
+
+## Overview
+
+The `flag` package provides utility functions for working with bitwise flags in XRPL.
+
+- `Contains`: Checks whether a flag is fully set within a combined flag value. Useful for inspecting transaction or ledger object flags.
+
+## Usage
+
+To import the package, you can use the following code:
+
+```go
+import "github.com/Peersyst/xrpl-go/xrpl/flag"
+```
+
+## API
+
+### Contains
+
+```go
+func Contains(currentFlag uint32, flag uint32) bool
+```
+
+Returns `true` if all bits of `flag` are set in `currentFlag` (`(currentFlag & flag) == flag`). Returns `false` if any bit of `flag` is missing in `currentFlag`, or if `flag` is `0`.
+
+:::warning
+
+The comparison is based on the flag value as a `uint32`. Different contexts may use the same numeric values (e.g. a transaction flag and a ledger-state flag), so a match only indicates the bit is set — not that it belongs to a specific context. Always pair `Contains` with the flag constant that matches the context you are checking.
+
+:::
+
+### Example
+
+```go
+package main
+
+import (
+	"fmt"
+
+	"github.com/Peersyst/xrpl-go/xrpl/flag"
+	"github.com/Peersyst/xrpl-go/xrpl/transaction"
+)
+
+func main() {
+	offer := transaction.OfferCreate{
+		BaseTx: transaction.BaseTx{
+			Account: "rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe",
+		},
+		TakerGets: nil,
+		TakerPays: nil,
+	}
+
+	// Set the sell flag on the offer
+	offer.SetSellFlag()
+
+	// Check whether the sell flag is set
+	if flag.Contains(offer.Flags, transaction.TfSell) {
+		fmt.Println("Offer is a sell offer")
+	}
+
+	// Check whether the fill-or-kill flag is set (it is not)
+	if !flag.Contains(offer.Flags, transaction.TfFillOrKill) {
+		fmt.Println("Offer is not fill-or-kill")
+	}
+}
+```

examples/mptoken/rpc/main.go

@@ -72,7 +72,7 @@ func main() {
 		MaximumAmount:   &amount,
 		MPTokenMetadata: types.MPTokenMetadata("464F4F"), // "FOO" in hex
 	}
-	// Since TransferFee is provided, enable the tfMPTCanTransfer flag.
+	// Since TransferFee is provided, enable the TfMPTCanTransfer flag.
 	issuanceTx.SetMPTCanTransferFlag()
 
 	// Flatten, autofill, sign, and submit the transaction.

examples/mptoken/ws/main.go

@@ -87,7 +87,7 @@ func main() {
 		MaximumAmount:   &amount,
 		MPTokenMetadata: types.MPTokenMetadata("464F4F"), // "FOO" in hex
 	}
-	// Since TransferFee is provided, enable the tfMPTCanTransfer flag.
+	// Since TransferFee is provided, enable the TfMPTCanTransfer flag.
 	issuanceTx.SetMPTCanTransferFlag()
 
 	// Flatten, autofill, sign, and submit the transaction.

xrpl/flag/flag.go

@@ -0,0 +1,10 @@
+// Package flag provides utility functions for working with bitwise flags.
+package flag
+
+// Contains checks if all bits of flag are present in currentFlag.
+// Returns false if flag is 0.
+// Note: It should be taken into account that the comparison is based on the flag value as a uint32.
+// Different contexts may use same values, and they will return ok as the value matches.
+func Contains(currentFlag, flag uint32) bool {
+	return flag != 0 && (currentFlag&flag) == flag
+}

xrpl/flag/flag_test.go

@@ -0,0 +1,65 @@
+package flag
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+const (
+	dummyFlagA = 262144
+	dummyFlagB = 131072
+	dummyFlagC = 65536
+)
+
+func TestFlag_Contains(t *testing.T) {
+	testCases := []struct {
+		name        string
+		currentFlag uint32
+		flag        uint32
+		expected    bool
+	}{
+		{
+			name:        "pass - same flag",
+			currentFlag: dummyFlagA,
+			flag:        dummyFlagA,
+			expected:    true,
+		},
+		{
+			name:        "pass - containing flag",
+			currentFlag: dummyFlagA | dummyFlagB,
+			flag:        dummyFlagA,
+			expected:    true,
+		},
+		{
+			name:        "pass - not containing flag",
+			currentFlag: dummyFlagA | dummyFlagB,
+			flag:        dummyFlagC,
+			expected:    false,
+		},
+		{
+			name:        "pass - zero flag",
+			currentFlag: dummyFlagA,
+			flag:        0,
+			expected:    false,
+		},
+		{
+			name:        "pass - zero current flag",
+			currentFlag: 0,
+			flag:        0,
+			expected:    false,
+		},
+		{
+			name:        "pass - partial overlap multi-bit flag",
+			currentFlag: dummyFlagA,
+			flag:        dummyFlagA | dummyFlagB,
+			expected:    false,
+		},
+	}
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			actual := Contains(tc.currentFlag, tc.flag)
+			assert.Equal(t, tc.expected, actual)
+		})
+	}
+}

xrpl/ledger-entry-types/account_root.go

@@ -6,36 +6,36 @@ import (
 )
 
 const (
-	// Enable Clawback for this account. (Requires the Clawback amendment.)
-	lsfAllowTrustLineClawback uint32 = 0x80000000
-	// Allow IOUs to be used as escrow amounts for an issuer
-	lsfAllowTrustLineLocking uint32 = 0x40000000
-	// Enable rippling on this addresses's trust lines by default. Required for issuing addresses; discouraged for others.
-	lsfDefaultRipple uint32 = 0x00800000
-	// This account has DepositAuth enabled, meaning it can only receive funds from transactions it sends, and from preauthorized accounts. (Added by the DepositAuth amendment)
-	lsfDepositAuth uint32 = 0x01000000
-	// Disallows use of the master key to sign transactions for this account.
-	lsfDisableMaster uint32 = 0x00100000
-	// This account blocks incoming Checks. (Added by the DisallowIncoming amendment.)
-	lsfDisallowIncomingCheck uint32 = 0x08000000
-	// This account blocks incoming NFTokenOffers. (Added by the DisallowIncoming amendment.)
-	lsfDisallowIncomingNFTokenOffer uint32 = 0x04000000
-	// This account blocks incoming Payment Channels. (Added by the DisallowIncoming amendment.)
-	lsfDisallowIncomingPayChan uint32 = 0x10000000
-	// This account blocks incoming trust lines. (Added by the DisallowIncoming amendment.)
-	lsfDisallowIncomingTrustline uint32 = 0x20000000
-	// Client applications should not send XRP to this account. (Advisory; not enforced by the protocol.)
-	lsfDisallowXRP uint32 = 0x00080000
-	// All assets issued by this account are frozen.
-	lsfGlobalFreeze uint32 = 0x00400000
-	// This account cannot freeze trust lines connected to it. Once enabled, cannot be disabled.
-	lsfNoFreeze uint32 = 0x00200000
-	// This account has used its free SetRegularKey transaction.
-	lsfPasswordSpent uint32 = 0x00010000
-	// This account must individually approve other users for those users to hold this account's tokens.
-	lsfRequireAuth uint32 = 0x00040000
-	// Requires incoming payments to specify a Destination Tag.
-	lsfRequireDestTag uint32 = 0x00020000
+	// LsfAllowTrustLineClawback enables Clawback for this account. (Requires the Clawback amendment.)
+	LsfAllowTrustLineClawback uint32 = 0x80000000
+	// LsfAllowTrustLineLocking allows IOUs to be used as escrow amounts for an issuer
+	LsfAllowTrustLineLocking uint32 = 0x40000000
+	// LsfDefaultRipple enables rippling on this addresses's trust lines by default. Required for issuing addresses; discouraged for others.
+	LsfDefaultRipple uint32 = 0x00800000
+	// LsfDepositAuth this account has DepositAuth enabled, meaning it can only receive funds from transactions it sends, and from preauthorized accounts. (Added by the DepositAuth amendment)
+	LsfDepositAuth uint32 = 0x01000000
+	// LsfDisableMaster disallows use of the master key to sign transactions for this account.
+	LsfDisableMaster uint32 = 0x00100000
+	// LsfDisallowIncomingCheck this account blocks incoming Checks. (Added by the DisallowIncoming amendment.)
+	LsfDisallowIncomingCheck uint32 = 0x08000000
+	// LsfDisallowIncomingNFTokenOffer this account blocks incoming NFTokenOffers. (Added by the DisallowIncoming amendment.)
+	LsfDisallowIncomingNFTokenOffer uint32 = 0x04000000
+	// LsfDisallowIncomingPayChan this account blocks incoming Payment Channels. (Added by the DisallowIncoming amendment.)
+	LsfDisallowIncomingPayChan uint32 = 0x10000000
+	// LsfDisallowIncomingTrustline this account blocks incoming trust lines. (Added by the DisallowIncoming amendment.)
+	LsfDisallowIncomingTrustline uint32 = 0x20000000
+	// LsfDisallowXRP client applications should not send XRP to this account. (Advisory; not enforced by the protocol.)
+	LsfDisallowXRP uint32 = 0x00080000
+	// LsfGlobalFreeze all assets issued by this account are frozen.
+	LsfGlobalFreeze uint32 = 0x00400000
+	// LsfNoFreeze this account cannot freeze trust lines connected to it. Once enabled, cannot be disabled.
+	LsfNoFreeze uint32 = 0x00200000
+	// LsfPasswordSpent this account has used its free SetRegularKey transaction.
+	LsfPasswordSpent uint32 = 0x00010000
+	// LsfRequireAuth this account must individually approve other users for those users to hold this account's tokens.
+	LsfRequireAuth uint32 = 0x00040000
+	// LsfRequireDestTag requires incoming payments to specify a Destination Tag.
+	LsfRequireDestTag uint32 = 0x00020000
 )
 
 // AccountRoot ledger entry type describes a single account, its settings, and XRP balance.
@@ -73,7 +73,7 @@ type AccountRoot struct {
 	Account types.Address
 	// The identifying hash of the transaction most recently sent by this account.
 	// This field must be enabled to use the AccountTxnID transaction field.
-	// To enable it, send an AccountSet transaction with the asfAccountTxnID flag enabled.
+	// To enable it, send an AccountSet transaction with the AsfAccountTxnID flag enabled.
 	AccountTxnID types.Hash256 `json:",omitempty"`
 	// (Added by the AMM amendment) The ledger entry ID of the corresponding AMM ledger entry.
 	// Set during account creation; cannot be modified. If present, indicates that this is a
@@ -135,75 +135,75 @@ func (*AccountRoot) EntryType() EntryType {
 
 // SetLsfAllowTrustLineClawback sets the AllowTrustLineClawback flag.
 func (a *AccountRoot) SetLsfAllowTrustLineClawback() {
-	a.Flags |= lsfAllowTrustLineClawback
+	a.Flags |= LsfAllowTrustLineClawback
 }
 
 // SetLsfAllowTrustLineLocking sets the AllowTrustLineLocking flag.
 func (a *AccountRoot) SetLsfAllowTrustLineLocking() {
-	a.Flags |= lsfAllowTrustLineLocking
+	a.Flags |= LsfAllowTrustLineLocking
 }
 
 // SetLsfDefaultRipple sets the DefaultRipple flag.
 func (a *AccountRoot) SetLsfDefaultRipple() {
-	a.Flags |= lsfDefaultRipple
+	a.Flags |= LsfDefaultRipple
 }
 
 // SetLsfDepositAuth sets the DepositAuth flag.
 func (a *AccountRoot) SetLsfDepositAuth() {
-	a.Flags |= lsfDepositAuth
+	a.Flags |= LsfDepositAuth
 }
 
 // SetLsfDisableMaster sets the DisableMaster flag.
 func (a *AccountRoot) SetLsfDisableMaster() {
-	a.Flags |= lsfDisableMaster
+	a.Flags |= LsfDisableMaster
 }
 
 // SetLsfDisallowIncomingCheck sets the DisallowIncomingCheck flag.
 func (a *AccountRoot) SetLsfDisallowIncomingCheck() {
-	a.Flags |= lsfDisallowIncomingCheck
+	a.Flags |= LsfDisallowIncomingCheck
 }
 
 // SetLsfDisallowIncomingNFTokenOffer sets the DisallowIncomingNFTokenOffer flag.
 func (a *AccountRoot) SetLsfDisallowIncomingNFTokenOffer() {
-	a.Flags |= lsfDisallowIncomingNFTokenOffer
+	a.Flags |= LsfDisallowIncomingNFTokenOffer
 }
 
 // SetLsfDisallowIncomingPayChan sets the DisallowIncomingPayChan flag.
 func (a *AccountRoot) SetLsfDisallowIncomingPayChan() {
-	a.Flags |= lsfDisallowIncomingPayChan
+	a.Flags |= LsfDisallowIncomingPayChan
 }
 
 // SetLsfDisallowIncomingTrustline sets the DisallowIncomingTrustline flag.
 func (a *AccountRoot) SetLsfDisallowIncomingTrustline() {
-	a.Flags |= lsfDisallowIncomingTrustline
+	a.Flags |= LsfDisallowIncomingTrustline
 }
 
 // SetLsfDisallowXRP sets the DisallowXRP flag.
 func (a *AccountRoot) SetLsfDisallowXRP() {
-	a.Flags |= lsfDisallowXRP
+	a.Flags |= LsfDisallowXRP
 }
 
 // SetLsfGlobalFreeze sets the GlobalFreeze flag.
 func (a *AccountRoot) SetLsfGlobalFreeze() {
-	a.Flags |= lsfGlobalFreeze
+	a.Flags |= LsfGlobalFreeze
 }
 
 // SetLsfNoFreeze sets the NoFreeze flag.
 func (a *AccountRoot) SetLsfNoFreeze() {
-	a.Flags |= lsfNoFreeze
+	a.Flags |= LsfNoFreeze
 }
 
 // SetLsfPasswordSpent sets the PasswordSpent flag.
 func (a *AccountRoot) SetLsfPasswordSpent() {
-	a.Flags |= lsfPasswordSpent
+	a.Flags |= LsfPasswordSpent
 }
 
 // SetLsfRequireAuth sets the RequireAuth flag.
 func (a *AccountRoot) SetLsfRequireAuth() {
-	a.Flags |= lsfRequireAuth
+	a.Flags |= LsfRequireAuth
 }
 
 // SetLsfRequireDestTag sets the RequireDestTag flag.
 func (a *AccountRoot) SetLsfRequireDestTag() {
-	a.Flags |= lsfRequireDestTag
+	a.Flags |= LsfRequireDestTag
 }