bind

package
v0.0.0-...-50f1747 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 29, 2026 License: MIT Imports: 31 Imported by: 29

Documentation

Index

Constants

View Source 
const (
	AddressType = "address"

	// BCS data length constants
	U8Len      = 1
	U16Len     = 2
	U32Len     = 4
	U64Len     = 8
	U128Len    = 16
	U256Len    = 32
	AddressLen = 32
)
View Source 
const (
	HashingIntentScopeChildObjectID = 0xf0
	SuiFrameworkAddress             = "0x2"
)
View Source 
const (
	MaxUint8Value     = 255
	MaxUint16Value    = 65535
	U128ByteSize      = 16
	U256ByteSize      = 32
	DecimalBase       = 10
	HexCharPairLength = 2
)

Constants for magic numbers

View Source 
const (
	// DefaultGasBudget is the default gas budget for transactions
	DefaultGasBudget uint64 = 10_000_000_000
)

Variables

View Source 
var (
	// WaitForTxIndexedTimeout bounds the total time SignAndSendTx will poll for a
	// successfully-submitted transaction to become visible on the fullnode's JSON-RPC
	// view (i.e. queryable via sui_getTransactionBlock). This is an additional wall
	// clock cost on top of the transaction's own execution time, paid only when the
	// caller sets CallOpts.WaitForExecution = true.
	WaitForTxIndexedTimeout = 30 * time.Second

	// WaitForTxIndexedInitialBackoff is the first delay between poll attempts; it
	// doubles on each failure up to WaitForTxIndexedMaxBackoff.
	WaitForTxIndexedInitialBackoff = 100 * time.Millisecond

	// WaitForTxIndexedMaxBackoff caps the poll interval so steady-state polling does
	// not add unbounded latency for slow-indexing fullnodes.
	WaitForTxIndexedMaxBackoff = 1 * time.Second
)

Polling parameters for waitForTransactionIndexed. Exposed as package-level vars so callers / tests can tune them without changing the SignAndSendTx signature.

View Source 
var ErrTxIndexingTimeout = errors.New("tx submitted but fullnode indexing wait timed out")

ErrTxIndexingTimeout is returned by SignAndSendTx when the transaction was accepted by validators (effects certified) but the fullnode JSON-RPC did not surface the tx within WaitForTxIndexedTimeout. The caller can distinguish this from a real tx failure (the tx is fine; just not yet visible for reads).

Functions

func AppendToEphemeralPubFile 

func AppendToEphemeralPubFile(filePath, buildEnv, chainID string, entry EphemeralPubEntry) error

AppendToEphemeralPubFile adds a new entry to an existing ephemeral pub file If the file doesn't exist, it creates a new one

func ClearTestModifier 

func ClearTestModifier()

ClearTestModifier removes the test modifier

func ComputeDigestForModulesAndDeps 

func ComputeDigestForModulesAndDeps(modules [][]byte, objectIDs [][]byte) [32]byte

func ConvertToCallArg 

func ConvertToCallArg(typeName string, value any) (*transaction.CallArg, error)

ConvertToCallArg converts a Go value to a CallArg for use in PTB

func DecodeDevInspectResults 

func DecodeDevInspectResults(rawResults json.RawMessage, returnTypes []string, resolver *TypeResolver) ([]any, error)

func DecodeU128Value 

func DecodeU128Value(bcsBytes [16]byte) (*big.Int, error)

DecodeU128Value decodes a 16-byte array to *big.Int for u128 values

func DecodeU256Value 

func DecodeU256Value(bcsBytes [32]byte) (*big.Int, error)

DecodeU256Value decodes a 32-byte array to *big.Int for u256 values

func DeriveObjectIDWithVectorU8Key 

func DeriveObjectIDWithVectorU8Key(parentAddress string, keyBytes []byte) (string, error)

DeriveObjectIDWithVectorU8Key constructs the BCS bytes for DerivedObjectKey<vector<u8>> TypeTag. keyBytes should be the raw vector<u8> value - this function will BCS-serialize it.

func DeserializeBCS 

func DeserializeBCS(data []byte, moveTypes []string) ([]any, error)

