chore(iota-transaction-builder): Add crate documentation

bindings/go/iota_sdk_ffi/iota_sdk_ffi.go

@@ -3734,6 +3734,15 @@ func uniffiCheckChecksums() {
 	}
 	}
 	{
+	checksum := rustCall(func(_uniffiStatus *C.RustCallStatus) C.uint16_t {
+		return C.uniffi_iota_sdk_ffi_checksum_method_transactionbuilder_gas_coins()
+	})
+	if checksum != 20903 {
+		// If this happens try cleaning and rebuilding your project
+		panic("iota_sdk_ffi: uniffi_iota_sdk_ffi_checksum_method_transactionbuilder_gas_coins: UniFFI API checksum mismatch")
+	}
+	}
+	{
 	checksum := rustCall(func(_uniffiStatus *C.RustCallStatus) C.uint16_t {
 		return C.uniffi_iota_sdk_ffi_checksum_method_transactionbuilder_gas_price()
 	})
@@ -22210,6 +22219,8 @@ type TransactionBuilderInterface interface {
 	Gas(objectId *ObjectId) *TransactionBuilder
 	// Set the gas budget for the transaction.
 	GasBudget(budget uint64) *TransactionBuilder
+	// Add a gas object to use to pay for the transaction.
+	GasCoins(objectIds []*ObjectId) *TransactionBuilder
 	// Set the gas price for the transaction.
 	GasPrice(price uint64) *TransactionBuilder
 	// Set the gas station sponsor.
@@ -22452,6 +22463,16 @@ func (_self *TransactionBuilder) GasBudget(budget uint64) *TransactionBuilder {
 	}))
 }
 
