# IMasterAccountController

> Flare Smart Accounts IMasterAccountController interface reference.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.

Source: https://dev.flare.network/smart-accounts/reference/IMasterAccountController

Interface for the `MasterAccountController` contract, which manages personal accounts and executes XRPL instructions on Flare. It uses the [Diamond pattern](https://eips.ethereum.org/EIPS/eip-2535) to compose all functionality into a single deployed contract.

Sourced from `IMasterAccountController.sol` and its facets on [GitHub](https://github.com/flare-foundation/flare-smart-accounts/tree/main/contracts/userInterfaces).

## Personal Accounts[​](#personal-accounts "Direct link to Personal Accounts")

### `getPersonalAccount`[​](#getpersonalaccount "Direct link to getpersonalaccount")

Returns the [`PersonalAccount`](/smart-accounts/reference/IPersonalAccount) contract address for a given XRPL owner. A `PersonalAccount` is deployed only once the first instruction has been sent from its owner XRPL address. If the account has not yet been deployed, it returns the precomputed deterministic address.

```
function getPersonalAccount(    string calldata _xrplOwner)    external view    returns (address);
```

Parameters:

-   `_xrplOwner`: The XRPL address of the owner.

Returns:

-   The [`PersonalAccount`](/smart-accounts/reference/IPersonalAccount) contract address, or the computed address if not yet deployed.

## Instructions[​](#instructions "Direct link to Instructions")

### `executeInstruction`[​](#executeinstruction "Direct link to executeinstruction")

Executes an XRPL instruction for a given XRPL address using a [Flare Data Connector](/fdc/overview) payment proof.

```
function executeInstruction(    IPayment.Proof calldata _proof,    string calldata _xrplAddress)    external payable;
```

Parameters:

-   `_proof`: Proof of the XRPL payment transaction that comes from the [Flare Data Connector](/fdc/overview).
-   `_xrplAddress`: The XRPL address that sent the payment.

### `reserveCollateral`[​](#reservecollateral "Direct link to reservecollateral")

Reserves collateral for a minting operation. Called by the executor service after receiving a collateral reservation instruction from an XRPL payment.

```
function reserveCollateral(    string calldata _xrplAddress,    bytes32 _paymentReference,    bytes32 _transactionId)    external payable    returns (uint256 _collateralReservationId);
```

Parameters:

-   `_xrplAddress`: The XRPL address requesting the collateral reservation.
-   `_paymentReference`: The payment reference from the XRPL transaction memo.
-   `_transactionId`: The unique XRPL transaction ID for tracking.

Returns:

-   `_collateralReservationId`: The ID of the collateral reservation.

### `executeDepositAfterMinting`[​](#executedepositafterminting "Direct link to executedepositafterminting")

Executes a vault deposit after minting is complete for a given collateral reservation.

```
function executeDepositAfterMinting(    uint256 _collateralReservationId,    IPayment.Proof calldata _proof,    string calldata _xrplAddress)    external;
```

Parameters:

-   `_collateralReservationId`: The ID of the collateral reservation returned by `reserveCollateral`.
-   `_proof`: Proof of the XRPL payment transaction.
-   `_xrplAddress`: The XRPL address requesting execution.

### `isTransactionIdUsed`[​](#istransactionidused "Direct link to istransactionidused")

Returns `true` if the given XRPL transaction ID has already been executed.

```
function isTransactionIdUsed(    bytes32 _transactionId)    external view    returns (bool);
```

### `getTransactionIdForCollateralReservation`[​](#gettransactionidforcollateralreservation "Direct link to gettransactionidforcollateralreservation")

Returns the XRPL transaction ID associated with a collateral reservation.

```
function getTransactionIdForCollateralReservation(    uint256 _collateralReservationId)    external view    returns (bytes32 _transactionId);
```

## Instruction Fees[​](#instruction-fees "Direct link to Instruction Fees")

### `getDefaultInstructionFee`[​](#getdefaultinstructionfee "Direct link to getdefaultinstructionfee")

Returns the default fee applied to instructions without a specific per-instruction fee configured. Denominated in the underlying asset's smallest unit (i.e., XRP drops).

```
function getDefaultInstructionFee()    external view    returns (uint256);
```

### `getInstructionFee`[​](#getinstructionfee "Direct link to getinstructionfee")

Returns the fee for a specific instruction ID (first byte on an encoded instruction).

```
function getInstructionFee(    uint256 _instructionId)    external view    returns (uint256);
```

Parameters:

-   `_instructionId`: The ID of the instruction.

## Agent Vaults[​](#agent-vaults "Direct link to Agent Vaults")

### `getAgentVaults`[​](#getagentvaults "Direct link to getagentvaults")

Returns the list of registered FAssets agent vault IDs and their corresponding addresses.

```
function getAgentVaults()    external view    returns (uint256[] memory _agentVaultIds, address[] memory _agentVaultAddresses);
```

Returns:

-   `_agentVaultIds`: The list of registered agent vault IDs.
-   `_agentVaultAddresses`: The list of registered agent vault addresses.

## Vaults[​](#vaults "Direct link to Vaults")

### `getVaults`[​](#getvaults "Direct link to getvaults")

Returns the list of registered vaults as arrays of their IDs, addresses, and types (Firelight or Upshift).

```
function getVaults()    external view    returns (        uint256[] memory _vaultIds,        address[] memory _vaultAddresses,        uint8[] memory _vaultTypes    );
```

Returns:

-   `_vaultIds`: The list of registered vault IDs.
-   `_vaultAddresses`: The list of vault addresses.
-   `_vaultTypes`: The list of vault types (`1` = Firelight, `2` = Upshift).

## Executor[​](#executor "Direct link to Executor")

### `getExecutorInfo`[​](#getexecutorinfo "Direct link to getexecutorinfo")

Returns the executor address and fee. The executor is the service that calls [`reserveCollateral`](/smart-accounts/reference/IMasterAccountController#reservecollateral) and [`executeDepositAfterMinting`](/smart-accounts/reference/IMasterAccountController#executedepositafterminting) on behalf of users.

```
function getExecutorInfo()    external view    returns (address payable _executor, uint256 _executorFee);
```

Returns:

-   `_executor`: The executor address.
-   `_executorFee`: The executor fee in wei.

## XRPL Provider Wallets[​](#xrpl-provider-wallets "Direct link to XRPL Provider Wallets")

### `getXrplProviderWallets`[​](#getxrplproviderwallets "Direct link to getxrplproviderwallets")

Returns a list of XRPL operator wallet addresses to which users send payment transactions.

```
function getXrplProviderWallets()    external view    returns (string[] memory);
```

## Payment Proofs[​](#payment-proofs "Direct link to Payment Proofs")

### `getSourceId`[​](#getsourceid "Direct link to getsourceid")

Returns the source ID used to identify the XRPL chain for payment proof verification.

```
function getSourceId()    external view    returns (bytes32);
```

### `getPaymentProofValidityDurationSeconds`[​](#getpaymentproofvaliditydurationseconds "Direct link to getpaymentproofvaliditydurationseconds")

Returns the maximum age (in seconds) of an XRPL payment proof for it to be accepted.

```
function getPaymentProofValidityDurationSeconds()    external view    returns (uint256);
```

## Memo Instructions[​](#memo-instructions "Direct link to Memo Instructions")

Memo instructions allow a [`PersonalAccount`](/smart-accounts/reference/IPersonalAccount) to execute [custom user operations](/smart-accounts/custom-instruction-comparison) embedded in the XRPL `Payment` memo when FAssets are direct-minted into the account.

### `handleMintedFAssets`[​](#handlemintedfassets "Direct link to handlemintedfassets")

Called by the FAssets `AssetManager` when FXRP is direct-minted into a personal account. Decodes the XRPL memo, distributes the minted FAssets between the personal account and the executor, and dispatches the custom instruction. For the [`0xFE` custom instruction](/smart-accounts/custom-instruction), the `_data` parameter carries the ABI-encoded `PackedUserOperation` whose hash was committed to in the memo. See [Custom Instruction Comparison](/smart-accounts/custom-instruction-comparison) for the end-to-end flow.

```
function handleMintedFAssets(    bytes32 _transactionId,    string calldata _sourceAddress,    uint256 _amount,    uint256 _underlyingTimestamp,    bytes calldata _memoData,    address payable _executor,    bytes calldata _data)    external payable;
```

Parameters:

-   `_transactionId`: The XRPL transaction ID for replay protection.
-   `_sourceAddress`: The XRPL source address that triggered the mint.
-   `_amount`: The total minted FAsset amount, in the FAsset's smallest unit (XRP drops for FXRP).
-   `_underlyingTimestamp`: The XRPL transaction timestamp.
-   `_memoData`: The raw XRPL memo bytes carrying the [memo instruction](/smart-accounts/custom-instruction-comparison).
-   `_executor`: The executor address; must equal the personal account's pinned executor when one is set.
-   `_data`: Extra data not contained in the XRPL memo. For the `0xFE` custom instruction this is the ABI-encoded `PackedUserOperation`; for all other instruction IDs it is ignored.

The `AssetManager` is the only address allowed to call this function — any other caller reverts with [`OnlyAssetManager`](#onlyassetmanager).

### `getNonce`[​](#getnonce "Direct link to getnonce")

Returns the current memo-instruction nonce for a personal account. A `PackedUserOperation`'s `nonce` field must equal this value to be accepted; the nonce auto-increments on every successful execution.

Nonce collisions

Only one user operation can consume a given nonce. If several XRPL flows or off-chain builders read the same `getNonce` value and each embeds a **different** `PackedUserOperation` with that nonce, whichever mint executes first succeeds and increments the nonce; the others revert with [`InvalidNonce`](#invalidnonce).

```
function getNonce(    address _personalAccount)    external view    returns (uint256);
```

Parameters:

-   `_personalAccount`: The personal account address to query.

### `getExecutor`[​](#getexecutor "Direct link to getexecutor")

Returns the executor pinned to a personal account, or `address(0)` if no executor is pinned. When set, only that executor can deliver memos to the account (except for the executor-management memos `0xD0` and `0xD1`).

```
function getExecutor(    address _personalAccount)    external view    returns (address);
```

Parameters:

-   `_personalAccount`: The personal account address to query.

## Events[​](#events "Direct link to Events")

### Instructions[​](#instructions-1 "Direct link to Instructions")

#### `CollateralReserved`[​](#collateralreserved "Direct link to collateralreserved")

Emitted when collateral is reserved for minting.

```
event CollateralReserved(    address indexed personalAccount,    bytes32 indexed transactionId,    bytes32 indexed paymentReference,    string xrplOwner,    uint256 collateralReservationId,    address agentVault,    uint256 lots,    address executor,    uint256 executorFee);
```

#### `InstructionExecuted`[​](#instructionexecuted "Direct link to instructionexecuted")

Emitted when an instruction is executed.

```
event InstructionExecuted(    address indexed personalAccount,    bytes32 indexed transactionId,    bytes32 indexed paymentReference,    string xrplOwner,    uint256 instructionId);
```

#### `FXrpRedeemed`[​](#fxrpredeemed "Direct link to fxrpredeemed")

Emitted when an FXRP redemption is performed.

```
event FXrpRedeemed(    address indexed personalAccount,    uint256 lots,    uint256 amount,    address executor,    uint256 executorFee);
```

#### `FXrpTransferred`[​](#fxrptransferred "Direct link to fxrptransferred")

Emitted when FXRP is transferred from a personal account.

```
event FXrpTransferred(    address indexed personalAccount,    address to,    uint256 amount);
```

#### `Approved`[​](#approved "Direct link to approved")

Emitted when a token approval is made for a vault.

```
event Approved(    address indexed personalAccount,    address fxrp,    address vault,    uint256 amount);
```

#### `Deposited`[​](#deposited "Direct link to deposited")

Emitted when a deposit is made to a vault.

```
event Deposited(    address indexed personalAccount,    address indexed vault,    uint256 amount,    uint256 shares);
```

#### `Redeemed`[​](#redeemed "Direct link to redeemed")

Emitted when a redemption is made from a vault.

```
event Redeemed(    address indexed personalAccount,    address indexed vault,    uint256 shares,    uint256 amount);
```

#### `WithdrawalClaimed`[​](#withdrawalclaimed "Direct link to withdrawalclaimed")

Emitted when a withdrawal claim is completed.

```
event WithdrawalClaimed(    address indexed personalAccount,    address indexed vault,    uint256 period,    uint256 amount);
```

#### `RedeemRequested`[​](#redeemrequested "Direct link to redeemrequested")

Emitted when a redeem request is made from a vault.

```
event RedeemRequested(    address indexed personalAccount,    address indexed vault,    uint256 shares,    uint256 claimableEpoch,    uint256 year,    uint256 month,    uint256 day);
```

#### `Claimed`[​](#claimed "Direct link to claimed")

Emitted when a claim is made for a specific date.

```
event Claimed(    address indexed personalAccount,    address indexed vault,    uint256 year,    uint256 month,    uint256 day,    uint256 shares,    uint256 amount);
```

### Memo Instructions[​](#memo-instructions-1 "Direct link to Memo Instructions")

#### `UserOperationExecuted`[​](#useroperationexecuted "Direct link to useroperationexecuted")

Emitted when a memo-dispatched user operation (`0xFF` memo field custom instruction or `0xFE` custom instruction) executes against the personal account.

```
event UserOperationExecuted(    address indexed personalAccount,    uint256 nonce);
```

Parameters:

-   `personalAccount`: The personal account that ran the user operation.
-   `nonce`: The nonce consumed by the user operation.

#### `IgnoreMemoSet`[​](#ignorememoset "Direct link to ignorememoset")

Emitted when an `0xE0` memo marks a target XRPL transaction's memo to be skipped on its next direct mint.

```
event IgnoreMemoSet(    address indexed personalAccount,    bytes32 indexed targetTxId);
```

Parameters:

-   `personalAccount`: The personal account that owns the ignore flag.
-   `targetTxId`: The XRPL transaction ID whose memo will be skipped.

#### `NonceIncreased`[​](#nonceincreased "Direct link to nonceincreased")

Emitted when an `0xE1` memo fast-forwards the personal account's memo-instruction nonce.

```
event NonceIncreased(    address indexed personalAccount,    uint256 newNonce);
```

Parameters:

-   `personalAccount`: The personal account whose nonce was advanced.
-   `newNonce`: The new nonce value.

#### `ExecutorSet`[​](#executorset "Direct link to executorset")

Emitted when an `0xD0` memo pins an executor to the personal account.

```
event ExecutorSet(    address indexed personalAccount,    address indexed executor);
```

Parameters:

-   `personalAccount`: The personal account.
-   `executor`: The pinned executor address.

#### `ExecutorRemoved`[​](#executorremoved "Direct link to executorremoved")

Emitted when an `0xD1` memo unpins the executor from the personal account.

```
event ExecutorRemoved(    address indexed personalAccount);
```

Parameters:

-   `personalAccount`: The personal account whose executor was cleared.

#### `ReplacementFeeSet`[​](#replacementfeeset "Direct link to replacementfeeset")

Emitted when an `0xE2` memo sets a replacement executor fee for a stuck XRPL transaction.

```
event ReplacementFeeSet(    address indexed personalAccount,    bytes32 indexed targetTxId,    uint64 newFee);
```

Parameters:

-   `personalAccount`: The personal account.
-   `targetTxId`: The XRPL transaction ID whose fee is being replaced.
-   `newFee`: The new executor fee, in the FAsset's smallest unit.

#### `DirectMintingExecuted`[​](#directmintingexecuted "Direct link to directmintingexecuted")

Emitted when direct minting credits FAssets to a personal account.

```
event DirectMintingExecuted(    address indexed personalAccount,    bytes32 indexed transactionId,    string sourceAddress,    uint256 amount,    uint256 executorFee,    address executor);
```

Parameters:

-   `personalAccount`: The recipient personal account.
-   `transactionId`: The XRPL transaction ID.
-   `sourceAddress`: The XRPL source address that triggered the mint.
-   `amount`: The total minted amount (before deducting the executor fee).
-   `executorFee`: The fee paid to the executor.
-   `executor`: The executor address that delivered the mint.

## Errors[​](#errors "Direct link to Errors")

### Memo Instructions[​](#memo-instructions-2 "Direct link to Memo Instructions")

These errors are surfaced by [`handleMintedFAssets`](#handlemintedfassets) and the memo dispatch path.

#### `TransactionAlreadyExecuted`[​](#transactionalreadyexecuted "Direct link to transactionalreadyexecuted")

Thrown when an XRPL transaction ID has already been processed.

```
error TransactionAlreadyExecuted();
```

#### `OnlyAssetManager`[​](#onlyassetmanager "Direct link to onlyassetmanager")

Thrown when [`handleMintedFAssets`](#handlemintedfassets) is called by any address other than the FAssets `AssetManager`.

```
error OnlyAssetManager();
```

#### `InsufficientAmountForFee`[​](#insufficientamountforfee "Direct link to insufficientamountforfee")

Thrown when the minted amount is smaller than the executor fee.

```
error InsufficientAmountForFee(    uint256 amount,    uint256 fee);
```

Parameters:

-   `amount`: The minted amount.
-   `fee`: The executor fee.

#### `WrongExecutor`[​](#wrongexecutor "Direct link to wrongexecutor")

Thrown when the delivered executor does not match the executor pinned to the personal account.

```
error WrongExecutor(    address expected,    address actual);
```

Parameters:

-   `expected`: The executor pinned via [`getExecutor`](#getexecutor).
-   `actual`: The executor that delivered the mint.

#### `InvalidMemoData`[​](#invalidmemodata "Direct link to invalidmemodata")

Thrown when the memo payload does not match the expected length for the given memo instruction ID.

```
error InvalidMemoData();
```

#### `InvalidInstructionId`[​](#invalidinstructionid "Direct link to invalidinstructionid")

Thrown when the first byte of the memo is not a recognized memo instruction ID (`0xFF`, `0xFE`, `0xE0`, `0xE1`, `0xE2`, `0xD0`, `0xD1`).

```
error InvalidInstructionId(    uint8 instructionId);
```

Parameters:

-   `instructionId`: The unrecognized memo instruction ID.

#### `CustomInstructionHashMismatch`[​](#custominstructionhashmismatch "Direct link to custominstructionhashmismatch")

Thrown by the [`0xFE` custom instruction](/smart-accounts/custom-instruction) when `keccak256(_data)` does not match the 32-byte hash carried in the XRPL memo.

```
error CustomInstructionHashMismatch(    bytes32 expected,    bytes32 actual);
```

Parameters:

-   `expected`: The hash committed to in the memo.
-   `actual`: The hash of the supplied `_data`.

#### `InvalidSender`[​](#invalidsender "Direct link to invalidsender")

Thrown when the `sender` field of the embedded `PackedUserOperation` does not match the personal account derived from the XRPL source address.

```
error InvalidSender(    address sender,    address personalAccount);
```

Parameters:

-   `sender`: The sender field of the user operation.
-   `personalAccount`: The expected personal account address.

#### `InvalidNonce`[​](#invalidnonce "Direct link to invalidnonce")

Thrown when the `nonce` field of the embedded `PackedUserOperation` does not equal the personal account's current nonce.

```
error InvalidNonce(    uint256 expected,    uint256 actual);
```

Parameters:

-   `expected`: The nonce currently stored for the personal account.
-   `actual`: The nonce supplied in the user operation.

#### `InvalidNonceIncrease`[​](#invalidnonceincrease "Direct link to invalidnonceincrease")

Thrown by an `0xE1` memo when the requested nonce is not strictly greater than the current nonce, or jumps by more than `type(uint32).max`.

```
error InvalidNonceIncrease(    uint256 currentNonce,    uint256 newNonce);
```

Parameters:

-   `currentNonce`: The current nonce value.
-   `newNonce`: The requested new nonce value.

#### `CallFailed`[​](#callfailed "Direct link to callfailed")

Thrown when the `callData` carried by the user operation reverts when invoked on the personal account.

```
error CallFailed(    bytes returnData);
```

Parameters:

-   `returnData`: The raw return data from the failed call.

#### `AddressZero`[​](#addresszero "Direct link to addresszero")

Thrown when an address parsed from a memo payload (for example, the executor in an `0xD0` memo) is the zero address.

```
error AddressZero();
```

#### `ValueZero`[​](#valuezero "Direct link to valuezero")

Thrown when a value parsed from a payment reference is zero.

```
error ValueZero();
```