DeserializeBCS consumes a slice of bytes containing multiple BCS-encoded values and decodes them according to the provided Move types. TODO: this function should also serve extractBCSBytes, but currently getElementType handles objects as their ID (32-byte address)

func DevInspectPTB 

func DevInspectPTB(ctx context.Context, signerAddress string, client sui.ISuiAPI, ptb *transaction.Transaction) (*models.SuiTransactionBlockResponse, error)

DevInspectPTB executes a PTB using DevInspect

func DevInspectTx 

func DevInspectTx(ctx context.Context, signerAddress string, client sui.ISuiAPI, txBytes []byte) (*models.SuiTransactionBlockResponse, error)

func EnsureEnvironmentInMoveToml 

func EnsureEnvironmentInMoveToml(packageDir, environment, chainID string) error

EnsureEnvironmentInMoveToml ensures the [environments] section exists in Move.toml with the specified environment and chain ID

func ExecutePTB 

func ExecutePTB(ctx context.Context, opts *CallOpts, client sui.ISuiAPI, ptb *transaction.Transaction) (*models.SuiTransactionBlockResponse, error)

func FetchDefaultGasCoinRef 

func FetchDefaultGasCoinRef(ctx context.Context, client sui.ISuiAPI, address string) (*models.SuiObjectRef, error)

Fetches every coin owned by the address. Looks for a SUI object, returns the first it finds

func FindCoinObjectIdFromTx 

func FindCoinObjectIdFromTx(tx models.SuiTransactionBlockResponse, coinType string) (string, error)

FindCoinObjectIdFromTx finds a coin object ID from a transaction response by looking for created objects of type Coin<T>

func FindObjectIdFromPublishTx 

func FindObjectIdFromPublishTx(tx models.SuiTransactionBlockResponse, module, object string) (string, error)

func FindPackageIdFromPublishTx 

func FindPackageIdFromPublishTx(tx models.SuiTransactionBlockResponse) (string, error)

func GetCustomValueFromObjectData 

func GetCustomValueFromObjectData[T any](resp *models.SuiObjectResponse, target *T) error

Decodes "value" field into a user provided pointer of any type.

func GetFailedTxError 

func GetFailedTxError(tx *models.SuiTransactionBlockResponse) error

func GetObjectRef 

func GetObjectRef(ctx context.Context, client sui.ISuiAPI, objectID string) (*models.SuiObjectRef, error)

func IsGenericType 

func IsGenericType(moveType string) bool

IsGenericType checks if a type contains generic parameters

func IsSuiAddress 

func IsSuiAddress(addr string) bool

IsSuiAddress returns true if addr is a valid Sui address/ObjectID. It is an improvement over the sui-go-sdk's IsValidSuiAddress function.

func ReadObject 

func ReadObject(ctx context.Context, objectId string, client sui.ISuiAPI) (*models.SuiObjectResponse, error)

func RegisterStructDecoder 

func RegisterStructDecoder(moveType string, decoder StructDecoder)

func RemovePublishedTOML 

func RemovePublishedTOML(packageDir string) error

RemovePublishedTOML removes the Published.toml file from a package directory This is useful when cleaning up temporary workspaces

func SetTestModifier 

func SetTestModifier(modifier SourceModifier)

SetTestModifier sets a source modifier for the next compilation (test only)

func SignAndSendTx 

func SignAndSendTx(ctx context.Context, signer bindutils.SuiSigner, client sui.ISuiAPI, txBytes []byte, waitForExecution bool) (*models.SuiTransactionBlockResponse, error)

func ToSuiAddress 

func ToSuiAddress(address string) (string, error)

ToSuiAddress normalizes and validates a Sui address

func ToSuiObjectRef 

func ToSuiObjectRef(ctx context.Context, client sui.ISuiAPI, objectId string, address string) (*models.SuiObjectRef, error)

func UpdatePublishedTOMLForUpgrade 

func UpdatePublishedTOMLForUpgrade(packageDir, environment, chainID, newPublishedAt, originalID string, newVersion int, upgradeCap string) error

UpdatePublishedTOMLForUpgrade updates an existing Published.toml file for a package upgrade. This updates the published-at address and increments the version.

