Collaborative Asset Vault

A secure multi-signature smart contract for the Stacks blockchain that enables collaborative governance of digital assets through a trustee-based voting system.

Overview

The Collaborative Asset Vault implements a decentralized treasury management system where a primary owner controls day-to-day operations, while a group of trusted parties (trustees) can collectively vote to transfer ownership in emergency situations or planned transitions.

Key Features

• Owner-Controlled Operations: Primary owner has exclusive rights to transfer STX and fungible tokens
• Trustee Governance: Designated trustees can initiate and vote on ownership changes
• Configurable Voting Threshold: Customizable percentage of trustee votes required for ownership transfer
• Time-Limited Proposals: Voting periods expire after 3 days to prevent indefinite proposals
• Emergency Recovery: Enables asset recovery if the owner becomes unavailable

Contract Architecture

Core Roles

• Vault Owner: Primary controller with transfer privileges
• Trustees: Authorized parties who can vote on ownership changes
• Vote Initiator: Any trustee can propose ownership transfers

State Management

The contract maintains several key state variables:

• Vault readiness status and owner identity
• Trustee registry and count
• Active voting sessions with deadlines
• Vote tallies and approval tracking

Function Reference

Setup Functions

initialize-vault(new-owner, initial-threshold)

Initializes the vault with an owner and voting threshold.

• Parameters:
  • new-owner: Principal address of the vault owner
  • initial-threshold: Percentage (1-100) of trustees required for votes
• Access: Anyone (one-time only)

Trustee Management

add-trustee(trustee)

Adds a new trustee to the vault.

• Access: Owner only
• Validation: Prevents duplicate trustees and null addresses

remove-trustee(trustee)

Removes an existing trustee from the vault.

• Access: Owner only
• Restriction: Cannot remove trustees during active votes

set-vote-threshold(new-threshold)

Updates the percentage of trustees required for successful votes.

• Access: Owner only
• Range: 1-100%

Voting System

initiate-vote(beneficiary)

Creates a new ownership transfer proposal.

• Access: Trustees only
• Duration: 3 days from creation
• Auto-approval: Initiator's vote is automatically counted

cast-vote()

Allows trustees to vote on the active proposal.

• Access: Trustees only
• Restriction: One vote per trustee per proposal

finalize-vote()

Executes the ownership transfer if threshold is met.

• Access: Anyone
• Requirements: Sufficient votes within deadline

cancel-vote()

Cancels the active voting session.

• Access: Owner only

Asset Management

transfer-tokens(token, recipient, amount)

Transfers fungible tokens from the vault.

• Access: Owner only
• Parameters: Token contract, recipient address, amount

transfer-stx(recipient, amount)

Transfers STX from the vault.

• Access: Owner only
• Validation: Sufficient balance check

Query Functions

vote-details()

Returns comprehensive information about the current voting session:

{
  active: bool,
  created-by: (optional principal),
  beneficiary: (optional principal),
  deadline: uint,
  current-votes: uint,
  required-votes: uint
}

get-vault-owner()

Returns the current vault owner's principal address.

get-trustee-total()

Returns the total number of registered trustees.

has-voted(trustee)

Checks if a specific trustee has voted on the current proposal.

Usage Examples

Initial Setup

;; Initialize vault with 60% approval threshold
(contract-call? .vault initialize-vault 'SP1ABC...DEF u60)

;; Add trustees
(contract-call? .vault add-trustee 'SP2GHI...JKL)
(contract-call? .vault add-trustee 'SP3MNO...PQR)

Emergency Ownership Transfer

;; Trustee initiates ownership change
(contract-call? .vault initiate-vote 'SP4STU...VWX)

;; Other trustees vote
(contract-call? .vault cast-vote)

;; Execute when threshold is met
(contract-call? .vault finalize-vote)

Asset Operations

;; Transfer STX
(contract-call? .vault transfer-stx 'SP5YZA...BCD u1000000)

;; Transfer fungible tokens
(contract-call? .vault transfer-tokens .token-contract 'SP6EFG...HIJ u500)

Security Considerations

• Trustee Selection: Choose trustees carefully as they can collectively change ownership
• Threshold Setting: Balance security (higher threshold) vs. availability (lower threshold)
• Vote Timing: 3-day voting window prevents rushed decisions but allows timely recovery
• Address Validation: All functions validate against null/zero addresses
• Single Active Vote: Only one ownership proposal can be active at a time

Error Codes

Code	Constant	Description
100	ERR_ACCESS_DENIED	Unauthorized access attempt
101	ERR_VAULT_INITIALIZED	Vault already initialized
102	ERR_VAULT_NOT_READY	Vault not yet initialized
103	ERR_TRUSTEE_EXISTS	Trustee already registered
104	ERR_TRUSTEE_NOT_FOUND	Trustee not found
105	ERR_VOTE_IN_SESSION	Vote already in progress
106	ERR_NO_ACTIVE_VOTE	No active vote exists
107	ERR_VOTE_SUBMITTED	Trustee already voted
108	ERR_VOTES_INSUFFICIENT	Not enough votes to execute
109	ERR_VOTE_DEADLINE_PASSED	Voting period expired
110	ERR_BALANCE_TOO_LOW	Insufficient STX balance
111	ERR_INVALID_THRESHOLD	Invalid threshold percentage
112	ERR_ZERO_ADDRESS	Invalid null address
113	ERR_INVALID_VALUE	Invalid amount value