asgayapedia

Manual Covenant Construction

Status: ⚠️ Implemented but not validated - moved to WebView approach (August 2026)
Platform: Android (Kotlin)
Originally Targeted: CashScript v0.13+ (P2SH32 format)

Why This Matters

The 367-byte principle: A static bytecode template plus 8 constructor parameters replaces an entire CashScript runtime. This is the covenant simplicity principle made tangible.

What this proves: Covenants are portable. They exist as pure cryptographic constructions—hash functions, script opcodes, and addresses. Any platform that can hash and encode can create covenants. No JavaScript runtime, no WebView, no external dependencies.

Architectural significance:

User sovereignty: Covenant construction happens entirely on-device. No external service knows what covenant you created, when you created it, or who it’s for.
Portability: The same construction logic works on Android, iOS, desktop, hardware wallets, or server-side validators. It’s just bytes and hashing.
Auditability: The entire covenant constructor is ~800 lines of readable Kotlin. A security auditor can verify every step without understanding CashScript internals.
Future-proofing: If Asgaya succeeds (hundreds of users), we can optimize further—native secp256k1, custom ECDSA, or even hardware acceleration. The architecture supports it.

This is not just an implementation detail. It’s proof that decentralized payment covenants can exist on consumer devices without intermediation.

The Construction Process

A Bitcoin Cash covenant is a P2SH32 script with this structure:

[Constructor Parameters] + [Bytecode Template] → SHA256 → CashAddr P2SH32 Address

Step 1: Encode Constructor Parameters

Inputs (v2.5):

senderPubkey - 33 bytes (compressed public key)
recipientPubkey - 33 bytes
sellerPubkey - 33 bytes
oraclePubkey - 33 bytes
eurCents - int (e.g., 10000 = €100.00) — payment amount in cents
expiryOracleTime - int (Unix timestamp)
initialBchPriceInCents - int (e.g., 65000 = €650/BCH) — BCH price in EUR cents
minPricePercent - int (e.g., 93 = 7% drop tolerance)

Bitcoin Script encoding rules:

Parameters are pushed in reverse order (stack-based VM)
Integers use minimal encoding (little-endian, no padding)
Data < 75 bytes: [length][data]
Data < 255 bytes: OP_PUSHDATA1 [length][data]
Data < 65535 bytes: OP_PUSHDATA2 [length_low][length_high][data]

Result: 150 bytes of encoded parameters

Step 2: Append Bytecode Template

The v2.5 bytecode template is 367 bytes of Bitcoin Script opcodes compiled from the PriceOracle contract.

Source: price-oracle-v2.5.json artifact (compiled July 27, 2026)

This bytecode is static and shared across all v2.5 covenants. It implements:

Claim path (recipient + oracle signature)
Merchant cashout path (recipient + merchant + oracle)
Refund path (sender, anytime)
Seller recovery path (seller + oracle, after expiry)

Complete script: 150 bytes (params) + 367 bytes (bytecode) = 517 bytes

Step 3: Hash with SHA256 (P2SH32)

CashScript v0.13+ uses P2SH32 format:

Hash algorithm: SHA256 only (not HASH160)
Output: 32-byte script hash

Why P2SH32?

Better security (32 bytes vs 20 bytes)
Matches modern CashScript output
Prevents RIPEMD160 dependency (removed from Android)

Result: 32-byte script hash (e.g., c47fc431...)

Step 4: Encode as CashAddr Address

CashAddr P2SH32 format:

Prefix: bchtest: (testnet) or bitcoincash: (mainnet)
Type indicator: ‘v’ (P2SH32, version byte 0x10)
Payload: version byte + 32-byte script hash
Encoding: Base32 (custom alphabet: qpzry9x8gf2tvdw0s3jn54khce6mua7l)
Checksum: BCH polymod (8 bytes)

Example output:

bchtest:vzrz8l3p3f62ungalsuxvkv7el37v8ayvn8647mvm056xafn3lwly7x4hucsr2

This is the address you fund to create a covenant. The 32-byte hash uniquely identifies the covenant script.

Implementation (AsgayaHusk)

File Structure

app/src/main/java/com/asgaya/husk/covenant/
├── CovenantBuilder.kt         # Core construction logic
├── CovenantConstants.kt       # v2.5 bytecode + oracle params
├── CashAddrEncoder.kt         # P2SH32 address formatting
└── CovenantTest.kt            # Validation tests

Dependencies

BouncyCastle for Bitcoin crypto:

implementation("org.bouncycastle:bcprov-jdk18on:1.78")

Android’s standard library lacks Bitcoin-specific algorithms (RIPEMD160, secp256k1). BouncyCastle provides them.

Note: Android 14+ (API 34+) includes some BouncyCastle algorithms natively, but the explicit dependency ensures consistent behavior across all API levels (AsgayaHusk targets API 26+).

Usage Example

// Define covenant parameters
val params = CovenantBuilder.CovenantParams(
    senderPubkey = senderKey.publicKey,
    recipientPubkey = recipientKey.publicKey,
    sellerPubkey = sellerKey.publicKey,
    oraclePubkey = fetchOraclePubkey(),  // From Pi-chan oracle /oracle/info (no hardcoded keys since Aug 16)
    eurCents = 10000,                  // €100.00
    expiryOracleTime = currentTime + 8.hours,
    initialBchPriceInCents = 65000,    // €650/BCH
    minPricePercent = 93               // 7% drop tolerance
)

// Build covenant
val builder = CovenantBuilder()
val result = builder.buildCovenant(params)