func WaitForTransactionIndexed 

func WaitForTransactionIndexed(ctx context.Context, client SuiTransactionBlockGetter, digest string) error

WaitForTransactionIndexed polls sui_getTransactionBlock until the fullnode surfaces the given digest, providing the read-after-write consistency that WaitForLocalExecution used to give before being silently disabled in JSON-RPC (Sui >= v1.33). Without this, a tight "tx A -> tx B referencing objects mutated by tx A" sequence can race with the fullnode's indexer and have tx B rejected pre- consensus with "Object ... Version ... is not available for consumption" because the local view of owned-object versions (notably the default gas coin) is stale.

The poll uses exponential backoff between WaitForTxIndexedInitialBackoff and WaitForTxIndexedMaxBackoff, bounded by WaitForTxIndexedTimeout.

Relayer and other packages that execute with WaitForEffectsCert but still need the same consistency should call this after a successful execute when they would have previously used WaitForLocalExecution.

func WriteEphemeralPubFile 

func WriteEphemeralPubFile(filePath, buildEnv, chainID string, entries []EphemeralPubEntry) error

WriteEphemeralPubFile writes an ephemeral publication file (Pub.<env>.toml) for test publishing. This file tracks publications of the package and its dependencies for ephemeral environments.

Parameters:

  • filePath: The full path to the ephemeral pub file
  • buildEnv: The build environment (e.g., "testnet", "mainnet")
  • chainID: The actual chain ID of the network being published to
  • entries: List of published package entries

func WritePublishedTOML 

func WritePublishedTOML(packageDir, environment, chainID, publishedAt, originalID string, version int) error

WritePublishedTOML writes a Published.toml file for a package at the given directory. This is used to make a dependency resolvable when building packages that depend on it.

Parameters:

  • packageDir: The directory containing the package (where Published.toml will be written)
  • environment: The environment name (e.g., "testnet", "mainnet", "local")
  • chainID: The chain identifier (first 8 chars of chain ID hash)
  • publishedAt: The on-chain address where the package is published
  • originalID: The original package ID (for v1, same as publishedAt)
  • version: The package version number

Types

type ArgumentRef 

type ArgumentRef struct {
	Result *uint16 `json:"Result,omitempty"`
	Input  *uint16 `json:"Input,omitempty"`
}

ArgumentRef — small helper for fields like {"Result": 0}

type BoundContract 

type BoundContract struct {
	// contains filtered or unexported fields
}

func NewBoundContract 

func NewBoundContract(packageID string, packageName, moduleName string, client sui.ISuiAPI) (*BoundContract, error)

func (*BoundContract) AppendPTB 

func (c *BoundContract) AppendPTB(ctx context.Context, opts *CallOpts, ptb *transaction.Transaction, encoded *EncodedCall) (*transaction.Argument, error)

AppendPTB adds an EncodedCall to an existing PTB and returns the result argument

func (*BoundContract) Call 

func (c *BoundContract) Call(ctx context.Context, opts *CallOpts, encoded *EncodedCall) ([]any, error)

TODO: dedupe transaction argument generation code from ExecuteTransaction

func (*BoundContract) EncodeCallArgs 

func (c *BoundContract) EncodeCallArgs(function string, typeArgs []string, paramTypes []string, paramValues []any) (*EncodedCall, error)

EncodeCallArgs encodes function parameters to CallArgs for use in PTB

func (*BoundContract) EncodeCallArgsWithGenerics 

func (c *BoundContract) EncodeCallArgsWithGenerics(function string, typeArgs []string, typeParams []string, paramTypes []string, paramValues []any, returnTypes []string) (*EncodedCall, error)

EncodeCallArgsWithGenerics encodes function parameters with full generic type information

func (*BoundContract) EncodeCallArgsWithReturnTypes 

func (c *BoundContract) EncodeCallArgsWithReturnTypes(function string, typeArgs []string, paramTypes []string, paramValues []any, returnTypes []string) (*EncodedCall, error)

EncodeCallArgsWithReturnTypes encodes function parameters to CallArgs for use in PTB with return type information

func (*BoundContract) ExecuteTransaction 

