Skip to content

Issuance Hookset ~ build on Xahau #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Handy4ndy wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Issuance Hookset ~ build on Xahau #5

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
158 changes: 158 additions & 0 deletions IssuanceHookset/Docs/IDOMulti.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,158 @@
# IDO Master Hook (IDOM)

## Overview

The IDO Master Hook (IDOM) is a sophisticated smart contract for Xahau that enables Initial DEX Offerings (IDOs). It facilitates token sales with multiple phases, dynamic multipliers, soft cap evaluation, and refund mechanisms. Users deposit XAH during active phases to receive IOU tokens at varying rates, with options for unwinding positions during eligible periods.

## Purpose

IDOs allow issuers to launch token sales with structured phases that incentivize early participation through higher multipliers. The hook manages the entire lifecycle: setup, deposits, issuance, soft cap evaluation, and refunds. It integrates with whitepaper validation to ensure user acknowledgment of terms and includes balance protection to prevent premature fund withdrawal.

## Hook Parameters

The hook requires several parameters set at installation time:

- **ADMIN** (20 bytes): Account ID of the administrator authorized to configure the IDO.
- **CURRENCY** (20 bytes): Currency code for the IOU tokens to be issued.
- **INTERVAL** (4 bytes): Ledger interval per phase (big-endian uint32).
- **SOFT_CAP** (8 bytes): Soft cap in XAH (big-endian uint64).
- **WP_LNK** (variable): Whitepaper/documentation link for validation.

## Admin Configuration

### Invoke Parameters
- **START** (4 bytes): Ledger offset to begin the IDO window (big-endian uint32).
- **WP_LNK** (variable): Whitepaper link stored in state for validation.

## Phases and Multipliers

The IDO operates in 5 phases with decreasing multipliers:

- **Phase 1**: 100x multiplier
- **Phase 2**: 75x multiplier
- **Phase 3**: 50x multiplier
- **Phase 4**: 25x multiplier
- **Phase 5**: Cooldown/unwind period (no new deposits)

Phases are determined by elapsed ledgers since the start, divided by the interval offset.

## User Actions

### Deposits
- Send XAH payments during active phases (1-4).
- Include 'WP_LNK' parameter matching the stored whitepaper link.
- Receive IOU tokens at the current phase's multiplier rate.

### Unwinding
- Send exact IOU amount back during eligible periods for proportional XAH refund.
- Available during Phase 5 (refund mode) or before window end (successful sales).

## Transaction Handling

### Invoke Transactions
- **Authorized Admin**: Can set START and WP_LNK to initialize the IDO window.
- **Unauthorized**: Rejected.

### Payment Transactions

#### Outgoing Payments
- **IOU Payments**: Always accepted (token issuance).
- **XAH Payments**: Checked against unlocked balance (locked during active IDO).
- **Other**: Accepted.

#### Incoming Payments

##### XAH Deposits (Active Phases)
- Validates WP_LNK parameter match.
- Checks window active and phase valid.
- Issues IOU tokens via Remit transaction.
- Updates global and user participation counters.

##### IOU Unwinds
- Validates issuer and amount.
- Checks refund mode or exact amount match.
- Emits XAH refund payment.
- Updates counters and removes user data.

## State Management

The hook maintains several state keys:

- **START**: Window start ledger.
- **END**: Window end ledger.
- **WP_LNK**: Stored whitepaper link.
- **SOFT_CAP**: Soft cap threshold.
- **XAH**: Total XAH raised.
- **IOU**: Total IOU issued.
- **EXEC**: Total execution count.
- **PHASE[1-5]**: Phase-specific execution counts.
- **REFUND**: Refund mode flag (0=success, 1=refund).
- **TOTAL_RAISED**: Preserved total for successful sales.
- **IDO_DATA** (foreign): User participation data (XAH deposited, IOU received).

## Soft Cap Evaluation

After Phase 4 ends:
- Compares total XAH raised against soft cap.
- If met: Sale successful, funds unlock after cooldown.
- If not met: Refund mode activated, users can unwind.

## Balance Protection

- Funds are locked during active IDO to prevent withdrawal.
- Locked amount = total XAH raised × 1,000,000 (drops).
- Unlocks after successful sale and cooldown period.

## Accepted Transactions

- Admin invokes with START/WP_LNK parameters.
- Outgoing IOU and other payments.
- Outgoing XAH with sufficient unlocked balance.
- Incoming XAH during active phases with valid WP_LNK.
- Incoming IOU for unwinding during eligible periods.

