@fundtokens/builders 0.1.0-rc5 → 0.1.0-rc7

package/FundTokenTransactionBuilder.js

@@ -16,6 +16,7 @@ import {
     getBestFee,
     getRandomInt,
     withDust,
+    categoryAscending,
 } from './utils.js';
 
 import managerJson from './art/manager.json' with { type: 'json' };
@@ -72,7 +73,9 @@ export default class FundTokenTransactionBuilder extends TransactionBuilder {
             throw new Error('No system configuration provided, unable to continue');
         }
         super({ provider });
-        this.#system = system;
+        this.#system = {
+            ...system,
+        };
         this.#swapped = {
             inflow: swapEndianness(system.inflow),
             outflow: swapEndianness(system.outflow),
@@ -81,7 +84,10 @@ export default class FundTokenTransactionBuilder extends TransactionBuilder {
                 nft: swapEndianness(system.fee.nft),
             },
         };
-        this.#fund = fund;
+        this.#fund = {
+            ...fund,
+            assets: [...fund.assets.map(a => ({ ...a })).sort(categoryAscending)] ?? [],
+        };
         this.#meta = {
             isBitcoinFund: this.#fund.satoshis > 0,
         };
@@ -98,18 +104,18 @@ export default class FundTokenTransactionBuilder extends TransactionBuilder {
         const fundHash = hashFund(this.#fund);
 
         const assetContracts = [];
-        
+
         let satoshiAssetContract = undefined;
-        if(this.#fund.satoshis > 0) {
+        if (this.#fund.satoshis > 0) {
             satoshiAssetContract = new Contract(assetJson, [this.#swapped.outflow, fundHash, BitcoinCategory], { provider: this.provider });
         }
 
         assets.forEach(a => {
             const fundAssetCategory = swapEndianness(a.category);
-            
+
             // 32 32 32
             const assetContract = new Contract(assetJson, [this.#swapped.outflow, fundHash, fundAssetCategory], { provider: this.provider });
-            
+
             assetContracts.push(assetContract);
         });
 
@@ -137,18 +143,29 @@ export default class FundTokenTransactionBuilder extends TransactionBuilder {
         return this.#contracts;
     }
 
-    // TODO: Scaling fund UTXO selection
-    // As new threads are added to the fund token contract, we should select for inflow tx the UTXO with the most tokens
-    // Although this means we still target one thread, should have a range maybe and then randomly select
-    // Maybe should just randomly select enough to fulfills the needs for the tx
-
-    // This method should be called while the transaction has same transaction input and output lengths
-    // The consuming app is responsible for adding an output for Bitcoin change, fund token minted, and token change
+    /**
+     * addInflow(amount, payBy): Builds a fund token minting transaction
+     * 
+     * Randomly selects:
+     * - One inflow thread (for thread distribution)
+     * - Multiple fund UTXOs to cover the minting amount (reduces collision)
+     * - Best fee option (Bitcoin or token-based)
+     * 
+     * Constructs transaction with:
+     * - Inflow manager input + output (threaded signal)
+     * - Fund UTXO inputs collected randomly + outputs (one per input)
+     * - Fee validation and routing
+     * - Asset custody outputs (prepared for user deposit)
+     * 
+     * The consuming app is responsible for:
+     * - Adding user inputs (assets to deposit)
+     * - Adding user outputs (fund tokens minted, Bitcoin change, token change)
+     */
     async addInflow({
         amount,
         payBy,
     }) {
-        this.#logger.log('transaction builder...adding minting transaction');
+        this.#logger.log('transaction builder...adding minting transaction', amount, payBy);
 
         const { managerContract, fundContract, assetContracts, feeContract, feeVaultContract } = this.#contracts;
 
@@ -162,20 +179,56 @@ export default class FundTokenTransactionBuilder extends TransactionBuilder {
         }
 
         const inflowUtxo = inflowUtxos[getRandomInt(inflowUtxos.length)];
-        const fundUtxo = fundUtxos[getRandomInt(fundUtxos.length)];
         const feeUtxo = bestFee.utxo;
 
         const inflowAmount = this.#fund.amount * amount;
-        const fundChangeAmount = fundUtxo.token.amount - inflowAmount;
 
-        const fundContractOutput = fundChangeAmount > 0 ? withDust({
-            to: fundContract.tokenAddress,
-            token: {
-                category: this.#fund.category,
-                amount: fundChangeAmount,
-            },
-        }) : withDust({
-            to: fundContract.tokenAddress,
+        // Randomly select fund UTXOs to cover the inflow amount
+        // Shuffle to reduce collision chances when multiple transactions are building
+        const shuffledFundUtxos = [...fundUtxos].sort(() => Math.random() - 0.5);
+        let totalFundAmount = 0n;
+        const selectedFundUtxos = [];
+
+        for (const utxo of shuffledFundUtxos) {
+            selectedFundUtxos.push(utxo);
+            totalFundAmount += utxo.token.amount;
+
+            if (totalFundAmount >= inflowAmount) {
+                break;
+            }
+        }
+
+        if (totalFundAmount < inflowAmount) {
+            throw new Error(`Insufficient fund tokens: need ${inflowAmount}, have ${totalFundAmount}`);
+        }
+
+        const fundChangeAmount = totalFundAmount - inflowAmount;
+
+
+        // Create one input per selected UTXO
+        const fundInputs = selectedFundUtxos.map(utxo => ({
+            ...utxo,
+            unlocker: fundContract.unlock.mint(),
+        }));
+
+        // Create one output per input (maintain input/output balance)
+        // First output contains any change, others are dust returns
+        const fundOutputs = selectedFundUtxos.map((utxo, index) => {
+            if (index === 0 && fundChangeAmount > 0) {
+                // Last output: return change to contract
+                return withDust({
+                    to: fundContract.tokenAddress,
+                    token: {
+                        category: this.#fund.category,
+                        amount: fundChangeAmount,
+                    },
+                });
+            } else {
+                // Other outputs: return as dust
+                return withDust({
+                    to: fundContract.tokenAddress,
+                });
+            }
         });
 
         const bitcoinOutputs = [];
@@ -186,51 +239,60 @@ export default class FundTokenTransactionBuilder extends TransactionBuilder {
                 ...inflowUtxo,
                 unlocker: managerContract.unlock.inflow(getFundBin(this.#fund)),
             },
-            {
-                ...fundUtxo,
-                unlocker: fundContract.unlock.mint(),
-            },
             {
                 ...feeUtxo,
                 unlocker: feeContract.unlock.pay(),
-            }
+            },
+            ...fundInputs,
         ])
-        .addOutputs([
-            withDust({
-                to: managerContract.tokenAddress,
-                token: {
-                    ...inflowUtxo.token,
-                },
-            }),
-            fundContractOutput,
-            ...bestFee.outputs,
-            ...bitcoinOutputs,
-            ...assetContracts.map((assetContract, i) => {
-                return withDust({
-                    to: assetContract.tokenAddress,
+            .addOutputs([
+                withDust({
+                    to: managerContract.tokenAddress,
                     token: {
-                        category: this.#fund.assets[i].category,
-                        amount: this.#fund.assets[i].amount * amount,
-                    }
-                });
-            }),
-        ]);
+                        ...inflowUtxo.token,
+                    },
+                }),
+                ...bestFee.outputs,
+                ...fundOutputs,
+                ...bitcoinOutputs,
+                ...assetContracts.map((assetContract, i) => {
+                    return withDust({
+                        to: assetContract.tokenAddress,
+                        token: {
+                            category: this.#fund.assets[i].category,
+                            amount: this.#fund.assets[i].amount * amount,
+                        }
+                    });
+                }),
+            ]);
         this.#logger.log('finished adding mint transaction i/o');
         return this;
     }
 
-    // TODO: Scaling fund UTXO selection
-    // As new threads are added to the fund token contract, we should select for outflow tx the UTXO with the least tokens
-    // Although this means we still target one thread, should have a range maybe and then randomly select
-    // Maybe should just randomly select one that fulfills the needs
-
-    // This method should be called while the transaction has same transaction input and output lengths
-    // The consuming user is responsible for adding inputs for the fund token
-    // The consuming app is responsible for adding an outputs for Bitcoin change and token change
+    /**
+     * addOutflow(amount, payBy): Builds a fund token redemption transaction
+     * 
+     * Randomly selects:
+     * - One outflow thread (for thread distribution)
+     * - A fund UTXO to collect redeemed tokens into
+     * - Best fee option (Bitcoin or token-based)
+     * - Asset UTXOs from each asset contract (largest first)
+     * - Satoshi UTXOs if fund includes Bitcoin (largest first)
+     * 
+     * Constructs transaction with:
+     * - Outflow manager input + output (threaded signal)
+     * - Fund UTXO input + output (collects redeemed tokens)
+     * - Fee validation and routing
+     * - Asset release inputs + outputs (with change handling)
+     * - Satoshi release inputs + outputs (with change handling)
+     * 
+     * The consuming app is responsible for:
+     * - Adding user inputs (fund tokens to redeem)
+     * - Adding user outputs (underlying assets received, change)
+     */
     async addOutflow({
         amount,
         payBy,
-        bufferHex,
     }) {
         this.#logger.log('transaction builder...adding redemption transaction');
 
@@ -241,27 +303,37 @@ export default class FundTokenTransactionBuilder extends TransactionBuilder {
         if (!outflowUtxos.length) {
             throw new Error(`Missing required outflow ${this.#system.outflow} UTXO.`);
         }
-        const outflowUtxo = outflowUtxos[0];
-
+        const outflowUtxo = outflowUtxos[getRandomInt(outflowUtxos.length)];
 
-        //
         const fundUtxos = await fundContract.getUtxos();
 
         if (!fundUtxos.length) {
             throw new Error(`Missing required fund ${this.#fund.category} UTXO. Send dust UTXO to contract and redeem again.`)
         }
 
-        const existingFundUtxo = fundUtxos.filter(u => u.token?.category === this.#fund.category).sort(sortDecreasingTokenAmount);
+        const existingFundUtxo = fundUtxos.filter(u => u.token?.category === this.#fund.category);
         const fundUtxo = existingFundUtxo.length ? existingFundUtxo[getRandomInt(existingFundUtxo.length)] : fundUtxos[getRandomInt(fundUtxos.length)];
 
-
         //
         const outflowAmount = this.#fund.amount * amount;
         const updatedFundAmount = (fundUtxo.token?.amount ?? 0n) + outflowAmount;
 
-        const bestFee = await getBestFee({ feeVaultContract, feeContract, payBy, fee: this.#system.fee, authorization: this.#system.authorization });
+        const bestFee = await getBestFee({ feeVaultContract, feeContract, payBy, fee: this.#system.fee });
         const feeUtxo = bestFee.utxo;
 
+
+        const fundInputs = [{
+            ...fundUtxo,
+            unlocker: fundContract.unlock.redeem()
+        }];
+        const fundOutputs = [withDust({
+            to: fundContract.tokenAddress,
+            token: {
+                category: this.#fund.category,
+                amount: updatedFundAmount,
+            },
+        })];
+
         const satoshiAssetInputs = [];
         const satoshiAssetOutputs = [];
         const satoshiAssetChangeAmounts = [];
@@ -269,7 +341,7 @@ export default class FundTokenTransactionBuilder extends TransactionBuilder {
         const calcSatoshiAsset = async () => {
             if (this.#meta.isBitcoinFund) {
                 const satoshiAssetUtxos = (await satoshiAssetContract.getUtxos()).filter(u => !u.token);
-                if(!satoshiAssetUtxos) {
+                if (!satoshiAssetUtxos) {
                     throw new Error('Missing required satoshi asset UTXO');
                 }
                 let satoshiAmountAdded = 0n;
@@ -323,7 +395,7 @@ export default class FundTokenTransactionBuilder extends TransactionBuilder {
                     }
                 }
             }
-            
+
             for (let i = 0; i < assetChangeAmounts.length; ++i) {
                 if (!assetChangeAmounts[i]) {
                     continue;
@@ -339,44 +411,32 @@ export default class FundTokenTransactionBuilder extends TransactionBuilder {
         }
 
         await calcTokenAssets();
-        
-        // 180 is good up to 12
-        const densityBuffer = this.#fund.assets.length <= 8 ? '' : '00'.repeat(180 * (this.#fund.assets.length - 8));
 
         this.addInputs([
             {
                 ...outflowUtxo,
-                unlocker: managerContract.unlock.outflow(getFundBin(this.#fund), bufferHex ?? densityBuffer) // TODO: support density better, need to calculate the "expensive" operations // '00'.repeat(4325)
-            },
-            {
-                ...fundUtxo,
-                unlocker: fundContract.unlock.redeem()
+                unlocker: managerContract.unlock.outflow(getFundBin(this.#fund))
             },
             {
                 ...feeUtxo,
                 unlocker: feeContract.unlock.pay()
             },
+            ...fundInputs,
             ...satoshiAssetInputs,
-            ...assetInputs
+            ...assetInputs,
         ])
-        .addOutputs([
-            withDust({
-                to: managerContract.tokenAddress,
-                token: {
-                    ...outflowUtxo.token,
-                },
-            }),
-            withDust({
-                to: fundContract.tokenAddress,
-                token: {
-                    category: this.#fund.category,
-                    amount: updatedFundAmount,
-                },
-            }),
-            ...bestFee.outputs,
-            ...satoshiAssetOutputs,
-            ...assetOutputs
-        ]);
+            .addOutputs([
+                withDust({
+                    to: managerContract.tokenAddress,
+                    token: {
+                        ...outflowUtxo.token,
+                    },
+                }),
+                ...bestFee.outputs,
+                ...fundOutputs,
+                ...satoshiAssetOutputs,
+                ...assetOutputs
+            ]);
 
         this.#logger.log('finished adding redemption transaction i/o');
         return this;

package/PublicFundTransactionBuilder.js

@@ -171,6 +171,13 @@ export default class PublicFundTransactionBuilder extends TransactionBuilder {
         return this.#contracts;
     }
 
+    getAuthHeadOutput() {
+        const { authHeadVaultContract } = this.#contracts;
+        return withDust({
+            to: authHeadVaultContract.tokenAddress,
+        });
+    }
+
     async addBroadcast({
         fund,
         payBy,
@@ -186,33 +193,39 @@ export default class PublicFundTransactionBuilder extends TransactionBuilder {
             publicFundVaultContract,
         } = this.#contracts;
 
-        if(this.inputs.length === 0) {
+        if (this.inputs.length === 0) {
             throw new Error('User genesis input is expected to be added prior to calling this function');
         }
 
-        if(this.outputs.length > 0) {
-            throw new Error('No outputs should be added to the transaction');
+        if (this.outputs.length === 0) { // add authhead output
+            this.addOutput(this.getAuthHeadOutput());
+        } else {
+            // verify authhead output
+            const authhead = this.outputs[0];
+            if(authhead.to != authHeadVaultContract.tokenAddress || authhead.token) {
+                throw new Error('Authhead output is incorrect, expecting to send to authhead vault with no tokens');
+            }
         }
 
         const genesisUtxo = this.inputs[0];
 
-        if(genesisUtxo.vout !== 0 || genesisUtxo.token) {
+        if (genesisUtxo.vout !== 0 || genesisUtxo.token) {
             throw new Error('First input must be a genesis input (vout is 0) with no tokens');
         }
 
-
         const bestFee = await getBestFee({ feeVaultContract, feeContract: createFundFeeContract, payBy, fee: this.#system.fees.create });
 
-        const broadcastUtxos = await startupContract.getUtxos();
+        const startupUtxos = await startupContract.getUtxos();
         const mintInflowUtxos = await mintInflowContract.getUtxos();
         const mintOutflowUtxos = await mintOutflowContract.getUtxos();
         const publicUtxos = await publicFundContract.getUtxos();
+
         const inflowUtxos = mintInflowUtxos.filter(u => u.token?.category === this.#system.inflow);
         const outflowUtxos = mintOutflowUtxos.filter(u => u.token?.category === this.#system.outflow);
         const publicFundUtxos = publicUtxos.filter(u => u.token?.category === this.#system.publicFund)
 
 
-        const broadcastUtxo = broadcastUtxos[getRandomInt(broadcastUtxos.length)];
+        const startupUtxo = startupUtxos[getRandomInt(startupUtxos.length)];
         const inflowUtxo = inflowUtxos[getRandomInt(inflowUtxos.length)];
         const outflowUtxo = outflowUtxos[getRandomInt(outflowUtxos.length)];
         const publicFundUtxo = publicFundUtxos[getRandomInt(publicFundUtxos.length)];
@@ -223,13 +236,13 @@ export default class PublicFundTransactionBuilder extends TransactionBuilder {
 
         this.addInputs([
             {
-                ...broadcastUtxo,
+                ...startupUtxo,
                 unlocker: startupContract.unlock.start(getFundBin(fund)),
-            }, 
+            },
             {
                 ...inflowUtxo,
                 unlocker: mintInflowContract.unlock.mint(),
-            }, 
+            },
             {
                 ...outflowUtxo,
                 unlocker: mintOutflowContract.unlock.mint(),
@@ -243,77 +256,74 @@ export default class PublicFundTransactionBuilder extends TransactionBuilder {
                 unlocker: publicFundContract.unlock.broadcast(getFundBin(fund))
             }
         ])
-        .addOutputs([
-            withDust({
-                to: authHeadVaultContract.tokenAddress,
-            }),
-            {
-                to: startupContract.tokenAddress,
-                amount: broadcastUtxo.satoshis,
-                token: broadcastUtxo.token,
-            },
-            {
-                to: mintInflowContract.tokenAddress,
-                amount: inflowUtxo.satoshis,
-                token: inflowUtxo.token,
-            },
-            {
-                to: mintOutflowContract.tokenAddress,
-                amount: outflowUtxo.satoshis,
-                token: outflowUtxo.token,
-            }, 
-            ...bestFee.outputs,
-            withDust({
-                to: managerContract.tokenAddress,
-                token: {
-                    ...inflowUtxo.token,
-                    nft: {
-                        capability: 'none',
-                        commitment: swapEndianness(genesisUtxo.txid) + binToHex(hash256(getFundBin(fund))),
+            .addOutputs([
+                {
+                    to: startupContract.tokenAddress,
+                    amount: startupUtxo.satoshis,
+                    token: startupUtxo.token,
+                },
+                {
+                    to: mintInflowContract.tokenAddress,
+                    amount: inflowUtxo.satoshis,
+                    token: inflowUtxo.token,
+                },
+                {
+                    to: mintOutflowContract.tokenAddress,
+                    amount: outflowUtxo.satoshis,
+                    token: outflowUtxo.token,
+                },
+                ...bestFee.outputs,
+                withDust({
+                    to: managerContract.tokenAddress,
+                    token: {
+                        ...inflowUtxo.token,
+                        nft: {
+                            capability: 'none',
+                            commitment: swapEndianness(genesisUtxo.txid) + binToHex(hash256(getFundBin(fund))),
+                        }
                     }
-                }
-            }),
-            withDust({
-                to: managerContract.tokenAddress,
-                token: {
-                    ...outflowUtxo.token,
-                    nft: {
-                        capability: 'none',
-                        commitment: swapEndianness(genesisUtxo.txid) + binToHex(hash256(getFundBin(fund))),
+                }),
+                withDust({
+                    to: managerContract.tokenAddress,
+                    token: {
+                        ...outflowUtxo.token,
+                        nft: {
+                            capability: 'none',
+                            commitment: swapEndianness(genesisUtxo.txid) + binToHex(hash256(getFundBin(fund))),
+                        }
                     }
-                }
-            }),
-            withDust({
-                to: fundContract.tokenAddress,
-                token: {
-                    category: genesisUtxo.txid,
-                    amount: fundTokenAmount,
-                }
-            }),
-            withDust({
-                to: publicFundContract.tokenAddress,
-                token: {
-                    category: this.#system.publicFund,
-                    amount: 0n,
-                    nft: {
-                        capability: 'minting',
-                        commitment: '',
+                }),
+                withDust({
+                    to: fundContract.tokenAddress,
+                    token: {
+                        category: genesisUtxo.txid,
+                        amount: fundTokenAmount,
                     }
-                }
-            }),
-        ]);
+                }),
+                withDust({
+                    to: publicFundContract.tokenAddress,
+                    token: {
+                        category: this.#system.publicFund,
+                        amount: 0n,
+                        nft: {
+                            capability: 'minting',
+                            commitment: '',
+                        }
+                    }
+                }),
+            ]);
 
 
         const maxSize = 128 * 2;
 
         const fundHex = getFundHex(fund);
         const fundHexParts = [];
-        
+
         let curr = 0;
         let next = maxSize;
 
 
-        while(curr < fundHex.length) {
+        while (curr < fundHex.length) {
             fundHexParts.push(fundHex.slice(curr, next));
             curr = next;
             next += maxSize
@@ -321,7 +331,7 @@ export default class PublicFundTransactionBuilder extends TransactionBuilder {
 
         fundHexParts.forEach(part => {
             this.addOutput(withDust({
-                to:  publicFundVaultContract.tokenAddress,
+                to: publicFundVaultContract.tokenAddress,
                 token: {
                     category: this.#system.publicFund,
                     amount: 0n,

package/README.md

@@ -0,0 +1,85 @@
+# FundTokens.Contracts
+
+A JavaScript library for interacting with FundTokens smart contracts on the Bitcoin Cash network. This library provides tools for creating, minting, and redeeming fund tokens while handling the complex multi-contract operations required by the FundTokens protocol.
+
+## Features
+
+- **Fund Creation**: Create new public funds with custom asset compositions
+- **Token Minting**: Deposit assets to mint fund tokens
+- **Token Redemption**: Withdraw assets by redeeming fund tokens
+- **Multi-Contract Coordination**: Handles complex transaction flows across many smart contracts
+
+## Installation
+
+```bash
+npm install @fundtokens/builders
+```
+
+## Quick Start
+
+### Creating a Public Fund
+
+```javascript
+import { PublicFundTransactionBuilder } from '@fundtokens/builders';
+
+const publicBuilder = new PublicFundTransactionBuilder({ provider, system });
+const fund = {
+    category: genesisUtxo.txid,
+    amount: 10n,
+    satoshis: 1000n,
+    assets: [{ category: 'asset_token_id', amount: 2n }]
+};
+
+// add user's genesis UTXO
+await publicBuilder.addBroadcast({ fund });
+// add additional IO
+await publicBuilder.send();
+```
+
+### Minting Fund Tokens
+
+```javascript
+import { FundTokenTransactionBuilder } from '@fundtokens/builders';
+
+const fundBuilder = new FundTokenTransactionBuilder({
+    provider, system, fund
+});
+
+await fundBuilder.addInflow({ amount: 1n });
+// Add user asset inputs and fund token outputs
+await fundBuilder.send();
+```
+
+### Redeeming Fund Tokens
+
+```javascript
+const fundBuilder = new FundTokenTransactionBuilder({
+    provider, system, fund
+});
+
+await fundBuilder.addOutflow({ amount: 1n });
+// Add user inputs/outputs
+await fundBuilder.send();
+```
+
+## Key Concepts
+
+### Fund Lifecycle
+
+* Fund Creation - Broadcast fund parameters
+* Fund Operations - Mint and redeem tokens
+
+## Security Model
+
+* Non-Custodial: Funds held in contract UTXOs controlled by code
+* Parameter Immutability: Fund details hashed and committed to tokens
+* Contract Isolation: Each contract has single, verified responsibility
+* Thread Authorization: Operations require matching token presence
+* Atomic Validation: Multi-contract validation ensures consistency
+
+## Requirements
+* Bitcoin Cash network access
+
+## License
+
+Copyright (c) 2026 FoldingCash LLC, doing business as Fun(d)Tokens. All rights reserved.