Categorygithub.com/iotaledger/iota.go/v2
modulepackage
2.0.1
Repository: https://github.com/iotaledger/iota.go.git
Documentation: pkg.go.dev
Overview
Versions
3
Dependencies
21
Dependents
47
Files
4.8k SLOC

# README

iota.go

Official Go library.

This library allows you to do the following:

  • Create messages with indexation and transaction payloads
  • Get messages and outputs
  • Sign transactions
  • Generate addresses
  • Interact with an IOTA node
  • Act as a foundation for Go based node software

If you need to have more sophisticated account management, have a look at wallet.rs for which we also provide bindings in Python and JavaScript.

Requirements

This library was mainly tested with Go version 1.16.x

To use the library, we recommend you update Go to the latest stable version.

Using the library

Using the library is easy, just go get it as any other dependency:

go get github.com/iotaledger/iota.go/v2

API reference

You can read the API reference here.

Joining the discussion

If you want to get involved in the community, need help with setting up, have any issues or just want to discuss IOTA with other people, feel free to join our Discord in the #clients-dev and #clients-discussion channels.

License

The MIT license can be found here.

# Packages

Package bech32 implements bech32 encoding and decoding.
Package ed25519 implements the Ed25519 signature algorithm.
No description provided by the author
Package pow implements the Curl-based proof of work for arbitrary binary data.
No description provided by the author
No description provided by the author
Package units provides functions for converting different units of IOTAs.
Package iotagox provides experimental APIs which are not stable.

# Functions

AddressFromEd25519PubKey returns the address belonging to the given Ed25519 public key.
AddressSelector implements SerializableSelectorFunc for address types.
DeserializeObjectFromJSON reads out the type of the given raw json message, then selects the appropriate object type and deserializes the given *json.RawMessage into it.
InMemoryEd25519MilestoneSigner is a function which uses the provided Ed25519 MilestonePublicKeyMapping to produce signatures for the Milestone essence data.
InputSelector implements SerializableSelectorFunc for input types.
InputsUTXORefIndexBoundsValidator returns a validator which checks that the UTXO ref index is within bounds.
InputsUTXORefsUniqueValidator returns a validator which checks that every input has a unique UTXO ref.
InsecureRemoteEd25519MilestoneSigner is a function which uses a remote RPC server via an insecure connection to produce signatures for the Milestone essence data.
MessageIDFromHexString converts the given message IDs from their hex to MessageID representation.
MessageIDToHexString converts the given message ID to their hex representation.
MustMessageIDFromHexString converts the given message IDs from their hex to MessageID representation.
MustParseEd25519AddressFromHexString parses the given hex string into an Ed25519Address.
NetworkIDFromString returns the network ID string's numerical representation.
NewAddressKeysForEd25519Address returns new AddressKeys for Ed25519Address.
NewDustSemanticValidation returns a SemanticValidationFunc which verifies whether a transaction fulfils the semantics regarding dust outputs: A transaction: - consuming a SigLockedDustAllowanceOutput on address A or - creating a SigLockedSingleOutput with deposit amount < OutputSigLockedDustAllowanceOutputMinDeposit (dust output) is only semantically valid, if after the transaction is booked, the number of dust outputs on address A does not exceed the allowed threshold of the sum of min(S / div, dustOutputsCountLimit).
NewInMemoryAddressSigner creates a new InMemoryAddressSigner holding the given AddressKeys.
NewMessageBuilder creates a new MessageBuilder.
NewMilestone creates a new Milestone.
NewNodeHTTPAPIClient returns a new NodeHTTPAPIClient with the given BaseURL.
NewReceiptBuilder creates a new ReceiptBuilder.
NewTransactionBuilder creates a new TransactionBuilder.
OutputsAddrUniqueValidator returns a validator which checks that all addresses are unique per OutputType.
OutputsDepositAmountValidator returns a validator which checks that: 1.
OutputSelector implements SerializableSelectorFunc for output types.
ParseBech32 decodes a bech32 encoded string.
ParseEd25519AddressFromHexString parses the given hex string into an Ed25519Address.
PayloadSelector implements SerializableSelectorFunc for payload types.
SignatureSelector implements SerializableSelectorFunc for signature types.
TransactionEssenceSelector implements SerializableSelectorFunc for transaction essence types.
UnlockBlockSelector implements SerializableSelectorFunc for unlock block types.
UnlockBlocksSigUniqueAndRefValidator returns a validator which checks that: 1.
ValidateInputs validates the inputs by running them against the given InputsValidatorFunc.
ValidateOutputs validates the outputs by running them against the given OutputsValidatorFunc.
ValidateReceipt validates whether given the following receipt: - None of the MigratedFundsEntry objects deposits more than the max supply and deposits at least MinMigratedFundsEntryDeposit tokens.
ValidateUnlockBlocks validates the unlock blocks by running them against the given UnlockBlockValidatorFunc.
WithNodeHTTPAPIClientHTTPClient sets the used HTTP Client.
WithNodeHTTPAPIClientUserInfo sets the Userinfo used to add basic auth "Authorization" headers to the requests.