## Rejected Transactions

- Unauthorized invokes.
- XAH deposits without WP_LNK or during invalid phases.
- IOU unwinds with wrong issuer or invalid amounts.
- Payments outside active window (unless refund mode).
- Outgoing XAH exceeding unlocked balance.

## Error Messages

The hook provides detailed error messages for debugging:
- "IDO :: Error :: [specific issue]" for configuration/setup problems.
- "IDO :: Rejected :: [reason]" for invalid transactions.
- "IDO :: Unwind :: [issue]" for unwind-specific errors.
- "IDO :: Accepted :: [description]" for successful transactions.

## Security Considerations

- Admin authorization prevents unauthorized configuration.
- WP_LNK validation ensures user acknowledgment.
- Exact amount matching for unwinds prevents manipulation.
- Balance protection secures raised funds.
- State validation prevents race conditions.

## Integration

Designed to work with:
- Router Hook for transaction routing.
- Rewards Hook for post-IDO incentives.
- Compatible with Xahau's Remit transaction type for IOU issuance.

## Usage Example

1. **Setup**: Install hook with parameters, admin invokes with START.
2. **Deposit Phase**: Users send XAH with WP_LNK during phases 1-4.
3. **Evaluation**: After Phase 4, soft cap checked automatically.
4. **Unwind/Claim**: Users unwind IOU for refunds or hold for rewards.

## Author

@Handy_4ndy

## License

