Skip to main content
API docs by Redocly

Energy Factory Smart Contract (1.0.0)

Download OpenAPI specification:Download

URL: https://defi.bitcoin.me

The Energy Factory smart contract manages the XKFI token system and energy accumulation mechanism in Bitcoin.me DeFi.

Overview

XKFI is the locked version of KFI token. By locking KFI tokens for a specific period (1, 2, or 4 years), accounts accumulate Energy which provides various benefits including fee collection and protocol rewards.

XKFI Token

When locking KFI, users receive an XKFI SFT with metadata containing:

  • original_token_id: The original token ID (e.g., KFI)
  • original_token_nonce: The SFT nonce
  • unlock_epoch: Epoch when KFI will be available for unlock

Endpoints

Write operations that modify contract state

Lock Tokens

Lock KFI tokens until a specified unlock epoch and receive XKFI SFT tokens at a 1:1 ratio.

Accepted input token types:

  • Base asset token (KFI)
  • Token from old factory (extends all periods to the provided option)
  • Previously locked token (extends period to the provided option)

Process:

  1. Verifies contract is not paused and lock option is valid
  2. Gets payment (KLV or KDA token)
  3. Calculates unlock_epoch (must be greater than current epoch)
  4. Locks token according to type and conditions
  5. Sends LOCKED tokens to destination address

Note: If a lockTokens has the same metadata, amount is added to the existing SFT instead of creating a new one with a different nonce.

Request Body schema: application/json
required
scAddress
required
string

Energy Factory contract address

funcName
required
string
Value: "lockTokens"
args
required
Array of strings

Arguments in hexadecimal:

  • lock_epochs (required): Number of epochs for locking. Must be one of the available lock options (query getLockOptions)
  • opt_destination (optional): Destination address for LOCKED tokens (defaults to caller)

Responses

Request samples

Content type
application/json
Example
{
  • "scAddress": "klv1qqqqqqqqqqqqqpgq9696g7x76kwrrh02fahn4rpem4v595t8c0nqgxzpmu",
  • "funcName": "lockTokens",
  • "args": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "error": "string",
  • "code": "string"
}

Unlock Tokens

Unlock tokens that were previously locked using lockTokens.

Expected Payment: LOCKED (XKFI) tokens

Process:

  1. Verifies contract is not paused
  2. Gets current epoch and caller address
  3. Initializes output payment representing unlocked tokens
  4. Updates caller's energy:
    • Gets non-empty payments and verifies all are the same token
    • For each payment, retrieves locked token attributes and unlocks
    • Updates energy based on unlocked amount and unlock epoch
    • Merges unlocked tokens to output payment
  5. Sends unlocked tokens to caller address
Request Body schema: application/json
required
scAddress
required
string

Energy Factory contract address

funcName
required
string
Value: "unlockTokens"
args
Array of strings

No arguments required (payment is the LOCKED tokens)

Responses

Request samples

Content type
application/json
{
  • "scAddress": "string",
  • "funcName": "unlockTokens",
  • "args": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "error": "string",
  • "code": "string"
}

Extend Lock Period

Extend the lock period for tokens. Used internally by proxy-dex.

Expected Payment: KDA payment (must be a locked token)

Requirements:

  • Contract must not be paused
  • Lock option must be valid
  • Caller must be in token transfer whitelist

Process:

  1. Verifies contract is not paused and lock option is valid
  2. Gets caller address and verifies it's in token transfer whitelist
  3. Gets payment and verifies it's the correct type
  4. Calculates unlock_epoch (must be greater than current epoch)
  5. Updates user energy, extending token lock period
  6. Sends corresponding tokens back to caller
Request Body schema: application/json
required
scAddress
required
string
funcName
required
string
Value: "extendLockPeriod"
args
required
Array of strings
  • lock_epochs: Number of epochs for locking
  • user: User address whose lock period will be extended

Responses

Request samples

Content type
application/json
{
  • "scAddress": "string",
  • "funcName": "extendLockPeriod",
  • "args": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "error": "string",
  • "code": "string"
}

Unlock Early (with penalty)

Instantly unlock locked tokens with a penalty. The penalty increases with remaining lock time.

Expected Payment: KDA payment (XKFI tokens)

Process:

  1. Verifies contract is not paused
  2. Gets caller and determines user with energy from optional parameter
  3. Performs common lock period reduction using received payment
  4. Converts unlocked tokens to KDA payment format
  5. Calculates amount to burn based on penalty applied to payment value
  6. Updates tokens to burn amount
  7. Updates user energy with new energy entry
  8. Unbonds tokens from user
  9. Returns unlocked tokens

Penalty Calculation:

  • Penalty percentage increases with longer remaining lock periods
  • Query getPenaltyAmount to calculate exact penalty before calling

Example Response (receipts):

{
  "assetId": "XKFI-2AR6/2",
  "assetType": "SemiFungible",
  "from": "klv17e8zzgn73h6ehe3c6q9vlt77kuxk5euddmhymy5uhv2rhv0dc0nqlfp0ap",
  "to": "klv1qqqqqqqqqqqqqpgq9696g7x76kwrrh02fahn4rpem4v595t8c0nqgxzpmu",
  "value": 100000000
}
Request Body schema: application/json
required
scAddress
required
string
funcName
required
string
Value: "unlockEarly"
args
Array of strings
  • opt_user_with_energy (optional): Address of the user with energy (defaults to caller)

Responses

Request samples

Content type
application/json
{
  • "scAddress": "klv1qqqqqqqqqqqqqpgq9696g7x76kwrrh02fahn4rpem4v595t8c0nqgxzpmu",
  • "funcName": "unlockEarly",
  • "args": [ ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "error": "string",
  • "code": "string"
}