flare-fcc-solidity-test
v0.1.0
Published
Solidity library for Flare Confidential Compute application-contract integration.
Maintainers
Readme
flare-fcc-solidity-test
Foundry / Hardhat import:
import {Fcc} from "flare-fcc-solidity-test/src/FCC.sol";Fcc is a library, not a deployed contract. It wraps Flare Confidential Compute protocol plumbing so application contracts only keep permissions, payloads, and what a result means.
API reference for src/FCC.sol is below. Architecture and the TypeScript client live in the repository README.
Scope
| This library does | Application contract does |
|---|---|
| Resolve Coston2 FlareTeeManager facet addresses | Own Fcc.Extension storage, or inherit optional FccApp |
| Look up / bind a public extension id | Decide who may call execute |
| Select production TEEs (getRandomTeeIds) | Encode the payload |
| Resolve the unique production TEE (getActiveTeeMachines) | Pin teeAddress when more than one machine is active |
| Check native instruction fee | Forward msg.value from a payable function |
| Call sendInstructions (including explicit claim-back) | Interpret ActionResult.data |
| Recover / verify TEE signatures; consumeResult replay helper | Map success to business state |
Coston2-only for now. TeeExtensionRegistry and TeeMachineRegistry are facets of the FlareTeeManager diamond (Fcc.FLARE_TEE_MANAGER). Do not pass those addresses in. Once FCC is listed in FlareContractRegistry, this library can resolve them by name per network.
execute is asynchronous: it submits an instruction and returns instructionId. Results arrive later. Watch TeeInstructionsSent on the diamond — the library does not emit a duplicate event.
Constants
| Name | Value | Meaning |
|---|---|---|
| FIRST_PUBLIC_EXTENSION_ID | 0x10000 | First id assigned to public (non-system) extensions. findExtensionId scans from here. |
| FLARE_TEE_MANAGER | 0x1a9C4A0f9D76c0b1D91d22E24E573a9b377618aE | Coston2 FlareTeeManager diamond. Both registries are facets of this address. |
extensionRegistry() and machineRegistry() both return FLARE_TEE_MANAGER.
Types
Fcc.Extension
Binding to a registered Flare Compute Extension.
| Field | Type | Notes |
|---|---|---|
| extensionRegistry | address | Filled by createExtension (diamond). |
| machineRegistry | address | Filled by createExtension (same diamond). |
| extensionId | uint256 | Public extension id. May be 0 until setExtensionId. |
Store this on the application contract. Use using Fcc for Fcc.Extension.
Fcc.ExecutionParams
Arguments for executeAdvanced. Empty teeIds selects randomly.
| Field | Type | Notes |
|---|---|---|
| opType | bytes32 | Required. e.g. bytes32("WEATHER"). |
| opCommand | bytes32 | Required. e.g. bytes32("SETTLE"). |
| payload | bytes | Required, non-empty. ABI-encoded message for the extension. |
| teeCount | uint256 | Used only when teeIds is empty. Must be > 0 in that case. |
| teeIds | address[] | Explicit TEE ids. Empty ⇒ getRandomTeeIds(extensionId, teeCount). |
| cosigners | address[] | Optional extra signers. |
| cosignersThreshold | uint64 | Threshold over cosigners. |
| claimBackAddress | address | Refund / claim-back. Zero ⇒ msg.sender. |
Fcc.ActionResult
TEE result fields used for on-chain verification. Hashing matches tee-node.
| Field | Type | Notes |
|---|---|---|
| data | bytes | Application-specific result payload. |
| id | bytes32 | Action / instruction id (ActionResult.id). |
| submissionTag | string | Tag included in the signed hash. |
| status | uint8 | 0 = error, 1 = success, >= 2 = pending. |
Functions
Binding
function createExtension(uint256 extensionId) internal view returns (Extension memory);
function findExtensionId(address sender) internal view returns (uint256);
function lookupExtensionId(Extension storage) internal view returns (uint256);
function setExtensionId(Extension storage self) internal returns (uint256 id);createExtension(extensionId) — Fills registry addresses from this library. Pass a known public id, or 0 to bind later with setExtensionId. Reverts InvalidExtension if the diamond has no code.
findExtensionId(sender) — Scans [FIRST_PUBLIC_EXTENSION_ID, nextPublicExtensionId) for the registered instructions sender. Reverts InvalidExtension if sender is zero or no match.
lookupExtensionId — findExtensionId(address(this)). The storage argument is unused.
setExtensionId — Discovers this contract’s public id and stores it. Call after the diamond registers address(this) as the instructions sender. Can only be set once (ExtensionIdAlreadySet). Reverts InvalidExtension if unregistered.
Fcc.Extension private extension;
constructor() {
extension = Fcc.createExtension(0);
}
function bindExtension() external {
extension.setExtensionId();
}Fees
function getExecutionFee(bytes32 opType, bytes32 opCommand) internal view returns (uint256);Reads IOperationFees.getOperationFee on the diamond. Call from a payable function and forward at least this much as msg.value. Solidity cannot use {value: msg.value} on a library / struct call — the outer function must be payable so msg.value is already attached.
Execute
function execute(Extension memory self, bytes32 opType, bytes32 opCommand, bytes memory payload)
internal
returns (bytes32 instructionId);
function execute(Extension memory self, bytes32 opType, bytes32 opCommand, bytes memory payload, address claimBack)
internal
returns (bytes32 instructionId);
function executeAdvanced(Extension memory self, ExecutionParams memory params)
internal
returns (bytes32 instructionId);execute — One randomly selected production TEE, no cosigners. The 3-arg form sets claimBackAddress = msg.sender. The 4-arg form takes an explicit claim-back (zero still falls back to msg.sender). Forwards msg.value as the native instruction fee.
executeAdvanced — Same sendInstructions path with explicit TEE ids, cosigners, and claim-back. If teeIds is empty, selects teeCount machines via getRandomTeeIds. Any revert from that call (including TooMany) becomes TeeMachineNotAvailable.
extensionId must already be set. Results are not returned here; watch TeeInstructionsSent on the diamond and fetch the ActionResult off-chain (or relay it back for verifyResult).
using Fcc for Fcc.Extension;
function requestSettlement(uint256 policyId) external payable returns (bytes32 instructionId) {
instructionId = weatherExtension.execute(
bytes32("WEATHER"),
bytes32("SETTLE"),
abi.encode(policyId)
);
}weatherExtension.executeAdvanced(
Fcc.ExecutionParams({
opType: OP_TYPE,
opCommand: OP_COMMAND,
payload: payload,
teeCount: 1,
teeIds: new address[](0), // empty => getRandomTeeIds
cosigners: cosigners,
cosignersThreshold: 1,
claimBackAddress: msg.sender
})
);Verify
function verifyResult(
address expectedTeeId,
bytes calldata resultData,
bytes32 actionId,
string calldata submissionTag,
uint8 status,
bytes calldata signature
) internal view;
function verifyResult(address expectedTeeId, ActionResult memory result, bytes memory signature)
internal view;
function recoverResultSigner(ActionResult memory result, bytes memory signature)
internal view
returns (address);Optional. Use only if the application relays a signed ActionResult on-chain (e.g. a settle entrypoint).
verifyResult reverts unless:
expectedTeeId != address(0)status == 1- recovered signer ==
expectedTeeId - signature is a valid 65-byte ECDSA sig
The unpacked-fields overload is for relay entrypoints so callers do not assemble the struct.
function settle(
bytes calldata resultData,
bytes32 actionId,
string calldata submissionTag,
uint8 status,
bytes calldata signature
) external {
Fcc.verifyResult(teeAddress, resultData, actionId, submissionTag, status, signature);
// decode, auth / unlock checks, then:
Fcc.consumeResult(usedResults, actionId);
// apply app logic
}Production TEE ids
function getActiveTeeIds(Extension memory self) internal view returns (address[] memory teeIds);
function resolveTeeAddress(Extension memory self) internal view returns (address);
function consumeResult(mapping(bytes32 => bool) storage used, bytes32 actionId) internal;getActiveTeeIds — Wraps diamond getActiveTeeMachines. Use this to pin or check the verifier, not getRandomTeeIds (random, may disagree with the signer).
resolveTeeAddress — Unique production TEE id. Reverts TeeMachineNotAvailable if none, AmbiguousTee if more than one. Pin with setTeeAddress when several machines are active.
consumeResult — Marks actionId used. Reverts ResultAlreadyUsed if zero or already consumed. Call after auth / unlock checks; do not fold it into verifyResult.
Optional FccApp
src/FccApp.sol is an abstract InstructionSender: extension storage, setExtensionId / lookupExtensionId (unrestricted), teeAddress, setTeeAddress / syncTeeAddress (gated by _authorizeFccConfig), _execute / _execute(..., claimBack), _requireTeeResult, _consumeResult.
import {FccApp} from "flare-fcc-solidity-test/src/FccApp.sol";
contract WeatherInsurance is FccApp {
address public owner;
constructor() FccApp(0) {
owner = msg.sender;
}
function _authorizeFccConfig() internal view override {
require(msg.sender == owner, "not owner");
}
}ActionResult signature
tee-node signs an EIP-191 personal message over a 32-byte payload hash:
resultHash = keccak256( keccak256(data) || id || keccak256(utf8(submissionTag)) || status )
payloadHash = keccak256( abi.encode(bytes32("TEE_ACTION_RESULT"), chainid, resultHash) )
digest = keccak256( "\x19Ethereum Signed Message:\n32" || payloadHash )recoverResultSigner / verifyResult recover ecrecover(digest, v, r, s) from a 65-byte r || s || v signature (v accepted as 27/28 or 0/1).
Errors
Custom errors from src/libraries/FccErrors.sol plus FlareTeeManager facet errors from @flarenetwork/flare-periphery-contracts:
| Error | Source | When |
|---|---|---|
| InvalidExtension | Fcc | Diamond has no code; zero sender/registry; extension binding incomplete (extensionId == 0); or instructions sender not found. |
| ExtensionIdAlreadySet | Fcc | setExtensionId called when extensionId != 0. |
| InvalidTeeCount | Fcc | teeIds empty and teeCount == 0. |
| TeeMachineNotAvailable | ITeeCommonErrors | getRandomTeeIds reverted or returned an empty list; or resolveTeeAddress found none. |
| FeeTooLow | IInstructions | msg.value below getOperationFee(opType, opCommand). |
| OperationTypeEmpty | IInstructions | opType == bytes32(0). |
| OperationCommandEmpty | IInstructions | opCommand == bytes32(0). |
| MessageEmpty | IInstructions | payload length is 0. |
| InvalidResultSignature | Fcc | Signature length ≠ 65, invalid v, or ecrecover returned zero. |
| InvalidResultSigner | Fcc | Recovered signer ≠ expectedTeeId. |
| ResultNotSuccessful | Fcc | status != 1. |
| TeeAddressNotSet | Fcc | expectedTeeId == address(0). |
| ResultAlreadyUsed | Fcc | consumeResult on a zero or already-marked actionId. |
| AmbiguousTee | Fcc | resolveTeeAddress when more than one production TEE is active. |
The diamond may still revert with its own errors (OnlyInstructionsSender, TooMany, …) after the library checks pass.
When not to use this library
Use FlareTeeManager / facet APIs directly for:
- extension registration, TEE machine registration, governance, allowlists
F_*system operations (F_GET,F_WALLET,F_FDC2, …)sendSystemInstructions- anything that is not “submit an app instruction” or “verify a signed ActionResult”
