Cross-Chain Portal Smart Contract

Overview

The Cross-Chain Portal is a Clarity smart contract that enables secure cross-chain asset transfers between Stacks and other blockchain networks (Ethereum, BSC, Polygon). It implements a multi-signature validation system to ensure transfer security and integrity.

Key Features

• Multi-Chain Support: Transfer assets to/from Ethereum (chain ID: 1), BSC (56), and Polygon (137)
• Multi-Signature Validation: Requires multiple verifier approvals before finalizing transfers
• Configurable Limits: Adjustable minimum/maximum transfer amounts and fees
• Emergency Controls: Admin can pause the portal and perform emergency withdrawals
• Duplicate Prevention: Prevents processing the same transaction multiple times
• Transaction Tracking: Complete audit trail of all movements

Architecture

Constants

• ADMIN_ADDRESS: Contract owner with administrative privileges
• Error Codes: (u100-u109) for various failure scenarios

Configuration Variables

Variable	Default Value	Description
portal-suspended	false	Portal operational status
minimum-movement-amount	1,000,000 μSTX (1 STX)	Minimum transfer amount
maximum-movement-amount	100,000,000,000 μSTX (1,000 STX)	Maximum transfer amount
portal-charge	10,000 μSTX (0.01 STX)	Fee per transfer
needed-approvals	3	Required verifier signatures

Core Functions

Administrative Functions

register-verifier (verifier principal)

Adds a new verifier to the multi-signature system.

• Access: Admin only
• Returns: (ok true) on success

deregister-verifier (verifier principal)

Removes a verifier from the system.

• Access: Admin only
• Returns: (ok true) on success

update-portal-suspension (paused bool)

Pauses or resumes portal operations.

• Access: Admin only
• Use Case: Emergency situations or maintenance

update-movement-boundaries (min-amount uint) (max-amount uint)

Sets transfer limits.

• Access: Admin only
• Constraints:
  • min > 0
  • max > min
  • max ≤ 10,000 STX

update-portal-charge (fee uint)

Updates the transfer fee.

• Access: Admin only
• Maximum: 1 STX

update-needed-approvals (count uint)

Changes required verifier approvals.

• Access: Admin only
• Range: 1-10 signatures

register-permitted-blockchain (chain-id uint)

Adds support for a new blockchain.

• Access: Admin only
• Valid Range: 1-1,000,000

User Functions

begin-movement (amount uint) (target-chain uint) (recipient buff)

Initiates a cross-chain transfer.

Parameters:

• amount: Transfer amount in μSTX
• target-chain: Destination blockchain ID
• recipient: Destination address (max 32 bytes)

Process:

1. Validates amount is within limits
2. Checks target chain is supported
3. Transfers STX + fee to contract
4. Creates pending movement record
5. Returns unique movement ID

Example:

(begin-movement u5000000 u1 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb)
;; Transfers 5 STX to Ethereum address

approve-movement (transfer-id uint)

Verifier approves a pending transfer.

Process:

1. Validates caller is a registered verifier
2. Records approval
3. If threshold reached, finalizes transfer
4. Returns true if finalized, false if more approvals needed

Example:

(approve-movement u42)
;; Verifier approves transfer #42

finalize-arriving-movement (amount uint) (recipient principal) (source-chain uint) (tx-hash buff)

Completes an incoming transfer from another blockchain.

Parameters:

• amount: Amount in μSTX
• recipient: Stacks address to receive funds
• source-chain: Origin blockchain ID
• tx-hash: Transaction hash from source chain (32 bytes)

Access: Verifiers only

Process:

1. Validates transaction hasn't been processed
2. Marks transaction as completed
3. Transfers STX to recipient
4. Updates locked amount tracker

Emergency Functions

critical-extraction (amount uint)

Emergency withdrawal of contract funds.

• Access: Admin only
• Use Case: Critical situations requiring fund recovery

Read-Only Functions

fetch-movement-details (transfer-id uint)

Returns complete information about a pending movement.

Returns:

{
  sender: principal,
  amount: uint,
  target-chain: uint,
  recipient: (buff 32),
  block-height: uint
}