Part of the Xahau HandyHook Collection. See repository license for details.
163 changes: 163 additions & 0 deletions IssuanceHookset/Docs/MetaTemplate/Meta.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,163 @@
{
"t": "[TOKEN_TICKER]",
"n": "[TOKEN_DISPLAY_NAME]",
"d": "Utility token issued via an open-source phased IDO Hook on Xahau Network. Features time-decaying multipliers, soft-cap protection, automatic unwind/refund, and on-chain transparency for fair fundraising.",
"i": "[ICON_URI e.g. ipfs://... or https://...]",
"ac": "defi",
"as": "fundraising",
"in": "[ISSUER_OR_PROJECT_NAME]",
"us": [
{
"u": "[PROJECT_WEBSITE_URL]",
"c": "website",
"t": "Official Website"
},
{
"u": "[DOCUMENTATION_URL]",
"c": "docs",
"t": "Documentation & Usage Guide"
},
{
"u": "[WHITEPAPER_OR_DISCLOSURES_IPFS_OR_URL]",
"c": "docs",
"t": "Whitepaper, Risk Disclosures & Legal Terms"
},
{
"u": "[SOCIAL_MEDIA_URL e.g. x.com/...]",
"c": "social",
"t": "Project Updates"
},
{
"u": "explorer.xahau.network",
"c": "other",
"t": "Xahau Explorer (View On-Chain Activity)"
}
],
"ai": {
"platform": {
"network": "Xahau",
"programmability": "Account-attached Hooks (WebAssembly) for on-ledger automation and transaction logic",
"token_type": "Issued IOU (fungible token created via payments/Remits after TrustSet)",
"key_features": [
"4-phase fundraising window with configurable multipliers (e.g. 100x → 75x → 50x → 25x)",
"Soft cap threshold with automatic post-window refund/unwind if unmet",
"On-chain global counters: executions, total raised, total issued, per-phase stats",
"Per-user participation tracking via hierarchical state namespaces",
"WP_LNK parameter during install → used as access token to imply acknowledgment of disclosures"
]
},
"ido_mechanics": {
"phases": [
{
"number": 1,
"status": "First Phase",
"multiplier": "[PHASE1_MULTIPLIER e.g. 100x]",
"duration": "configurable (e.g. [EXAMPLE_LEDGERS] ledgers ≈ [DAYS] days)"
},
{
"number": 2,
"status": "Second Phase",
"multiplier": "[PHASE2_MULTIPLIER e.g. 75x]",
"duration": "same as phase 1"
},
{
"number": 3,
"status": "Mid Phase",
"multiplier": "[PHASE3_MULTIPLIER e.g. 50x]",
"duration": "same as phase 1"
},
{
"number": 4,
"status": "Final Phase",
"multiplier": "[PHASE4_MULTIPLIER e.g. 25x]",
"duration": "same as phase 1"
},
{
"number": 5,
"status": "Cooldown",
"multiplier": "0 (IDO closed, unwind only)",
"duration": "same as phase 1"
}
],
"soft_cap": "configurable (e.g. [AMOUNT] XAH in drops)",
"unwind_mechanism": "If soft cap unmet after window: participants return exact IOU balance → Hook emits proportional XAH refund via Remit",
"participation_flow": "XAH Payment to issuer during active window → Hook emits Remit with multiplied IOU; rejects invalid/out-of-window attempts"
},
"tokenomics": {
"total_supply": "[CONFIGURABLE_TOTAL_SUPPLY e.g. 1,000,000,000]",
"initial_distribution": "Primarily via phased IDO; remainder configurable (e.g. vested team, liquidity pools, ecosystem incentives, reserves)",
"utility": [
"Governance rights",
"Potential staking/yield mechanisms",
"Fee discounts or access perks",
"Ecosystem feature unlocks (project-specific)"
]
},
"compliance": {
"regulatory_classifications": {
"us_sec": "Self-assessed as utility token: Value from decentralized participation/utility, not centralized profit expectation (Howey Test review recommended).",
"eu_mica": "Crypto-asset (utility type); disclosures provided via IPFS-linked documentation; follow CASP rules if public offer exceeds thresholds.",
"uk_fca": "Cryptoasset; prominent risk warnings; no unauthorized high-risk promotions to retail users.",
"global": "On-chain transparency supports FATF Travel Rule principles; users advised to apply local AML/KYC standards."
},
"risk_disclosures": {
"general": [
"High risk of total loss due to volatility, illiquidity, or project failure.",
"No guaranteed value, returns, secondary market, or adoption.",
"Hook/smart-logic risks: potential bugs despite best practices."
],
"ido_specific": [
"Soft cap not met → unwind/refund mode may involve delays.",
"Early-phase higher multipliers reflect higher risk/reward timing.",
"Possible regulatory reclassification in certain jurisdictions."
],
"disclaimer": "This is not investment, financial, or legal advice. All participants bear full responsibility. Consult qualified professionals and review local laws."
},
"kyc_aml_policy": {
"approach": "Self-certification by participants; issuers may implement additional checks per jurisdiction.",
"privacy": "On-chain data is public and immutable by design; minimize off-chain personal data collection.",
"standards": "No facilitation of sanctioned entities; issuers should monitor for compliance."
},
"terms_of_service": {
"acceptance": "Sending XAH to the issuer account and/or providing WP_LNK during setup constitutes acknowledgment of all linked terms, risks, and disclosures.",
"eligibility": "Must be 18+ and not in restricted/sanctioned jurisdictions. Participants self-certify compliance.",
"limitations": "Issuer may pause, modify, or terminate fundraising for security, compliance, or technical reasons.",
"liability": "Services and Hook logic provided 'AS IS'; no liability accepted for market losses, technical issues, or third-party actions.",
"governing_law": "International blockchain norms; disputes recommended via arbitration in a neutral jurisdiction.",
"amendments": "Terms subject to update; continued participation implies acceptance."
},
"audit_and_security": {
"hook_audit": {
"status": "Pending / Planned / Completed (issuer to specify)",
"recommended_auditors": "Independent firms such as PeckShield, Certik, SlowMist, or equivalent",
"target_or_completion_date": "[YYYY-MM or 'Before real funds accepted']",
"report_uri": "[AUDIT_REPORT_IPFS_OR_URL] (placeholder – replace with actual link)"
},
"additional_audits": {
"status": "Pending / Planned / Completed (if separate token or tooling audited)",
"report_uri": "[ADDITIONAL_AUDIT_URI] (placeholder)"
},
"security_features": [
"Guard macros to prevent common errors (overflows, reentrancy, etc.)",
"Restricted invoke access (only issuer/admin)",
"Atomic emit-based token issuance",
"State integrity and counter validation"
],
"recommendation": "All deployers/issuers MUST obtain independent security audits before accepting real-value transactions. Audits materially reduce risk and build user confidence."
},
"tax_reporting": {
"user_responsibility": "Participants solely responsible for their own tax and reporting obligations.",
"platform_support": "On-chain transaction history available via explorers for user reference."
},
"sustainability": {
"note": "Xahau uses efficient consensus; issuers may allocate portions of raised funds to environmental or social impact initiatives."
}
},
"contact_and_support": {
"website": "[ISSUER_WEBSITE_URL]",
"email": "[SUPPORT_EMAIL e.g. support@[DOMAIN]]",
"social": "[SOCIAL_HANDLE_OR_URL]",
"legal": "[LEGAL_CONTACT e.g. legal@[DOMAIN]]"
}
}
}
Loading