SetOptionsOperation class

Configures account settings including flags, thresholds, signers, and account properties.

The SetOptions operation is one of the most versatile operations in Stellar, allowing comprehensive account configuration. It can set account options individually or in combination, enabling everything from multi-signature setups to authorization controls.

Configuration Categories:

1. Inflation Destination

  • Sets the account to receive inflation payouts
  • Note: Inflation was disabled in Protocol 12, this field is now mostly unused

2. Account Flags (Controls authorization and asset behavior)

  • AUTH_REQUIRED_FLAG (1): Requires authorization before accounts can hold your assets
  • AUTH_REVOCABLE_FLAG (2): Allows revoking authorization and freezing assets
  • AUTH_IMMUTABLE_FLAG (4): Prevents changing authorization flags in the future
  • AUTH_CLAWBACK_ENABLED_FLAG (8): Enables clawback functionality for issued assets

3. Home Domain

  • Sets the account's home domain for federation and stellar.toml lookup
  • Maximum 32 characters
  • Used for account discovery and asset information

4. Thresholds (Multi-signature weight requirements)

  • Master Weight: Weight of the account's master key (0-255)
  • Low Threshold: Required weight for low-security operations (0-255)
  • Medium Threshold: Required weight for medium-security operations (0-255)
  • High Threshold: Required weight for high-security operations (0-255)

5. Signers

  • Add or update additional signers for multi-signature
  • Set weight to 0 to remove a signer
  • Each signer has a weight (0-255)
  • Combined signer weights must meet threshold requirements

Operation Threshold Levels:

  • Low: AllowTrust, BumpSequence, ClaimClaimableBalance
  • Medium: All other operations except SetOptions and account merge
  • High: SetOptions, AccountMerge

Example - Set Account Flags (Require Authorization):

// Require authorization for accounts to hold issued assets
var setAuthRequired = SetOptionsOperationBuilder()
  .setSetFlags(1)  // AUTH_REQUIRED_FLAG
  .setSourceAccount(issuerAccountId)
  .build();

var transaction = TransactionBuilder(issuerAccount)
  .addOperation(setAuthRequired)
  .build();

Example - Configure Multi-Signature (2-of-3):

// Set up 2-of-3 multi-sig with master key and two signers
var addSigner1 = SetOptionsOperationBuilder()
  .setSigner(signer1Key, 1)  // Add first signer with weight 1
  .build();

var addSigner2 = SetOptionsOperationBuilder()
  .setSigner(signer2Key, 1)  // Add second signer with weight 1
  .build();

var setThresholds = SetOptionsOperationBuilder()
  .setMasterKeyWeight(1)      // Master key weight 1
  .setLowThreshold(1)         // Low requires 1
  .setMediumThreshold(2)      // Medium requires 2
  .setHighThreshold(2)        // High requires 2
  .build();

// Execute all operations in one transaction
var transaction = TransactionBuilder(account)
  .addOperation(addSigner1)
  .addOperation(addSigner2)
  .addOperation(setThresholds)
  .build();

Example - Set Home Domain:

// Set home domain for federation
var setDomain = SetOptionsOperationBuilder()
  .setHomeDomain('example.com')
  .build();

Example - Enable Clawback:

// Enable clawback for issued assets (must be set before issuance)
var enableClawback = SetOptionsOperationBuilder()
  .setSetFlags(8)  // AUTH_CLAWBACK_ENABLED_FLAG
  .setSourceAccount(issuerAccountId)
  .build();

Example - Remove Signer:

// Remove a signer by setting weight to 0
var removeSigner = SetOptionsOperationBuilder()
  .setSigner(signerKey, 0)  // Weight 0 removes signer
  .build();

Example - Lock Account Flags (Make Immutable):

// Prevent future flag changes by setting AUTH_IMMUTABLE_FLAG
var lockFlags = SetOptionsOperationBuilder()
  .setSetFlags(4)  // AUTH_IMMUTABLE_FLAG
  .build();

Important Security Considerations:

  • Master Key Weight 0: Disables master key (ensure other signers exist)
  • High Threshold > Total Weight: Locks account permanently
  • AUTH_IMMUTABLE_FLAG: Cannot be reversed, use with caution
  • AUTH_CLAWBACK_ENABLED: Must be set before issuing assets
  • Always test threshold configurations before committing

Flag Combinations:

  • AUTH_REQUIRED + AUTH_REVOCABLE: Full control over asset holders
  • AUTH_REQUIRED + AUTH_IMMUTABLE: Require auth but cannot revoke later
  • AUTH_REVOCABLE + CLAWBACK: Maximum issuer control

Best Practices:

  • Set flags before issuing assets
  • Test multi-sig configurations on testnet first
  • Keep backup signers when disabling master key
  • Document threshold requirements for your team
  • Use home domain for transparency and discoverability

See also:

Represents a SetOptions operation.

Inheritance

Constructors

SetOptionsOperation(String? inflationDestination, int? clearFlags, int? setFlags, int? masterKeyWeight, int? lowThreshold, int? mediumThreshold, int? highThreshold, String? homeDomain, XdrSignerKey? signer, int? signerWeight)
Creates a SetOptionsOperation.

Properties

clearFlags → int?
Flags to clear on the account.
no setter
hashCode → int
The hash code for this object.
no setterinherited
highThreshold → int?
Weight required for high threshold operations (0-255).
no setter
homeDomain → String?
The home domain of the account.
no setter
inflationDestination → String?
Account ID of the inflation destination.
no setter
lowThreshold → int?
Weight required for low threshold operations (0-255).
no setter
masterKeyWeight → int?
Weight of the master key (0-255).
no setter
mediumThreshold → int?
Weight required for medium threshold operations (0-255).
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
setFlags → int?
Flags to set on the account.
no setter
signer → XdrSignerKey?
Signer to add, update, or remove.
no setter
signerWeight → int?
Weight for the signer (0-255).
no setter
sourceAccount ↔ MuxedAccount?
Optional source account for this operation.
getter/setter pairinherited

Methods

noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toOperationBody() → XdrOperationBody
Converts this operation to its XDR OperationBody representation.
override
toString() → String
A string representation of this object.
inherited
toXdr() → XdrOperation
Converts this operation to its XDR representation.
inherited
toXdrBase64() → String
Returns base64-encoded Operation XDR object from this operation.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Methods

builder(XdrSetOptionsOp op) → SetOptionsOperationBuilder
Builds SetOptions operation from XDR operation.