How to Implement HTLC Locking for Taproot Assets Using an HTLC Script Address?

[shuishihang]

How can I implement HTLC locking for Taproot Assets using an address created with an HTLC script? I attempted to create a timelock address using a Taproot script and sent an asset to this address. However, it seems the script didn’t take effect. After creating an address with a timelock script, are there additional steps required to enforce the lock? I want to achieve locking by creating a locking address. So far, I’ve only successfully implemented a multisig lock based on the reference test cases, but I’ve been unable to correctly implement other test cases.

Currently, I’m using tapd version tapcli 0.5.0-alpha.rc2 commit=v0.5.0-rc2. The ImportProof RPC is not functional for me, so I can’t use swap transactions to set a timelock.

[shuishihang]

2025-01-13 11:34:36.559 [ERR] FRTR: Error evaluating state (SendStateStoreProofs): error verifying proof: invalid transfer asset witness: locktime requirement not satisfied -- locktime is greater than the transaction locktime: 44401 > 0

[shuishihang]

Hello, I’m working on implementing a multi-signature and time-lock escrow mechanism, using the approach from a multi-signature test case as a reference. However, when I add the time-lock condition to the vutxo script, I encounter the following error in the logs:
[ERR] FRTR: Error evaluating state (SendStateStoreProofs): error verifying proof: invalid transfer asset witness: locktime requirement not satisfied -- locktime is greater than the transaction locktime: 44796 > 0

When I add the time-lock condition to the utxo script, I encounter the following error:
2025-01-13 16:24:26.259 [INF] FRTR: Broadcasting new transfer tx, txid=87c8aea34b90ccca06deb460583fbcb298c6c0124e8d596d1c4cdf311f107e77
2025-01-13 16:24:26.277 [ERR] BTCN: Broadcast attempt failed:
2025-01-13 16:24:26.299 [WRN] BTWL: Transaction 87c8aea34b90ccca06deb460583fbcb298c6c0124e8d596d1c4cdf311f107e77 not accepted by mempool: mandatory-script-verify-flag-failed (Locktime requirement not satisfied)
2025-01-13 16:24:26.300 [ERR] RPCS: [/walletrpc.WalletKit/PublishTransaction]: mandatory script verify flag failed
2025-01-13 16:24:26.300 [ERR] FRTR: Error evaluating state (SendStateBroadcast): unable to broadcast transaction 87c8aea34b90ccca06deb460583fbcb298c6c0124e8d596d1c4cdf311f107e77: rpc error: code = Unknown desc = mandatory script verify flag failed
2025-01-13 16:24:26.301 [ERR] RPCS: [/assetwalletrpc.AssetWallet/PublishAndLogTransfer]: error requesting delivery: unable to broadcast transaction 87c8aea34b90ccca06deb460583fbcb298c6c0124e8d596d1c4cdf311f107e77: rpc error: code = Unknown desc = mandatory script verify flag failed

The error indicates that the locktime requirement is not satisfied.
Could someone help me understand why this error is occurring? I suspect it’s related to the time-lock condition in the utxo script.
Additionally, I observed that when I set the LockTime field in btcWithdrawPkt.UnsignedTx.LockTime (returned by CommitVirtualPsbts) to the block height corresponding to my escrow, the time-lock condition is satisfied, and the transaction successfully executes. Can anyone explain why this happens and whether I might be overlooking something in how I am setting the time-lock condition in the script?

[guggero]

Can you please show us some of the code you are using? Just from the error it sounds to me like you need to set the LockTime field on the spending asset before you sign it. See

taproot-assets/tappsbt/create.go

Line 109 in 4dcdb21

LockTime: lockTime,