fetch-approval-tally (transfer-id uint)

Returns number of verifier approvals for a transfer.

check-verifier-status (address principal)

Checks if an address is a registered verifier.

check-blockchain-permitted (chain-id uint)

Checks if a blockchain is supported.

fetch-portal-settings ()

Returns current portal configuration.

Returns:

{
  bridge-paused: bool,
  min-transfer: uint,
  max-transfer: uint,
  bridge-fee: uint,
  required-sigs: uint,
  total-locked: uint
}

check-operation-completed (chain-id uint) (tx-hash buff)

Checks if a transaction has been processed.

fetch-contract-holdings ()

Returns total STX held by contract.

fetch-subsequent-movement-id ()

Returns the next movement ID.

check-verifier-approval (transfer-id uint) (validator principal)

Checks if a specific verifier has approved a transfer.

Workflow Examples

Outgoing Transfer (Stacks → Ethereum)

1. User Initiates:

   (begin-movement u10000000 u1 0xRecipientAddress)
   ;; Returns movement ID: u123

2. Verifiers Approve (3 required):

   (approve-movement u123) ;; Verifier 1
   (approve-movement u123) ;; Verifier 2
   (approve-movement u123) ;; Verifier 3 - Finalizes

3. Off-chain relayer completes transfer on Ethereum

Incoming Transfer (Ethereum → Stacks)

1. User locks tokens on Ethereum bridge
2. Verifier detects and finalizes:

   (finalize-arriving-movement 
     u10000000 
     'SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ7
     u1
     0xEthereumTxHash)

Security Features

Multi-Signature Protection

• Configurable threshold (default: 3 signatures)
• Prevents single point of failure
• Each verifier can only approve once per transfer

Duplicate Prevention

• Tracks processed transactions by chain ID + tx hash
• Prevents replay attacks
• Verifiers cannot sign same transfer twice

Amount Limits

• Minimum: 1 STX (prevents spam)
• Maximum: 1,000 STX (limits risk exposure)
• Adjustable by admin

Emergency Controls

• Portal suspension capability
• Emergency withdrawal function
• Admin-only critical functions

Validation Checks

• Balance verification before transfers
• Chain support validation
• Input sanitization (buffer lengths, numeric ranges)
• Authorization checks on all privileged functions

Error Codes

Code	Constant	Description
u100	ERROR_NOT_AUTHORIZED	Caller lacks permission
u101	ERROR_AMOUNT_INVALID	Amount outside allowed range
u102	ERROR_PORTAL_SUSPENDED	Portal is paused
u103	ERROR_BALANCE_TOO_LOW	Insufficient STX balance
u104	ERROR_CHAIN_NOT_SUPPORTED	Invalid target blockchain
u105	ERROR_TRANSACTION_DUPLICATE	Transaction already processed
u106	ERROR_VERIFIER_ALREADY_EXISTS	Verifier already registered
u107	ERROR_NOT_A_VERIFIER	Caller is not a verifier
u108	ERROR_APPROVALS_INSUFFICIENT	Not enough signatures yet
u109	ERROR_INPUT_INVALID	Invalid input parameters

Supported Blockchains

• Ethereum: Chain ID 1
• BSC: Chain ID 56
• Polygon: Chain ID 137

Additional chains can be added via register-permitted-blockchain.

Deployment

Upon deployment:

1. Admin address is set to deployer (tx-sender)
2. Admin is automatically registered as first verifier
3. Default chains (Ethereum, BSC, Polygon) are activated
4. Default configuration values are set

Best Practices

1. For Admins:

   • Maintain at least 3-5 trusted verifiers
   • Set needed-approvals to at least 60% of verifier count
   • Regularly review and update verifiers
   • Use update-portal-suspension during upgrades

2. For Users:

   • Verify target chain ID before transfer
   • Ensure recipient address is correct (irreversible)
   • Account for portal fees in transfer amount
   • Save movement ID for tracking

3. For Verifiers:

   • Verify off-chain transaction proof before approving
   • Never approve without independent verification
   • Monitor for unusual patterns