func (c *BoundContract) ExecuteTransaction(ctx context.Context, opts *CallOpts, encoded *EncodedCall) (*models.SuiTransactionBlockResponse, error)

func (*BoundContract) GetModuleName 

func (c *BoundContract) GetModuleName() string

func (*BoundContract) GetPackageID 

func (c *BoundContract) GetPackageID() string

func (*BoundContract) GetPackageName 

func (c *BoundContract) GetPackageName() string

type BuildInfo 

type BuildInfo struct {
	CompiledPackageInfo struct {
		PackageName string `yaml:"package_name"`
	} `yaml:"compiled_package_info"`
}

type CallArg 

type CallArg struct {
	Pure []byte `json:"Pure,omitempty"`
}

CallArg — mimics SDK CallArg but matches CLI JSON

type CallArgManager 

type CallArgManager struct {
	// contains filtered or unexported fields
}

func NewCallArgManager 

func NewCallArgManager() *CallArgManager

func NewCallArgManagerWithExisting 

func NewCallArgManagerWithExisting(existingInputs []*transaction.CallArg) *CallArgManager

func (*CallArgManager) AddCallArg 

func (m *CallArgManager) AddCallArg(arg *transaction.CallArg) transaction.Argument

func (*CallArgManager) ConvertCallArgsToArguments 

func (m *CallArgManager) ConvertCallArgsToArguments(callArgs []*transaction.CallArg) ([]*transaction.Argument, error)

func (*CallArgManager) ConvertEncodedCallArgsToArguments 

func (m *CallArgManager) ConvertEncodedCallArgsToArguments(encodedArgs []*EncodedCallArgument) ([]*transaction.Argument, error)

func (*CallArgManager) GetInputs 

func (m *CallArgManager) GetInputs() []*transaction.CallArg

type CallOpts 

type CallOpts struct {
	Signer           bindutils.SuiSigner
	GasObject        string
	GasBudget        *uint64
	GasPrice         *uint64
	WaitForExecution bool

	ObjectResolver *ObjectResolver
}

type Command 

type Command struct {
	MoveCall *ProgrammableMoveCall `json:"MoveCall,omitempty"`
	Publish  [][]interface{}       `json:"Publish,omitempty"`
	Upgrade  []interface{}         `json:"Upgrade,omitempty"`
}

Command — mimics SDK Command but matches CLI JSON

type DevInspectResult 

type DevInspectResult struct {
	ReturnValues [][]any `json:"returnValues"`
}

type EmptyMoveStructWitness 

type EmptyMoveStructWitness struct{}

EmptyMoveStructWitness is a placeholder for a zero-sized Move struct (typical `has drop` proof witnesses). It encodes as an empty Pure argument (empty BCS for no fields).

type EncodedCall 

type EncodedCall struct {
	Module      ModuleInformation
	Function    string
	TypeArgs    []*transaction.TypeTag
	CallArgs    []*EncodedCallArgument
	ReturnTypes []string
	TypeParams  []string
}

EncodedCall represents an encoded Move function call

func (*EncodedCall) String 

func (e *EncodedCall) String() string

func (*EncodedCall) ValidateCallArgs 

func (e *EncodedCall) ValidateCallArgs() error

ValidateCallArgs ensures all CallArgs are valid (Pure or Object) and returns an error if an unresolved SDK variant is detected

type EncodedCallArgument 

type EncodedCallArgument struct {
	// Only one of these should be set:
	CallArg  *transaction.CallArg  // For regular values (Pure, Object)
	Argument *transaction.Argument // For PTB results (Result, NestedResult, GasCoin)

	// TypeName stores the original Move type string (e.g., "&mut 0x2::clock::Clock", "&OwnerCap")
	// This is used to preserve type information (including mutability) through the encoding process
	TypeName string
}

EncodedCallArgument represents an argument in an encoded Move function call.

func NewEncodedCallArgFromArgument 

func NewEncodedCallArgFromArgument(arg *transaction.Argument) *EncodedCallArgument

func NewEncodedCallArgFromArgumentWithType 

func NewEncodedCallArgFromArgumentWithType(arg *transaction.Argument, typeName string) *EncodedCallArgument

