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?