# Constants

AddressEd25519 denotes an Ed25519 address.
DustAllowanceDivisor defines the divisor used to compute the allowed dust outputs on an address.
Ed25519AddressBytesLength is the length of an Ed25519 address.
Ed25519AddressSerializedBytesSize is the size of a serialized Ed25519 address with its type denoting byte.
Ed25519SignatureSerializedBytesSize defines the size of a serialized Ed25519Signature with its type denoting byte and public key.
IndexationBinSerializedMinSize is the minimum size of an Indexation.
IndexationIndexMaxLength defines the max length of the index within an Indexation.
IndexationIndexMinLength defines the min length of the index within an Indexation.
IndexationPayloadTypeID defines the indexation payload's ID.
InputTreasury is a type of input which references a milestone which generated a treasury output.
InputUTXO is a type of input which references an unspent transaction output.
MaxDustOutputsOnAddress defines the maximum amount of dust outputs allowed to "reside" on an address.
MaxInputsCount defines the maximum amount of inputs within a TransactionEssence.
MaxMigratedFundsEntryCount defines the maximum amount of MigratedFundsEntry items within a Receipt.
MaxOutputsCount defines the maximum amount of outputs within a TransactionEssence.
MaxParentsInAMessage defines the maximum amount of parents in a message.
MaxPublicKeysInAMilestone is the maximum amount of public keys in a milestone.
MaxSignaturesInAMilestone is the maximum amount of signatures in a milestone.
MessageBinSerializedMaxSize defines the maximum size of a message.
MessageBinSerializedMinSize defines the minimum size of a message: network ID + parent count + 1 parent + uint16 payload length + nonce.
MessageIDLength defines the length of a message ID.
MessageNetworkIDLength defines the length of the network ID in bytes.
MilestoneBinSerializedMinSize defines the serialized size of a milestone payload.
MilestoneIDLength defines the length of a Milestone ID.
MilestoneInclusionMerkleProofLength defines the length of the inclusion merkle proof within a milestone payload.
MilestonePayloadTypeID defines the Milestone payload's ID.
MilestonePublicKeyLength defines the length of a public key within a milestone.
MilestoneSignatureLength defines the length of the milestone signature.
MinInputsCount defines the minimum amount of inputs within a TransactionEssence.
MinMigratedFundsEntryCount defines the minimum amount of MigratedFundsEntry items within a Receipt.
MinMigratedFundsEntryDeposit defines the minimum amount a MigratedFundsEntry must deposit.
MinOutputsCount defines the minimum amount of inputs within a TransactionEssence.
MinParentsInAMessage defines the minimum amount of parents in a message.
MinPublicKeysInAMilestone is the minimum amount of public keys in a milestone.
MinSignaturesInAMilestone is the minimum amount of signatures in a milestone.
NodeAPIRouteAddressBech32Balance is the route for getting the total balance of all unspent outputs of a Bech32 address.
NodeAPIRouteAddressBech32Outputs is the route for getting all output IDs for a Bech32 address.
NodeAPIRouteAddressEd25519Balance is the route for getting the total balance of all unspent outputs of an ed25519 address.
NodeAPIRouteAddressEd25519Outputs is the route for getting all output IDs for an ed25519 address.
NodeAPIRouteHealth is the route for querying a node's health status.
NodeAPIRouteInfo is the route for getting the node info.
NodeAPIRouteMessageBytes is the route for getting message raw data by its messageID.
NodeAPIRouteMessageChildren is the route for getting message IDs of the children of a message, identified by its messageID.
NodeAPIRouteMessageMetadata is the route for getting message metadata by its messageID.
NodeAPIRouteMessages is the route for getting message IDs or creating new messages.
NodeAPIRouteMilestone is the route for getting a milestone by its milestoneIndex.
NodeAPIRouteMilestoneUTXOChanges is the route for getting all UTXO changes of a milestone by its milestoneIndex.
NodeAPIRouteOutput is the route for getting outputs by their outputID (transactionHash + outputIndex).
NodeAPIRoutePeer is the route for getting peers by their peerID.
NodeAPIRoutePeers is the route for getting all peers of the node.
NodeAPIRouteReceipts is the route for getting all persisted receipts on a node.
NodeAPIRouteReceiptsByMigratedAtIndex is the route for getting all persisted receipts for a given migrated at index on a node.
NodeAPIRouteTips is the route for getting two tips.
NodeAPIRouteTreasury is the route for getting the current treasury.
OutputSigLockedDustAllowanceOutput is like OutputSigLockedSingleOutput but it is used to increase the allowance/amount of dust outputs on a given address.
OutputSigLockedDustAllowanceOutputMinDeposit defines the minimum deposit amount of a SigLockedDustAllowanceOutput.
OutputSigLockedSingleOutput denotes a type of output which is locked by a signature and deposits onto a single address.
OutputTreasuryOutput denotes the type of the TreasuryOutput.
Network prefixes.
Network prefixes.
ReceiptPayloadTypeID defines the Receipt payload's ID.
ReferenceUnlockBlockSize defines the size of a reference unlock block.
RefUTXOIndexMax is the maximum index of a referenced UTXO.
RefUTXOIndexMin is the minimum index of a referenced UTXO.
SigLockedDustAllowanceOutputAddressOffset defines the offset at which the address portion within a SigLockedDustAllowanceOutput begins.
SigLockedDustAllowanceOutputBytesMinSize defines the minimum size of a SigLockedDustAllowanceOutput.
SigLockedDustAllowanceOutputEd25519AddrBytesSize is the size of a SigLockedDustAllowanceOutput containing an Ed25519Address as its deposit address.
SigLockedSingleOutputAddressOffset defines the offset at which the address portion within a SigLockedSingleOutput begins.
SigLockedSingleOutputBytesMinSize defines the minimum size a SigLockedSingleOutput.
SigLockedSingleOutputEd25519AddrBytesSize defines the size of a SigLockedSingleOutput containing an Ed25519Address as its deposit address.
SignatureEd25519 denotes an Ed25519Signature.
SignatureUnlockBlockMinSize defines the minimum size of a signature unlock block.
TokenSupply is the IOTA token supply.
TransactionBinSerializedMinSize defines the minimum size of a serialized Transaction.
TransactionEssenceMinByteSize defines the minimum size of a TransactionEssence.
TransactionEssenceNormal denotes a standard transaction essence.
TransactionIDLength defines the length of a Transaction ID.
TransactionPayloadTypeID defines the transaction payload's type ID.
TreasuryInputBytesLength is the length of a TreasuryInput.
TreasuryInputSerializedBytesSize is the size of a serialized TreasuryInput with its type denoting byte.
TreasuryOutputBytesSize defines the binary serialized size of a TreasuryOutput.
TreasuryTransactionByteSize defines the serialized size of a TreasuryTransaction.
TreasuryTransactionPayloadTypeID defines the TreasuryTransaction payload's ID.
UnlockBlockReference denotes a reference unlock block.
UnlockBlockSignature denotes a signature unlock block.
UTXOInputSize is the size of a UTXO input: input type + tx id + index.