func NewEncodedCallArgFromCallArg 

func NewEncodedCallArgFromCallArg(callArg *transaction.CallArg) *EncodedCallArgument

func NewEncodedCallArgFromCallArgWithType 

func NewEncodedCallArgFromCallArgWithType(callArg *transaction.CallArg, typeName string) *EncodedCallArgument

func (*EncodedCallArgument) IsArgument 

func (e *EncodedCallArgument) IsArgument() bool

IsArgument returns true if this is a transaction.Argument (PTB result)

func (*EncodedCallArgument) IsCallArg 

func (e *EncodedCallArgument) IsCallArg() bool

IsCallArg returns true if this is a regular CallArg

func (*EncodedCallArgument) Validate 

func (e *EncodedCallArgument) Validate() error

Validate ensures that exactly one field is set

type EphemeralPubEntry 

type EphemeralPubEntry struct {
	Source      string // Can be local path, git URL, or root
	PublishedAt string
	OriginalID  string
	UpgradeCap  string
	Version     int // Package version number
}

EphemeralPubEntry represents an entry in the ephemeral publication file (Pub.<env>.toml)

type EphemeralPubFile 

type EphemeralPubFile struct {
	BuildEnv  string
	ChainID   string
	Published []EphemeralPubEntry
}

EphemeralPubFile represents the structure of Pub.<env>.toml files

type GasData 

type GasData struct {
	Payment [][]interface{} `json:"payment"`
	Owner   string          `json:"owner"`
	Price   uint64          `json:"price"`
	Budget  uint64          `json:"budget"`
}

GasData

type GenericTypeResolver 

type GenericTypeResolver struct {
	// contains filtered or unexported fields
}

GenericTypeResolver resolves generic type parameters to concrete types

func NewGenericTypeResolver 

func NewGenericTypeResolver(typeParamNames []string, typeArgs []string) (*GenericTypeResolver, error)

NewGenericTypeResolver creates a new resolver with the given type parameter mappings

func (*GenericTypeResolver) ResolveType 

func (r *GenericTypeResolver) ResolveType(typeName string) string

ResolveType resolves a type that may contain generic parameters

type IBoundContract 

type IBoundContract interface {
	GetPackageID() string
	GetPackageName() string
	GetModuleName() string
	AppendPTB(ctx context.Context, opts *CallOpts, ptb *transaction.Transaction, encoded *EncodedCall) (*transaction.Argument, error)
	Call(ctx context.Context, opts *CallOpts, encoded *EncodedCall) ([]any, error)
	ExecuteTransaction(ctx context.Context, opts *CallOpts, encoded *EncodedCall) (*models.SuiTransactionBlockResponse, error)
}

type ModuleInformation 

type ModuleInformation struct {
	PackageID   string
	PackageName string
	ModuleName  string
}

func (*ModuleInformation) String 

func (m *ModuleInformation) String() string

type Object 

type Object struct {
	Id                   string
	InitialSharedVersion *uint64
}

func GetSharedObject 

func GetSharedObject(ctx context.Context, client sui.ISuiAPI, objectId string) (*Object, error)

type ObjectResolver 

type ObjectResolver struct {
	// contains filtered or unexported fields
}

func NewObjectResolver 

func NewObjectResolver(client sui.ISuiAPI) *ObjectResolver

func (*ObjectResolver) ClearCache 

func (r *ObjectResolver) ClearCache()

func (*ObjectResolver) GetSharedObject 

func (r *ObjectResolver) GetSharedObject(ctx context.Context, objectId string) (*Object, error)

func (*ObjectResolver) ResolveCallArg 

func (r *ObjectResolver) ResolveCallArg(ctx context.Context, arg *transaction.CallArg, typeName string) (*transaction.CallArg, error)

type PackageArtifact 

type PackageArtifact struct {
	Modules      []string `json:"modules"`
	Dependencies []string `json:"dependencies"`
	Digest       []byte   `json:"digest"`
}

func CompilePackage 

func CompilePackage(packageName contracts.Package, namedAddresses map[string]string, isUpgrade bool, suiRPC string) (PackageArtifact, error)

func ToArtifact 