+// Add a gas object to use to pay for the transaction.
+func (_self *TransactionBuilder) GasCoins(objectIds []*ObjectId) *TransactionBuilder {
+	_pointer := _self.ffiObject.incrementPointer("*TransactionBuilder")
+	defer _self.ffiObject.decrementPointer()
+	return FfiConverterTransactionBuilderINSTANCE.Lift(rustCall(func(_uniffiStatus *C.RustCallStatus) unsafe.Pointer {
+		return C.uniffi_iota_sdk_ffi_fn_method_transactionbuilder_gas_coins(
+		_pointer,FfiConverterSequenceObjectIdINSTANCE.Lower(objectIds),_uniffiStatus)
+	}))
+}
+
 // Set the gas price for the transaction.
 func (_self *TransactionBuilder) GasPrice(price uint64) *TransactionBuilder {
 	_pointer := _self.ffiObject.incrementPointer("*TransactionBuilder")

bindings/go/iota_sdk_ffi/iota_sdk_ffi.h

@@ -4314,6 +4314,11 @@ void* uniffi_iota_sdk_ffi_fn_method_transactionbuilder_gas(void* ptr, void* obje
 void* uniffi_iota_sdk_ffi_fn_method_transactionbuilder_gas_budget(void* ptr, uint64_t budget, RustCallStatus *out_status
 );
 #endif
+#ifndef UNIFFI_FFIDEF_UNIFFI_IOTA_SDK_FFI_FN_METHOD_TRANSACTIONBUILDER_GAS_COINS
+#define UNIFFI_FFIDEF_UNIFFI_IOTA_SDK_FFI_FN_METHOD_TRANSACTIONBUILDER_GAS_COINS
+void* uniffi_iota_sdk_ffi_fn_method_transactionbuilder_gas_coins(void* ptr, RustBuffer object_ids, RustCallStatus *out_status
+);
+#endif
 #ifndef UNIFFI_FFIDEF_UNIFFI_IOTA_SDK_FFI_FN_METHOD_TRANSACTIONBUILDER_GAS_PRICE
 #define UNIFFI_FFIDEF_UNIFFI_IOTA_SDK_FFI_FN_METHOD_TRANSACTIONBUILDER_GAS_PRICE
 void* uniffi_iota_sdk_ffi_fn_method_transactionbuilder_gas_price(void* ptr, uint64_t price, RustCallStatus *out_status
@@ -7842,6 +7847,12 @@ uint16_t uniffi_iota_sdk_ffi_checksum_method_transactionbuilder_gas(void
 #define UNIFFI_FFIDEF_UNIFFI_IOTA_SDK_FFI_CHECKSUM_METHOD_TRANSACTIONBUILDER_GAS_BUDGET
 uint16_t uniffi_iota_sdk_ffi_checksum_method_transactionbuilder_gas_budget(void
 
+);
+#endif
+#ifndef UNIFFI_FFIDEF_UNIFFI_IOTA_SDK_FFI_CHECKSUM_METHOD_TRANSACTIONBUILDER_GAS_COINS
+#define UNIFFI_FFIDEF_UNIFFI_IOTA_SDK_FFI_CHECKSUM_METHOD_TRANSACTIONBUILDER_GAS_COINS
+uint16_t uniffi_iota_sdk_ffi_checksum_method_transactionbuilder_gas_coins(void
+
 );
 #endif
 #ifndef UNIFFI_FFIDEF_UNIFFI_IOTA_SDK_FFI_CHECKSUM_METHOD_TRANSACTIONBUILDER_GAS_PRICE

bindings/kotlin/lib/iota_sdk/iota_sdk_ffi.kt

@@ -2451,6 +2451,8 @@ internal interface UniffiForeignFutureCompleteVoid : com.sun.jna.Callback {
 
 
 
+
+
 
 
 
@@ -3219,6 +3221,8 @@ fun uniffi_iota_sdk_ffi_checksum_method_transactionbuilder_gas(
 ): Short
 fun uniffi_iota_sdk_ffi_checksum_method_transactionbuilder_gas_budget(
 ): Short
+fun uniffi_iota_sdk_ffi_checksum_method_transactionbuilder_gas_coins(
+): Short
 fun uniffi_iota_sdk_ffi_checksum_method_transactionbuilder_gas_price(
 ): Short
 fun uniffi_iota_sdk_ffi_checksum_method_transactionbuilder_gas_station_sponsor(
@@ -5594,6 +5598,8 @@ fun uniffi_iota_sdk_ffi_fn_method_transactionbuilder_gas(`ptr`: Pointer,`objectI
 ): Pointer
 fun uniffi_iota_sdk_ffi_fn_method_transactionbuilder_gas_budget(`ptr`: Pointer,`budget`: Long,uniffi_out_err: UniffiRustCallStatus, 
 ): Pointer
+fun uniffi_iota_sdk_ffi_fn_method_transactionbuilder_gas_coins(`ptr`: Pointer,`objectIds`: RustBuffer.ByValue,uniffi_out_err: UniffiRustCallStatus, 
+): Pointer
 fun uniffi_iota_sdk_ffi_fn_method_transactionbuilder_gas_price(`ptr`: Pointer,`price`: Long,uniffi_out_err: UniffiRustCallStatus, 
 ): Pointer
 fun uniffi_iota_sdk_ffi_fn_method_transactionbuilder_gas_station_sponsor(`ptr`: Pointer,`url`: RustBuffer.ByValue,`duration`: RustBuffer.ByValue,`headers`: RustBuffer.ByValue,uniffi_out_err: UniffiRustCallStatus, 
@@ -7239,6 +7245,9 @@ private fun uniffiCheckApiChecksums(lib: IntegrityCheckingUniffiLib) {
     if (lib.uniffi_iota_sdk_ffi_checksum_method_transactionbuilder_gas_budget() != 48686.toShort()) {
         throw RuntimeException("UniFFI API checksum mismatch: try cleaning and rebuilding your project")
     }
+    if (lib.uniffi_iota_sdk_ffi_checksum_method_transactionbuilder_gas_coins() != 20903.toShort()) {
+        throw RuntimeException("UniFFI API checksum mismatch: try cleaning and rebuilding your project")
+    }
     if (lib.uniffi_iota_sdk_ffi_checksum_method_transactionbuilder_gas_price() != 7437.toShort()) {
         throw RuntimeException("UniFFI API checksum mismatch: try cleaning and rebuilding your project")
     }
@@ -38714,6 +38723,11 @@ public interface TransactionBuilderInterface {
      */
     fun `gasBudget`(`budget`: kotlin.ULong): TransactionBuilder
 
+    /**
+     * Add a gas object to use to pay for the transaction.
+     */
+    fun `gasCoins`(`objectIds`: List<ObjectId>): TransactionBuilder
+
     /**
      * Set the gas price for the transaction.
      */
@@ -39030,6 +39044,21 @@ open class TransactionBuilder: Disposable, AutoCloseable, TransactionBuilderInte
 
 
 
+    /**
+     * Add a gas object to use to pay for the transaction.
+     */override fun `gasCoins`(`objectIds`: List<ObjectId>): TransactionBuilder {
+            return FfiConverterTypeTransactionBuilder.lift(
+    callWithPointer {
+    uniffiRustCall() { _status ->
+    UniffiLib.INSTANCE.uniffi_iota_sdk_ffi_fn_method_transactionbuilder_gas_coins(
+        it, FfiConverterSequenceTypeObjectId.lower(`objectIds`),_status)
+}
+    }
+    )
+    }
+
+
+
     /**
      * Set the gas price for the transaction.
      */override fun `gasPrice`(`price`: kotlin.ULong): TransactionBuilder {

bindings/python/lib/iota_sdk_ffi.py

@@ -1211,6 +1211,8 @@ def _uniffi_check_api_checksums(lib):
         raise InternalError("UniFFI API checksum mismatch: try cleaning and rebuilding your project")
     if lib.uniffi_iota_sdk_ffi_checksum_method_transactionbuilder_gas_budget() != 48686:
         raise InternalError("UniFFI API checksum mismatch: try cleaning and rebuilding your project")
+    if lib.uniffi_iota_sdk_ffi_checksum_method_transactionbuilder_gas_coins() != 20903:
+        raise InternalError("UniFFI API checksum mismatch: try cleaning and rebuilding your project")
     if lib.uniffi_iota_sdk_ffi_checksum_method_transactionbuilder_gas_price() != 7437:
         raise InternalError("UniFFI API checksum mismatch: try cleaning and rebuilding your project")
     if lib.uniffi_iota_sdk_ffi_checksum_method_transactionbuilder_gas_station_sponsor() != 41106:
@@ -6110,6 +6112,12 @@ class _UniffiForeignFutureStructVoid(ctypes.Structure):
     ctypes.POINTER(_UniffiRustCallStatus),
 )
 _UniffiLib.uniffi_iota_sdk_ffi_fn_method_transactionbuilder_gas_budget.restype = ctypes.c_void_p
+_UniffiLib.uniffi_iota_sdk_ffi_fn_method_transactionbuilder_gas_coins.argtypes = (
+    ctypes.c_void_p,
+    _UniffiRustBuffer,
+    ctypes.POINTER(_UniffiRustCallStatus),
+)
+_UniffiLib.uniffi_iota_sdk_ffi_fn_method_transactionbuilder_gas_coins.restype = ctypes.c_void_p
 _UniffiLib.uniffi_iota_sdk_ffi_fn_method_transactionbuilder_gas_price.argtypes = (
     ctypes.c_void_p,
     ctypes.c_uint64,
@@ -8540,6 +8548,9 @@ class _UniffiForeignFutureStructVoid(ctypes.Structure):
 _UniffiLib.uniffi_iota_sdk_ffi_checksum_method_transactionbuilder_gas_budget.argtypes = (
 )
 _UniffiLib.uniffi_iota_sdk_ffi_checksum_method_transactionbuilder_gas_budget.restype = ctypes.c_uint16
+_UniffiLib.uniffi_iota_sdk_ffi_checksum_method_transactionbuilder_gas_coins.argtypes = (
+)
+_UniffiLib.uniffi_iota_sdk_ffi_checksum_method_transactionbuilder_gas_coins.restype = ctypes.c_uint16
 _UniffiLib.uniffi_iota_sdk_ffi_checksum_method_transactionbuilder_gas_price.argtypes = (
 )
 _UniffiLib.uniffi_iota_sdk_ffi_checksum_method_transactionbuilder_gas_price.restype = ctypes.c_uint16
@@ -38458,6 +38469,12 @@ def gas_budget(self, budget: "int"):
         Set the gas budget for the transaction.
         """
 
+        raise NotImplementedError
+    def gas_coins(self, object_ids: "typing.List[ObjectId]"):
+        """
+        Add a gas object to use to pay for the transaction.
+        """
+
         raise NotImplementedError
     def gas_price(self, price: "int"):
         """
@@ -38773,6 +38790,22 @@ def gas_budget(self, budget: "int") -> "TransactionBuilder":
 
 
 
+    def gas_coins(self, object_ids: "typing.List[ObjectId]") -> "TransactionBuilder":
+        """
+        Add a gas object to use to pay for the transaction.
+        """
+
+        _UniffiConverterSequenceTypeObjectId.check_lower(object_ids)
+
+        return _UniffiConverterTypeTransactionBuilder.lift(
+            _uniffi_rust_call(_UniffiLib.uniffi_iota_sdk_ffi_fn_method_transactionbuilder_gas_coins,self._uniffi_clone_pointer(),
+        _UniffiConverterSequenceTypeObjectId.lower(object_ids))
+        )
+
+
+
+
+
     def gas_price(self, price: "int") -> "TransactionBuilder":
         """
         Set the gas price for the transaction.

crates/iota-sdk-ffi/README.md

@@ -1,8 +1,115 @@
 # IOTA SDK FFI
 
+Core type definitions for the IOTA blockchain.
+
 This crate can generate bindings for various languages using [UniFFI](https://github.com/mozilla/uniffi-rs).
 
-## Supported languages
+[IOTA](https://iota.org) is a next-generation smart contract platform with high throughput, low latency, and an asset-oriented programming model powered by the Move programming language. This crate provides type definitions for working with the data that makes up the IOTA blockchain.
+
+## BCS
+[BCS](https://docs.rs/bcs) is the serialization format used to represent the state of the blockchain and is used extensively throughout the IOTA ecosystem. In particular the BCS format is leveraged because it _"guarantees canonical serialization, meaning that for any given data type, there is a one-to-one correspondence between in-memory values and valid byte representations."_
+
+One benefit of this property of having a canonical serialized representation is to allow different entities in the ecosystem to all agree on how a particular type should be interpreted and more importantly define a deterministic representation for hashing and signing.
+
+This library strives to guarantee that the types defined are fully BCS-compatible with the data that the network produces. The one caveat to this would be that as the IOTA protocol evolves, new type variants are added and older versions of this library may not support those newly added variants. The expectation is that the most recent release of this library will support new variants and types as they are released to IOTA's `testnet` network.
+
+See the documentation for the various types defined by this crate for a specification of their BCS serialized representation which will be defined using ABNF notation as described by [RFC-5234](https://datatracker.ietf.org/doc/html/rfc5234). In addition to the format itself, some types have an extra layer of verification and may impose additional restrictions on valid byte representations above and beyond those already provided by BCS. In these instances the documentation for those types will clearly specify these additional restrictions.
+
+Here are some common rules:
+```text
+; --- BCS Value ---
+bcs-value           = bcs-struct / bcs-enum / bcs-length-prefixed / bcs-fixed-length
+bcs-length-prefixed = bytes / string / vector / option
+bcs-fixed-length    = u8 / u16 / u32 / u64 / u128 /
+                      i8 / i16 / i32 / i64 / i128 /
+                      boolean
+bcs-struct          = *bcs-value                ; Sequence of serialized fields
+bcs-enum            = uleb128-index bcs-value   ; Enum index and associated value
+; --- Length-prefixed types ---
+bytes           = uleb128 *OCTET          ; Raw bytes of the specified length
+string          = uleb128 *OCTET          ; valid utf8 string of the specified length
+vector          = uleb128 *bcs-value      ; Length-prefixed list of values
+option          = %x00 / (%x01 bcs-value) ; optional value
+; --- Fixed-length types ---
+u8          = OCTET                     ; 1-byte unsigned integer
+u16         = 2OCTET                    ; 2-byte unsigned integer, little-endian
+u32         = 4OCTET                    ; 4-byte unsigned integer, little-endian
+u64         = 8OCTET                    ; 8-byte unsigned integer, little-endian
+u128        = 16OCTET                   ; 16-byte unsigned integer, little-endian
+i8          = OCTET                     ; 1-byte signed integer
+i16         = 2OCTET                    ; 2-byte signed integer, little-endian
+i32         = 4OCTET                    ; 4-byte signed integer, little-endian
+i64         = 8OCTET                    ; 8-byte signed integer, little-endian
+i128        = 16OCTET                   ; 16-byte signed integer, little-endian
+boolean     = %x00 / %x01               ; Boolean: 0 = false, 1 = true
+array       = *(bcs-value)              ; Fixed-length array
+; --- ULEB128 definition ---
+uleb128         = 1*5uleb128-byte       ; Variable-length ULEB128 encoding
+uleb128-byte    = %x00-7F / %x80-FF     ; ULEB128 continuation rules
+uleb128-index   = uleb128               ; ULEB128-encoded variant index
+```
+
+## Transaction Builder
+
+This crate contains the
+[TransactionBuilder](./src/transaction_builder/mod.rs), which allows
+for construction of Programmable Transactions which can be executed on the
+IOTA network.
+
+### Methods
+
+The following methods are available:
+
+#### Commands
+
+Each command method adds one or more commands to the final transaction. Some commands have optional follow-up methods. Most command results can be named, which allows them to be used later in the transaction via the `PTBArgument::Res` variant. When a single name is provided, the result will be named, and when a list of names is provided, the names will be used for the individual nested results.
+
+- `move_call`: Call a move function.
+- `send_iota`: Send IOTA coins to a recipient address.
+- `send_coins`: Send coins of any type to a recipient address.
+- `merge_coins`: Merge a list of coins into a single primary coin.
+- `split_coins`: Split a coin into coins of various amounts.
+- `transfer_objects`: Send objects to a recipient address.
+- `publish`: Publish a move package.
+- `upgrade`: Upgrade a move package.
+- `make_move_vec`: Create a move `vector`.
+
+#### Metadata
+
+These methods set various metadata which may be needed for the execution.
+
+- `gas`: Add a gas coin to pay for the execution.
+- `gas_coins`: Add gas coins to pay for the execution.
+- `gas_budget`: Set the maximum gas budget to spend.
+- `gas_price`: Set the gas price.
+- `sponsor`: Set the gas sponsor address.
+- `gas_station_sponsor`: Set the gas station URL. See [Gas Station](#gas-station) for more info.
+- `expiration`: Set the transaction expiration epoch.
+
+### Finalization and Execution
+
+There are several ways to finish the builder. First, the [finish](transaction_builder::TransactionBuilder::finish) method can be used to return the resulting [Transaction](iota_types::Transaction), which can be manually serialized, executed, etc.
+
+Additionally, the builder can directly [dry_run](transaction_builder::TransactionBuilder::dry_run) or [execute](transaction_builder::TransactionBuilder::execute) the transaction.
+
+When the transaction is resolved, the builder will try to ensure a valid state by de-duplicating and converting appropriate inputs into references to the gas coin. This means that the same input can be passed multiple times and the final transaction will only contain one instance. However, in some cases an invalid state can still be reached. For instance, if a coin is used both for gas and as part of a group of coins, i.e. when transferring objects, the transaction can not possibly be valid.
+
+#### Defaults
+
+The builder can set some values by default. The
+following are the default behaviors for each metadata value.
+
+- Gas: One page of coins owned by the sender.
+- Gas Budget: A dry run will be used to estimate.
+- Gas Price: The current reference gas price.
+
+### Gas Station
+
+The Transaction Builder supports executing via a [Gas Station](https://github.com/iotaledger/gas-station). To do so, the URL, duration, and headers must be provided via [gas_station_sponsor](transaction_builder::TransactionBuilder::gas_station_sponsor).
+
+By default the request will contain the header `Content-Type: application/json` When this data has been set, calling [execute](transaction_builder::TransactionBuilder::execute) will request gas from and send the resulting transaction to this endpoint instead of using the GraphQL client.
+
+### Supported languages
 
 - [Go](../../bindings/go)
 - [Kotlin](../../bindings/kotlin)

crates/iota-sdk-ffi/src/graphql.rs

@@ -791,7 +791,8 @@ impl GraphQLClient {
     /// Get a page of dynamic fields for the provided address. Note that this
     /// will also fetch dynamic fields on wrapped objects.
     ///
-    /// This returns [`Page`] of [`DynamicFieldOutput`]s.
+    /// This returns a page of
+    /// [`DynamicFieldOutput`s](crate::types::graphql::DynamicFieldOutput).
     #[uniffi::method(default(pagination_filter = None))]
     pub async fn dynamic_fields(
         &self,