# Variables

ErrAddressKeysNotMapped gets returned if the needed keys to sign a message are absent/not mapped.
ErrAddressKeysWrongType gets returned if the specified keys to sign a message for a given address are of the wrong type.
ErrDepositAmountMustBeGreaterThanZero returned if the deposit amount of an output is less or equal zero.
ErrEd25519PubKeyAndAddrMismatch gets returned when an Ed25519Address and public key do not correspond to each other.
ErrEd25519SignatureInvalid gets returned for invalid an Ed25519Signature.
ErrHTTPBadRequest gets returned for 400 bad request HTTP responses.
ErrHTTPInternalServerError gets returned for 500 internal server error HTTP responses.
ErrHTTPNotFound gets returned for 404 not found error HTTP responses.
ErrHTTPNotImplemented gets returned for 501 not implemented error HTTP responses.
ErrHTTPUnauthorized gets returned for 401 unauthorized error HTTP responses.
ErrHTTPUnknownError gets returned for unknown error HTTP responses.
ErrIndexationIndexExceedsMaxSize gets returned when an Indexation's index exceeds IndexationIndexMaxLength.
ErrIndexationIndexUnderMinSize gets returned when an Indexation's index is under IndexationIndexMinLength.
ErrInputOutputSumMismatch gets returned if a transaction does not spend the entirety of the inputs to the outputs.
ErrInputSignatureUnlockBlockInvalid gets returned for errors where an input has a wrong companion signature unlock block.
ErrInputUTXORefsNotUnique gets returned if multiple inputs reference the same UTXO.
ErrInvalidDustAllowance gets returned for errors where the dust allowance is semantically invalid.
ErrInvalidJSON gets returned when invalid JSON is tried to get parsed.
ErrInvalidReceipt gets returned when a receipt is invalid.
ErrInvalidTransactionEssence gets returned if the transaction essence within a Transaction is invalid.
ErrMessageExceedsMaxSize gets returned when a serialized message exceeds MessageBinSerializedMaxSize.
ErrMilestoneDuplicatedPublicKey gets returned when a Milestone contains duplicated public keys.
ErrMilestoneInMemorySignerPrivateKeyMissing gets returned when an InMemoryEd25519MilestoneSigner is missing a private key.
ErrMilestoneInvalidMinPoWScoreValues gets returned when the min.
ErrMilestoneInvalidMinSignatureThreshold gets returned when an invalid min signatures threshold is given to the verification function.
ErrMilestoneInvalidSignature gets returned when a Milestone's signature is invalid.
ErrMilestoneNonApplicablePublicKey gets returned when a Milestone contains a public key which isn't in the applicable public key set.
ErrMilestoneProducedSignaturesCountMismatch gets returned when a MilestoneSigningFunc produces less signatures than expected.
ErrMilestoneSignaturesPublicKeyCountMismatch gets returned when the count of signatures and public keys within a Milestone don't match.
ErrMilestoneSignatureThresholdGreaterThanApplicablePublicKeySet gets returned when a min.
ErrMilestoneTooFewPublicKeys gets returned if a to be deserialized Milestone does not contain at least one public key.
ErrMilestoneTooFewSignatures gets returned if a to be deserialized Milestone does not contain at least one signature.
ErrMilestoneTooFewSignaturesForVerificationThreshold gets returned if there are less signatures within a Milestone than the min.
ErrMilestoneTooManySignatures gets returned when a Milestone holds more than 255 signatures.
ErrMinInputsNotReached gets returned if the count of inputs is too small.
ErrMinOutputsNotReached gets returned if the count of outputs is too small.
ErrMissingUTXO gets returned if an UTXO is missing to commence a certain operation.
ErrOutputAddrNotUnique gets returned if multiple outputs deposit to the same address.
ErrOutputDepositsMoreThanTotalSupply gets returned if an output deposits more than the total supply.
ErrOutputDustAllowanceLessThanMinDeposit gets returned if a SigLockedDustAllowanceOutput deposits less than OutputSigLockedDustAllowanceOutputMinDeposit.
ErrOutputsSumExceedsTotalSupply gets returned if the sum of the output deposits exceeds the total supply of tokens.
ErrReceiptMustContainATreasuryTransaction gets returned if a Receipt does not contain a TreasuryTransaction.
ErrRefUnlockBlockInvalidRef gets returned if a reference unlock block does not reference a signature unlock block.
ErrRefUTXOIndexInvalid gets returned on invalid UTXO indices.
ErrSignatureAndAddrIncompatible gets returned if an address of an input has a companion signature unlock block with the wrong signature type.
ErrSigUnlockBlockHasNilSig gets returned if a signature unlock block contains a nil signature.
ErrSigUnlockBlocksNotUnique gets returned if unlock blocks making part of a transaction aren't unique.
ErrTransactionBuilderUnsupportedAddress gets returned when an unsupported address type is given for a builder operation.
ErrUnknownAddrType gets returned for unknown address types.
ErrUnknownInputType gets returned for unknown input types.
ErrUnknownOutputType gets returned for unknown output types.
ErrUnknownPayloadType gets returned for unknown payload types.
ErrUnknownSignatureType gets returned for unknown signature types.
ErrUnknownTransactionEssenceType gets returned for unknown transaction essence types.
ErrUnknownUnlockBlockType gets returned for unknown unlock blocks.
ErrUnlockBlocksMustMatchInputCount gets returned if the count of unlock blocks doesn't match the count of inputs.
ErrUnsupportedObjectType gets returned for unsupported object types.
ErrUnsupportedPayloadType gets returned for unsupported payload types.