func ToArtifact(artifactJSON string) (PackageArtifact, error)

type PackageID 

type PackageID = string

func PublishPackage 

func PublishPackage(
	ctx context.Context,
	opts *CallOpts,
	client sui.ISuiAPI,
	req PublishRequest,
) (PackageID, *models.SuiTransactionBlockResponse, error)

type PackageManifest 

type PackageManifest struct {
	Package      any               `toml:"package"`
	Addresses    map[string]string `toml:"addresses"`
	Dependencies any               `toml:"dependencies"`
}

type ProgrammableMoveCall 

type ProgrammableMoveCall struct {
	Package       string        `json:"package"`
	Module        string        `json:"module"`
	Function      string        `json:"function"`
	TypeArguments []interface{} `json:"type_arguments"`
	Arguments     []ArgumentRef `json:"arguments"`
}

ProgrammableMoveCall — kept simple for now

type ProgrammableTransaction 

type ProgrammableTransaction struct {
	Inputs   []CallArg `json:"inputs"`
	Commands []Command `json:"commands"`
}

ProgrammableTransaction

type PublishRequest 

type PublishRequest struct {
	CompiledModules []string `json:"compiled_modules"`
	Dependencies    []string `json:"dependencies"`
}

type PublishedTOMLEntry 

type PublishedTOMLEntry struct {
	ChainID           string
	PublishedAt       string // The on-chain address of the published package
	OriginalID        string // The address of the first version of the package
	Version           int
	ToolchainVersion  string
	UpgradeCapability string
}

PublishedTOMLEntry represents a publication entry for a specific environment

type RPCResponse 

type RPCResponse struct {
	Result struct {
		Data struct {
			ObjectID string            `json:"objectId"`
			Owner    map[string]string `json:"owner"`
		} `json:"data"`
	} `json:"result"`
}

type SourceModifier 

type SourceModifier func(packageRoot string) error

SourceModifier is a function that can modify Move source files during compilation.

This is primarily used for testing package upgrades without creating duplicate contract versions in the repository.

Example usage: 

modifier := func(packageRoot string) error {
    sourcePath := filepath.Join(packageRoot, "sources", "contract.move")
    content, _ := os.ReadFile(sourcePath)
    modified := strings.Replace(string(content), "1.0.0", "2.0.0", 1)
    return os.WriteFile(sourcePath, []byte(modified), 0o644)
}

type StructDecoder 

type StructDecoder func([]byte) (any, error)

type SuiAddressBytes 

type SuiAddressBytes [32]byte

type SuiTransactionBlockGetter 

type SuiTransactionBlockGetter interface {
	SuiGetTransactionBlock(ctx context.Context, req models.SuiGetTransactionBlockRequest) (models.SuiTransactionBlockResponse, error)
}

SuiTransactionBlockGetter is the minimal JSON-RPC surface required to poll for a transaction digest via sui_getTransactionBlock. Implementations such as github.com/block-vision/sui-go-sdk/sui.ISuiAPI satisfy it.

type TransactionData 

type TransactionData struct {
	V1 TransactionDataV1 `json:"V1"`
}

Root object

type TransactionDataV1 

type TransactionDataV1 struct {
	Kind       TransactionKind `json:"kind"`
	Sender     string          `json:"sender"`
	GasData    GasData         `json:"gas_data"`
	Expiration string          `json:"expiration"`
}

TransactionDataV1

type TransactionKind 

type TransactionKind struct {
	ProgrammableTransaction ProgrammableTransaction `json:"ProgrammableTransaction"`
}

TransactionKind

type TransferObjects 

type TransferObjects struct {
	Objects []ArgumentRef `json:"TransferObjects,omitempty"`
	Address ArgumentRef   `json:"Address,omitempty"`
}

TransferObjects

type TypeResolver 

type TypeResolver struct {
	// contains filtered or unexported fields
}

func NewTypeResolver 

func NewTypeResolver(genericParams []string, concreteTypes []string) (*TypeResolver, error)

func (*TypeResolver) ResolveType 

func (r *TypeResolver) ResolveType(moveType string) string

ResolveType resolves a potentially generic type to a concrete type

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.