|
| 1 | +# buildAnnounceL1EarlyExit |
| 2 | + |
| 3 | +Builds an unsigned contract call to pox-5 `announce-l1-early-exit`, which tells pox-5 that a staker has left their L1 BTC lockup early. pox-5 stops counting the staker's BTC for the rest of the bond; their STX stays locked. |
| 4 | + |
| 5 | +*** |
| 6 | + |
| 7 | +### Usage |
| 8 | + |
| 9 | +```ts |
| 10 | +import { |
| 11 | + buildAnnounceL1EarlyExit, |
| 12 | + fetchBondMembership, |
| 13 | + fetchEligibleAnnounceL1EarlyExit, |
| 14 | +} from '@stacks/bitcoin-staking'; |
| 15 | +import { |
| 16 | + Pc, |
| 17 | + TransactionSigner, |
| 18 | + broadcastTransaction, |
| 19 | + fetchNonce, |
| 20 | + privateKeyToAddress, |
| 21 | + privateKeyToPublic, |
| 22 | + publicKeyToHex, |
| 23 | +} from '@stacks/transactions'; |
| 24 | + |
| 25 | +const network = 'mainnet'; |
| 26 | +const privateKey = process.env.STAKER_KEY!; |
| 27 | +const staker = privateKeyToAddress(privateKey, network); |
| 28 | + |
| 29 | +const membership = await fetchBondMembership({ address: staker, network }); |
| 30 | +if (!membership?.isL1Lock) throw new Error('no active L1 bond membership'); |
| 31 | +const oldSignerManager = membership.signer; |
| 32 | + |
| 33 | +const check = await fetchEligibleAnnounceL1EarlyExit({ staker, oldSignerManager, network }); |
| 34 | +if (!check.ok) throw new Error(`announce-l1-early-exit would fail: ${check.reasons}`); |
| 35 | + |
| 36 | +const tx = await buildAnnounceL1EarlyExit({ |
| 37 | + staker, |
| 38 | + oldSignerManager, |
| 39 | + publicKey: publicKeyToHex(privateKeyToPublic(privateKey)), |
| 40 | + fee: 10_000n, // micro-STX |
| 41 | + nonce: await fetchNonce({ address: staker, network }), |
| 42 | + network, |
| 43 | + postConditions: [Pc.principal(staker).willPerformPox()], |
| 44 | +}); |
| 45 | + |
| 46 | +new TransactionSigner(tx).signOrigin(privateKey); |
| 47 | +const result = await broadcastTransaction({ transaction: tx, network }); |
| 48 | +``` |
| 49 | + |
| 50 | +#### Notes |
| 51 | + |
| 52 | +* The staker must send it. pox-5 requires `contract-caller`, `tx-sender` and `staker` to be the same principal, so a call forwarded through another contract also fails with `ERR_UNAUTHORIZED (u1)` ([pox-5.clar L1175-L1257](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1175-L1257)). |
| 53 | +* Only for a membership backed by an L1 lockup (`isL1Lock`): an sBTC-backed membership fails with `ERR_CANNOT_ANNOUNCE_L1_EARLY_UNLOCK (u35)` and withdraws with [buildUnstakeSbtc](buildunstakesbtc.md) instead. |
| 54 | +* Also fails with `ERR_NOT_BOND_PARTICIPANT (u34)` when the staker has no bond membership or its bond has ended, `ERR_STAKE_IN_PREPARE_PHASE (u47)` in the last `prepareCycleLength` Bitcoin blocks of a reward cycle (100 on mainnet), and `ERR_INVALID_OLD_SIGNER_MANAGER (u36)` when `oldSignerManager` is not the bound signer-manager. |
| 55 | +* A second announcement for the same bond fails with `ERR_L1_EARLY_EXIT_ALREADY_ANNOUNCED (u50)`. Check with [fetchHasAnnouncedL1EarlyExit](../fetch/fetchhasannouncedl1earlyexit.md). |
| 56 | +* [fetchEligibleAnnounceL1EarlyExit](../eligibility/fetcheligibleannouncel1earlyexit.md) dry-runs every check except the caller check. |
| 57 | +* On success, pox-5 settles the staker's rewards, then sets their bond shares to zero from the current reward cycle, or the bond's first reward cycle if it has not started, through the end of the bond, reduces the bond totals by the same sats, and sets the membership's `amount-sats` to 0. The locked STX is untouched and unlocks on the bond's normal schedule. |
| 58 | +* `announce-l1-early-exit` is a position-altering PoX action for the sender ([pox\_5.rs](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/pox-locking/src/pox_5.rs#L572-L584)). In the default `deny` mode, and in `originator` mode, the node aborts the transaction unless it carries a PoX post condition for the sender, such as `Pc.principal(staker).willPerformPox()` ([node check](https://github.com/stacks-network/stacks-core/blob/10474cdec9f9c0bdf05841b58cffc89cdad87a9b/crates/stacks-transactions/src/lib.rs#L462-L494)). No Stacks asset moves, so no other post condition is needed. |
| 59 | +* A txid from [broadcastTransaction](../../stacks-transactions/network/broadcastTransaction.md) confirms submission only. The call can still fail on-chain: read the mined transaction's result and pass an `(err uN)` to [parsePox5Error](../errors/parsepox5error.md). |
| 60 | + |
| 61 | +[**Reference Link**](https://github.com/stx-labs/stacks.js/blob/6101c99efe5a9616ce7e16cef68e28fd10676e7e/packages/bitcoin-staking/src/build.ts#L356-L394) |
| 62 | + |
| 63 | +*** |
| 64 | + |
| 65 | +### Signature |
| 66 | + |
| 67 | +```ts |
| 68 | +function buildAnnounceL1EarlyExit( |
| 69 | + args: { |
| 70 | + staker: string; |
| 71 | + oldSignerManager: string; |
| 72 | + } & TxParams |
| 73 | +): Promise<StacksTransactionWire>; |
| 74 | +``` |
| 75 | + |
| 76 | +The transaction fields come from [TxParams](../types/txparams.md). |
| 77 | + |
| 78 | +*** |
| 79 | + |
| 80 | +### Returns |
| 81 | + |
| 82 | +`Promise<StacksTransactionWire>` |
| 83 | + |
| 84 | +Resolves to an unsigned [StacksTransactionWire](../../stacks-transactions/signing/StacksTransactionWire.md) that calls pox-5 `announce-l1-early-exit`. Sign it with [TransactionSigner](../../stacks-transactions/signing/TransactionSigner.md), then send it with [broadcastTransaction](../../stacks-transactions/network/broadcastTransaction.md). |
| 85 | + |
| 86 | +*** |
| 87 | + |
| 88 | +### Parameters |
| 89 | + |
| 90 | +#### args.staker (required) |
| 91 | + |
| 92 | +* **Type**: `string` |
| 93 | + |
| 94 | +Stacks address of the staker. It must be the address that signs the transaction. |
| 95 | + |
| 96 | +#### args.oldSignerManager (required) |
| 97 | + |
| 98 | +* **Type**: `string` |
| 99 | + |
| 100 | +Contract principal of the signer-manager the membership is bound to. [fetchBondMembership](../fetch/fetchbondmembership.md) returns it as `signer`. |
| 101 | + |
| 102 | +#### args.fee (required) |
| 103 | + |
| 104 | +* **Type**: `IntegerType` |
| 105 | + |
| 106 | +Transaction fee in micro-STX. |
| 107 | + |
| 108 | +#### args.nonce (required) |
| 109 | + |
| 110 | +* **Type**: `IntegerType` |
| 111 | + |
| 112 | +Nonce of the origin account. Read it with [fetchNonce](../../stacks-transactions/network/fetchNonce.md). |
| 113 | + |
| 114 | +#### args.network (required) |
| 115 | + |
| 116 | +* **Type**: `StacksNetworkName | StacksNetwork` |
| 117 | + |
| 118 | +A name such as `'mainnet'` or `'testnet'`, or a [StacksNetwork](../../stacks-network/network/StacksNetwork.md) object. Sets the contract address (the network's boot address, `SP000000000000000000002Q6VF78` on mainnet) and the transaction version and chain ID. |
| 119 | + |
| 120 | +#### args.publicKey (required for a single-sig origin) |
| 121 | + |
| 122 | +* **Type**: `string` |
| 123 | + |
| 124 | +Hex public key of the account that signs the transaction. |
| 125 | + |
| 126 | +#### args.publicKeys and args.numSignatures (required for a multisig origin) |
| 127 | + |
| 128 | +* **Type**: `PublicKey[]` and `number` |
| 129 | + |
| 130 | +Pass these instead of `publicKey` to build for an M-of-N multisig origin. This package defaults `useNonSequentialMultiSig` to `true`; pass `false` for the sequential hash mode. Pass `address` to check the key order against the multisig address. |
| 131 | + |
| 132 | +#### args.postConditions (optional) |
| 133 | + |
| 134 | +* **Type**: `PostCondition[]` |
| 135 | + |
| 136 | +[Post conditions](../../stacks-transactions/types/PostCondition.md) to attach. The builder adds none. |
| 137 | + |
| 138 | +#### args.postConditionMode (optional) |
| 139 | + |
| 140 | +* **Type**: `PostConditionModeName` |
| 141 | + |
| 142 | +`'allow'`, `'deny'` or `'originator'`. Defaults to `'deny'`. |
0 commit comments