# Structs

AddPeerRequest defines the request for a POST peer REST API call.
AddressBalanceResponse defines the response of a GET addresses REST API call.
AddressKeys pairs an address and its source key(s).
AddressOutputsResponse defines the response of a GET outputs by address REST API call.
ChildrenResponse defines the response of a GET children REST API call.
Ed25519Signature defines an Ed25519 signature.
GossipHeartbeat represents a gossip heartbeat message.
GossipInfo represents information about an ongoing gossip protocol.
HTTPErrorResponseEnvelope defines the error response schema for node API responses.
HTTPOkResponseEnvelope defines the ok response schema for node API responses.
Indexation is a payload which holds an index and associated data.
InMemoryAddressSigner implements AddressSigner by holding keys simply in-memory.
JSONObjectEnvelope defines the envelope for looking-ahead an object's type before deserializing it to its actual object.
Message can carry a payload and references two other messages.
MessageBuilder is used to easily build up a Message.
MessageIDsByIndexResponse defines the response of a GET messages REST API call.
MessageMetadataResponse defines the response of a GET message metadata REST API call.
MigratedFundsEntry are funds which were migrated from a legacy network.
Milestone represents a special payload which defines the inclusion set of other messages in the Tangle.
MilestoneResponse defines the response of a GET milestones REST API call.
MilestoneUTXOChangesResponse defines the response of a GET milestone UTXO changes REST API call.
NodeHTTPAPIClient is a client for node HTTP REST API endpoints.
NodeHTTPAPIClientOptions define options for the NodeHTTPAPIClient.
NodeInfoResponse defines the response of a GET info REST API call.
NodeOutputResponse defines the response of a GET outputs REST API call.
NodeTipsResponse defines the response of a GET tips REST API call.
PeerGossipMetrics defines the peer gossip metrics.
PeerResponse defines the response of a GET peer REST API call.
RawDataEnvelope is used internally to encapsulate binary data.
Receipt is a listing of migrated funds.
ReceiptBuilder is used to easily build up a Receipt.
ReceiptsResponse defines the response for receipts GET related REST API calls.
ReceiptTuple represents a receipt and the milestone index in which it was contained.
ReferenceUnlockBlock is an unlock block which references a previous unlock block.
SigLockedDustAllowanceOutput functions like a SigLockedSingleOutput but as a special property it is used to increase the allowance/amount of dust outputs on a given address.
SigLockedSingleOutput is an output type which can be unlocked via a signature.
SignatureUnlockBlock holds a signature which unlocks inputs.
ToBeSignedUTXOInput defines a UTXO input which needs to be signed.
Transaction is a transaction with its inputs, outputs and unlock blocks.
TransactionBuilder is used to easily build up a Transaction.
TransactionEssence is the essence part of a Transaction.
TreasuryOutput is an output which holds the treasury of a network.
TreasuryResponse defines the response of a GET treasury REST API call.
TreasuryTransaction represents a transaction which moves funds from the treasury.
UTXOInput references an unspent transaction output by the Transaction's ID and the corresponding index of the output.