(full integration test example here:

taproot-assets/itest/psbt_test.go

Line 2589 in 5369393

func testPsbtLockTimeSend(t *harnessTest) {

).

[shuishihang]

I’m referring to the multisignature implementation in multisig.go, and I want to use a combination of multisignature and time-lock scripts to create a Taproot address. Is this approach feasible?

Here’s my UTXO script:

btcTapscript, err := txscript.NewScriptBuilder().
    AddData(schnorr.SerializePubKey(aliceInternalKey1.PubKey)).   // Add Alice's public key
    AddOp(txscript.OP_CHECKSIG).                                   // Alice's signature verification
    AddData(schnorr.SerializePubKey(bobInternalKey.PubKey)).         // Add Bob's public key
    AddOp(txscript.OP_CHECKSIGADD).                                 // Bob's signature verification
    AddInt64(2).                                                    // Require at least 2 signatures
    AddOp(txscript.OP_EQUAL).                                       // Compare to meet the signature requirement
    AddInt64(lockTimeBlocks).                                       // Set locktime block height or time
    AddOp(txscript.OP_CHECKLOCKTIMEVERIFY).                         // Time-lock verification
    AddOp(txscript.OP_DROP).                                        // Discard the top value from the stack
    Script()

if err != nil {
    return nil, err
}

In this approach, I am constructing the virtual transaction like this:
withdrawAddr, err := aliceTapd.NewAddr(ctxt, &taprpc.NewAddrRequest{
    AssetId: firstBatchGenesis.AssetId,
    Amt:     assetsToSend / 2,
})
require.NoError(t, err)

// We fund this withdrawal transaction from Bob's tapd, which currently holds
// multisig locked assets.
withdrawRecipients := map[string]uint64{
    withdrawAddr.Encoded: withdrawAddr.Amount,
}
withdrawFundResp, err := bobTapd.FundVirtualPsbt(
    ctxt, &wrpc.FundVirtualPsbtRequest{
        Template: &wrpc.FundVirtualPsbtRequest_Raw{
            Raw: &wrpc.TxTemplate{
                Recipients: withdrawRecipients,
            },
        },
    },
)

After calling CommitVirtualPsbts, I set the UnsignedTx.LockTime field, and once the specified block is generated, the transaction can be successfully completed.

btcWithdrawPkt, finalizedWithdrawPackets, _, commitResp := CommitVirtualPsbts(
    ctx, withdrawBtcPkt, vPackets, nil, -1,
)

btcWithdrawPkt.UnsignedTx.LockTime = uint32(req.LockTime)

I didn’t use ForInteractiveSend because I had previously tried using the itest function functestPsbtLockTimeSend, which executes the sendProof operation. However, when I reached the dst.ImportProof step, I encountered an issue that prevented me from proceeding. Additionally, I tried adding -tag during dev startup, but it didn’t work, and I encountered the following error:

[INF] LITD: LiT version: 0.13.3-alpha commit=
could not create permissions manager: ActiveNetParams must be set to create DevRPC

[guggero]

btcWithdrawPkt.UnsignedTx.LockTime

Setting this on the BTC-level transaction is not enough. You also need to set the LockTime field of the output asset.

ActiveNetParams must be set to create DevRPC

Try litd v0.14.0-alpha, that problem should be gone there.

[shuishihang]

Thank you for your response. Your response has been incredibly helpful to me.I attempted to use litd v0.14.0-alpha and tried the ImportProof functionality. However, I encountered the following error:

Error importing proof: rpc error: code = Unimplemented desc = unknown service tapdevrpc.TapDev.

To address this, I referred to the sendProofUniRPC example. In the code, I had Alice call exportProof and then used the universe server on Bob's side to invoke importProof. After completing the process, I checked Bob's asset list but couldn't find the asset. Additionally, there was no corresponding proof file in the proofs folder.

Could it be that I have misunderstood the process?

[guggero]

Unimplemented desc = unknown service tapdevrpc.TapDev.

That RPC is only available when you build tapd (or litd) with the dev tag. So that wouldn't be available on a production build, that's why you should use the InsertProof (insert into universe) RPC instead of the ImportProof.

But I don't think you have to transfer the proof manually in any case. You should be able to just use a proof courier that uses a universe to transfer the proof. So either in aliceTapd.NewAddr() you specify `ProofCourierAddr: "universerpc://:". Then Alice will act as a universe and Bob will try to look up the proof there automatically.
You'll need to set some extra flags on Alice to allow Bob to call into the universe RPCs, see https://docs.lightning.engineering/lightning-network-tools/taproot-assets/universes#docs-internal-guid-a793947b-7fff-5e06-ddbf-f64bd25da85f.

[shuishihang]

I deeply apologize for taking up so much of your time, and I may not have fully understood your explanation.

Since I have included a time-lock condition in the multisignature setup, it is not sufficient to set btcWithdrawPkt.UnsignedTx.LockTime = uint32(req.LockTime) only at the BTC-level transaction. I also need to set the LockTime field for the output resource.

When constructing a virtual transaction in this way, I can only use the FundVirtualPsbtRequest_Psbt template, as shown below:

fundResp, err := fundPacket(ctx, conn, tappsbt.ForInteractiveSend(
    assetID, req.Amount, bobAssetScriptKey, lockTimeBlocks, 0, 0,
    bobInternalKey, asset.V0, &address.RegressionNetTap,
))
if err != nil {
    return nil, err
}

However, if I use aliceTapd.NewAddr() in a multisignature context, the construction uses the FundVirtualPsbtRequest_Raw template instead:

withdrawAddr, err := aliceTapd.NewAddr(ctxt, &taprpc.NewAddrRequest{
AssetId: firstBatchGenesis.AssetId,
Amt: assetsToSend / 2,
})
require.NoError(t, err)

withdrawRecipients := map[string]uint64{
withdrawAddr.Encoded: withdrawAddr.Amount,
}
withdrawFundResp, err := bobTapd.FundVirtualPsbt(
ctxt, &wrpc.FundVirtualPsbtRequest{
Template: &wrpc.FundVirtualPsbtRequest_Raw{
Raw: &wrpc.TxTemplate{
Recipients: withdrawRecipients,
},
},
},
)

Using this construction method, how can I set the LockTime field for the output resource?

In the functestPsbtLockTimeSend test case, if I only implement the locktime condition, but the aliceTapd.NewAddr() is not included in the code implementation, would I need to manually transfer the proof in such a scenario?

I’ve been studying time-locks, multisignatures, hash time-locks, and trustless swaps, but my thoughts are currently a bit scattered.
If needed, I would be happy to provide the relevant code snippets or the lit.conf file for further clarification.

I have configured taproot-assets.universe.federationserver=132.232.109.84:8443 in both Alice's and Bob's lit.conf files. Does this have any impact?

[guggero]

When you create an address, you are defining the spending conditions for an asset. So when creating the time locked address, you define the conditions as part of the Taproot scripts that are committed to the script key. So basically when creating the address you define the scripts that can be executed, e.g. using txscript.OP_CHECKLOCKTIMEVERIFY and so on.
You then need to create an address using that script, see the example here (and specifically the sendToScriptAddr function that specifies the script key when creating the address:

		ScriptKey: &taprpc.ScriptKey{
			PubKey: schnorr.SerializePubKey(bobAssetScriptKey),
			KeyDesc: taprpc.MarshalKeyDescriptor(
				bobScriptKey.RawKey,
			),
			TapTweak: rootHash,
		},

So with the address created and assets sent to that address, when you want to spend them again, you have to satisfy the conditions imposed on them by the scripts.
That means when you're spending the asset you have to show that you've waited enough blocks to satisfy the time lock.
You do that by setting the TimeLock field on the output asset of the virtual transaction.
It looks like you're already doing that correctly with this code (you pass lockTimeBlocks to tappsbt.ForInteractiveSend, which does exactly that).

So I'm not sure where things go wrong. Perhaps you can paste a link to the full code?

[shuishihang]

Thank you very much for your help. Are you suggesting that when implementing a time lock based on taproot-assets/itest/psbt_test.go, I should refer to the sendToScriptAddr function before proceeding to fundPacket? Should I use a script to create an address and send the assets to that address?

I’m not sure if I’ve fully understood the test case. If the time lock condition is met and I need to send the assets to a new address, does this mean I need to:

Use NewAddr() to create a receiving address, and Use the FundVirtualPsbtRequest_Raw template to execute the transaction?

However, this approach seems to prevent me from setting a time lock on the output assets of the virtual transaction. Alternatively, if I use the FundVirtualPsbtRequest_Psbt template, I wouldn’t be able to use an address-based approach for receiving the assets and would have to rely on sendProof to complete the transaction. Am I misunderstanding something here?

In my time lock implementation, I followed the testPsbtLockTimeSend test case almost exactly. In the code, I didn’t use a script to create an address or send assets to an address. I assumed that testPsbtLockTimeSend doesn’t require a Taproot address and completes the transaction via sendProof.

gist:a448567d2c597a5a2ec8adf81c323943
A few days ago, I implemented a portion of the asset transfer logic based on testPsbtLockTimeSend. However, I haven’t yet completed the part where the asset can be used after the block condition is satisfied. During the implementation, I encountered an issue with the sendProof step:

I divided the sendProof process into two parts:
Alice exported the proof file.
Bob’s node called the universe server to insert the proof file.
Both operations seemed to complete successfully without any errors, but the expected results were not achieved.
Bob’s node did not display the asset or the proof file in its asset list.

When implementing testPsbtTrustlessSwap, I also encountered an issue related to importing proof files in sendUniProof. This issue prevented me from successfully completing the trustless swap. I attempted to use sendProofUniRPC instead, but it also failed, and no errors appeared in the logs.

I suspect that the root of the problem lies in the proof file import process. If I correctly implement the functionality of sendProof and successfully import the proof file into Bob’s node, would that resolve all the issues?

[shuishihang]

How can I import the proof file for asset transfers into the recipient's node? Both nodes are configured to use the same Universe server. Following the sendProofUniRPC reference, I had Alice export the proof file and then used the Universe server to call InsertProof. All these steps were completed without any errors. However, the recipient's node still hasn't received the proof file for the asset transfer, and the corresponding asset is not listed in their asset list.

If using ImportProof is not an option, is there any alternative way to ensure that the node successfully imports the proof file? I would greatly appreciate any guidance or suggestions on this matter.

The reason I'm asking this question is that I used a timelock script to create an address for implementing a timelock. To eventually spend the asset, the timelock condition must be satisfied by setting the LockTime field on the spending asset before signing. Here’s how it is configured:

fundResp, err := fundPacket(ctx, conn, tappsbt.ForInteractiveSend(
    assetID, req.Amount, bobAssetScriptKey, lockTimeBlocks, 0, 0,
    bobInternalKey, asset.V0, &address.RegressionNetTap,
))
if err != nil {
    return nil, err
}

However, there is a significant limitation with this approach: I cannot use a Taproot address to receive this asset. Instead, I have to rely on the test case's sendProof method to complete the final transaction. The main issue is that I cannot properly import the proof file.

The failure to successfully import the proof file on the recipient's side has left me completely stuck.

My question might be quite basic, but I sincerely hope to receive your guidance and assistance.

[guggero]

Ah, sorry, my bad.

Try this instead:

	bobAssetScriptKey := &taprpc.ScriptKey{
		PubKey:   schnorr.SerializePubKey(tweakedTaprootKey),
		KeyDesc:  req.BobScriptKey.KeyDesc,
		TapTweak: rootHash,
	}

[shuishihang]

Thank you so much for your help! I believe I’ve successfully implemented the functionality, but I have a question and I’m not sure if it indicates an issue.

When I attempt to spend without meeting the required conditions, AnchorVirtualPsbts does not return an error. However, after generating a block, the following log entry appears:

2025-01-21 13:35:42.132 [ERR] FRTR: Error evaluating state (SendStateStorePostAnchorTxConf): unable to store proofs: error verifying proof: un-finalized asset: block_height=46721, min_height=46723

When I check the asset list, the asset remains in an unconfirmed state. Even though the block height has now reached 46723, satisfying the required conditions, the asset is still listed under unconfirmed_transfers.

Is this behavior expected? If an asset remains in the unconfirmed_transfers state, how should I handle it?

If I spend the asset only after meeting the conditions, there are no issues at all.

If there are any issues, I look forward to hearing from you. 😊

[guggero]

Cool, good to know it works!

Hmm, that might be a check that we'll want to add. Because if you spend an asset too early and include it in a block that is too early, it will forever be invalid and you basically burn the assets.
So until we add that check, you'll need to make sure that the correct number of blocks have been mined before publishing the spend transaction!

I'll create an issue. Thanks for the feedback.

[shuishihang]

Thank you for your reply，I have a question regarding the implementation of HTLC (Hash Time-Locked Contract). In a typical scenario, an address with a hash time lock is created, and Alice sends the assets to this address. Bob can unlock the assets by providing the correct hash value (pre-image). If Bob does not provide the hash value within a certain time, Alice can reclaim the assets once the time lock condition is met.

The question is: who should create this HTLC address? If Alice creates the address, how can Bob construct the transaction after providing the hash value? On the other hand, if Bob creates the address, how can Alice reclaim the assets?

[guggero]

The short answer is: They both decide on the exact scripts to use first, through out of band communication. And only once they agree and come up with the exact same script does the recipient create the address and the sender send to it.
So they both know at any time what spending conditions are required. The only thing they don't both know yet is the pre-image to the hash, but that's kind of the point that this can be learned in exchange for another transaction somewhere, making this an atomic swap.

If you want to learn more, one example of such an atomic swap is the so called "submarine swap" (which is what "Lightning Loop" implements): https://www.voltage.cloud/blog/submarine-swaps-how-do-they-work-and-where-they-are-used

The same principle can be applied to both on-chain BTC as well as assets, since they both operate on the same scripting language.