// Result contains:
// - result.address: "bchtest:v..."
// - result.scriptHash: [32 bytes]
// - result.redeemScript: [517 bytes]

⚠️ Note: This API exists in the codebase but was not validated to produce correct covenant addresses. Production covenant creation currently uses the WebView Covenant Bridge.

Validation

Cross-platform verification:

# Android builds covenant
adb logcat | grep CovenantBuilder
# Script hash: c47fc431...

# CashScript builds same covenant
node validate-android-covenant.mjs
# Script hash: c47fc431... ✅ MATCH

If script hashes match, construction is correct. Address format differences (Android vzrz... vs CashScript pvp8...) are cosmetic—both encode the same 32-byte hash.

Why Not Use CashScript Directly?

The arguments below describe why manual construction remains the long-term goal. For Phase 0, we chose WebView + CashScript for speed of validation—see Reality Check.

We could embed a JavaScript runtime (WebView) and call CashScript. But:

Security surface: A JavaScript engine is 10MB+ of attack surface. Our manual constructor is <1KB of auditable code.
Performance: JavaScript initialization takes 100-500ms. Manual construction takes <50ms.
Dependency risk: CashScript updates could break our app. Static bytecode is frozen—v2.5 covenants work forever.
Platform lock-in: WebView ties us to platforms with JavaScript support. Manual construction works anywhere (iOS, hardware wallets, embedded systems).
User sovereignty: No one can force us to change covenant construction logic. The bytecode is copied, not fetched.

The trade-off: We maintain our own covenant constructor. But it’s 800 lines of simple code, tested against CashScript output. That’s acceptable overhead for the benefits.

Security Considerations

What’s Safe

✅ Script hash validation: If our hash matches CashScript’s hash, the covenant is correct
✅ Static bytecode: v2.5 bytecode is frozen, can’t change unexpectedly
✅ On-device construction: No external service sees your covenant parameters
✅ Deterministic output: Same params always produce same address

What Needs Care

⚠️ Private key storage: WIF keys stored in SharedPreferences (plaintext for testing)
⚠️ Parameter validation: Malformed params produce invalid covenants
⚠️ Oracle pubkey: Hardcoded in CovenantConstants (must match Pi-chan’s oracle)
⚠️ Network flag: IS_TESTNET toggle—double-check before mainnet

Production TODO:

Encrypt WIF keys before storing (Android Keystore or EncryptedSharedPreferences)
Validate parameters (pubkey lengths, timestamp ranges, price sanity checks)
Add oracle pubkey rotation mechanism (for key compromise scenarios)

Limitations

What this does NOT do:

Transaction construction: Building the funding transaction requires UTXO selection, fee calculation, and signing. That’s the next layer (see Asgaya Trinity).
Covenant claiming: Unlocking a covenant requires constructing witness scripts with oracle signatures. Also next layer.
Parameter negotiation: This assumes you already know recipient’s pubkey, seller’s pubkey, current BCH price, and agreed EUR amount. Coordination is separate (Telegram, Nostr, or bulletin board).
Bytecode compilation: We use pre-compiled v2.5 bytecode. If covenant logic changes (v3.0), we need a new artifact.

Scope boundary: This module does ONE thing—turn covenant parameters into a P2SH32 address. Everything before (parameter negotiation) and after (transaction construction) is handled elsewhere.

Versioning

Current: v2.5 (July 27, 2026)

If covenant logic changes:

RaspberryPi compiles new CashScript contract
Extract bytecode hex from artifact
Update CovenantConstants.BYTECODE_V25_HEX
Run validation tests against CashScript
Bump version constant

Bytecode fingerprint (v2.5):

db7c643e5730713b88962d84c83626ecffbaa0e327de25bbe196a412310bc509

Use this to verify you have the correct v2.5 bytecode.

⚠️ Reality Check: What Actually Happened (August 2026)

The honest assessment: We implemented manual covenant construction in Kotlin, but we failed to validate that it produces addresses matching CashScript’s output.

What we tried:

Implemented parameter encoding according to Bitcoin Script rules
Implemented P2SH32 hashing and CashAddr encoding
Created test harness to compare against CashScript
Spent multiple sessions debugging byte-level differences

What didn’t work:

Address output never matched CashScript reference implementation
Debugging revealed subtle encoding differences we couldn’t resolve
Attempting to validate became a time sink without clear progress
First rule: If you’re in a hole, stop digging

What we did instead (August 1-2, 2026):

Pivoted to WebView + CashScript SDK approach
Bundled official CashScript library (webpack + polyfills)
Built JavaScript ↔ Kotlin bridge for covenant operations
Result: 4 successful covenant claims and 3 successful refunds on testnet3 within 48 hours

Why the pivot was right:

Proof over perfection: WebView approach is validated and working
Time value: 2 days of WebView work > 2 weeks of manual construction debugging
Maintenance: Official SDK updates automatically, manual code would need constant sync
Risk reduction: Using battle-tested library vs. maintaining custom Bitcoin Script encoder

Is manual construction abandoned?

No, just deferred. The architectural vision is still sound:

Portable covenant construction without JavaScript runtime
User sovereignty (entirely on-device)
Auditability (~800 lines of readable code)
Future hardware wallet integration

But pragmatism won: We need proven covenant infrastructure for Phase 0. Manual construction can be revisited later if:

WebView performance becomes a bottleneck
Hardware wallet integration requires it
We find time to debug the encoding differences properly

Documentation principle: Own what didn’t work. This document describes the ideal, but production uses WebView. Both approaches are documented honestly.

See also: WebView Covenant Bridge - what’s actually running in production