# Interfaces

Address describes a general address.
AddressSigner produces signatures for messages which get verified against a given address.
JSONSerializable is an object which can return a Serializable.
Output defines the deposit of funds.

# Type aliases

AddressSignerFunc implements the AddressSigner interface.
AddressType defines the type of addresses.
DustAllowanceFunc returns the deposit sum of dust allowance outputs and amount of dust outputs on the given address.
Ed25519Address defines an Ed25519 address.
InputsValidatorFunc which given the index of an input and the input itself, runs validations and returns an error if any should fail.
InputToOutputMapping maps inputs to their origin UTXOs.
InputType defines the type of inputs.
JSONSerializableSelectorFunc is a function that given a type int, returns an empty instance of the given underlying type.
LegacyTailTransactionHash represents the bytes of a T5B1 encoded legacy tail transaction hash.
MessageID is the ID of a Message.
MessageIDs are IDs of messages.
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
MilestoneSigningFunc is a function which produces a set of signatures for the given Milestone essence data.
NetworkID defines the ID of the network on which entities operate on.
NetworkPrefix denotes the different network prefixes.
NodeHTTPAPIClientOption is a function setting a NodeHTTPAPIClient option.
OutputIDHex is the hex representation of an output ID.
Outputs is a slice of Output.
OutputsValidatorFunc which given the index of an output and the output itself, runs validations and returns an error if any should fail.
OutputType defines the type of outputs.
SemanticValidationFunc is a function which when called tells whether the transaction is passing a specific semantic validation rule or not.
SignatureType defines the type of signature.
SigValidationFunc is a function which when called tells whether its signature verification computation was successful or not.
TransactionBuilderInputFilter is a filter function which determines whether an input should be used or not.
TransactionEssenceType defines the type of transaction.
TransactionFunc is a function which receives a Transaction as its parameter.
TransactionID is the ID of a Transaction.
TransactionIDs are IDs of transactions.
TreasuryInput is an input which references a milestone which generated a TreasuryOutput.
UnlockBlockType defines a type of unlock block.
UnlockBlockValidatorFunc which given the index of an unlock block and the unlock block itself, runs validations and returns an error if any should fail.
UTXOInputID defines the identifier for an UTXO input which consists out of the referenced transaction ID and the given output index.
UTXOInputIDs is a slice of UTXOInputID.