@soltracer/nft-staking 0.2.4 → 0.2.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/INTEGRATION.md +24 -0
- package/dist/helpers.d.ts +39 -4
- package/dist/helpers.d.ts.map +1 -1
- package/dist/helpers.js +30 -6
- package/dist/helpers.js.map +1 -1
- package/package.json +1 -1
package/INTEGRATION.md
CHANGED
|
@@ -143,6 +143,30 @@ const ix = await client.createStakePool(
|
|
|
143
143
|
Lock tier reward rates override the base rate for NFTs staked into that tier. Set `allowUnlockedStaking: false` for
|
|
144
144
|
pools where every stake must choose a lock tier.
|
|
145
145
|
|
|
146
|
+
#### Permanent (irreversible) lock tier
|
|
147
|
+
|
|
148
|
+
Use `PERMANENT_LOCK_DURATION` (= `-1`) as a tier's `lockDuration` to mark it as **permanent**: NFTs staked into
|
|
149
|
+
that tier get `lock_expires_at = i64::MAX` on-chain and can **never** be unstaked. If the pool has
|
|
150
|
+
`canBurn: true`, the staker may instead choose to burn the asset via `burnStakedNft` / `burnStakedCoreNft`.
|
|
151
|
+
|
|
152
|
+
```ts
|
|
153
|
+
import { PERMANENT_LOCK_DURATION } from "@soltracer/nft-staking"
|
|
154
|
+
|
|
155
|
+
await client.createStakePool(
|
|
156
|
+
0,
|
|
157
|
+
rewardConfig,
|
|
158
|
+
[
|
|
159
|
+
{ lockDuration: 0, rewardRate: 100, earlyUnstakePenaltyBps: 0, claimOnlyAtEnd: false },
|
|
160
|
+
{ lockDuration: 30 * 86400, rewardRate: 150, earlyUnstakePenaltyBps: 500, claimOnlyAtEnd: false },
|
|
161
|
+
// Permanent burn-tier: 5x the base reward rate, never unstakable; if pool.canBurn = true the staker may burn instead.
|
|
162
|
+
{ lockDuration: PERMANENT_LOCK_DURATION, rewardRate: 500, earlyUnstakePenaltyBps: 0, claimOnlyAtEnd: false },
|
|
163
|
+
],
|
|
164
|
+
collectionMint,
|
|
165
|
+
)
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
> ⚠️ Any non-zero negative value other than `-1` is rejected on-chain. Always use the `PERMANENT_LOCK_DURATION` constant rather than a magic number.
|
|
169
|
+
|
|
146
170
|
### Update Pool
|
|
147
171
|
|
|
148
172
|
```ts
|
package/dist/helpers.d.ts
CHANGED
|
@@ -16,11 +16,46 @@ export interface ClaimLockStatus {
|
|
|
16
16
|
export declare function getClaimLockStatus(staker: Pick<StakerAccount, "claimLockedUntil">, nowSeconds?: number): ClaimLockStatus;
|
|
17
17
|
/** Sentinel index meaning "no lock tier". Mirrors `shared_types::NO_LOCK_TIER`. */
|
|
18
18
|
export declare const NO_LOCK_TIER = 255;
|
|
19
|
+
/**
|
|
20
|
+
* Sentinel value for a permanent (irreversible) lock tier.
|
|
21
|
+
*
|
|
22
|
+
* Mirrors `shared_types::PERMANENT_LOCK_DURATION = -1`. Set
|
|
23
|
+
* `LockTierInput.lockDuration` to this value to mark a tier as permanent:
|
|
24
|
+
* staking under it sets `lock_expires_at = i64::MAX`, the asset can never be
|
|
25
|
+
* unstaked, and (if `allowBurn = true` on the pool) the staker may instead
|
|
26
|
+
* choose to burn it via `burnStakedNft` / `burnStakedCoreNft`.
|
|
27
|
+
*
|
|
28
|
+
* @example
|
|
29
|
+
* ```ts
|
|
30
|
+
* import { PERMANENT_LOCK_DURATION } from "@soltracer/nft-staking"
|
|
31
|
+
*
|
|
32
|
+
* await client.updateStakePool(poolId, {
|
|
33
|
+
* lockTiers: [
|
|
34
|
+
* { lockDuration: 0, rewardRate: 100, claimOnlyAtEnd: false, earlyUnstakePenaltyBps: 0 },
|
|
35
|
+
* { lockDuration: 30 * 86400, rewardRate: 150, claimOnlyAtEnd: false, earlyUnstakePenaltyBps: 5000 },
|
|
36
|
+
* { lockDuration: PERMANENT_LOCK_DURATION, rewardRate: 500, claimOnlyAtEnd: false, earlyUnstakePenaltyBps: 0 },
|
|
37
|
+
* ],
|
|
38
|
+
* })
|
|
39
|
+
* ```
|
|
40
|
+
*/
|
|
41
|
+
export declare const PERMANENT_LOCK_DURATION = -1;
|
|
19
42
|
export interface LockTierInput {
|
|
20
|
-
/**
|
|
43
|
+
/**
|
|
44
|
+
* Lock duration in seconds. Must be `> 0` for a normal locked tier, or
|
|
45
|
+
* `PERMANENT_LOCK_DURATION` (= -1) to mark the tier as permanent — staked
|
|
46
|
+
* assets under a permanent tier set `lock_expires_at = i64::MAX` and can
|
|
47
|
+
* never be unstaked (they may only be burned via `burnStakedNft` if the
|
|
48
|
+
* pool has `allowBurn = true`).
|
|
49
|
+
*/
|
|
21
50
|
lockDuration: number | bigint;
|
|
22
|
-
/**
|
|
23
|
-
|
|
51
|
+
/**
|
|
52
|
+
* Absolute per-interval reward rate for this tier. Overrides
|
|
53
|
+
* `pool.rewardConfig.baseRate` for assets staked into this tier (it is NOT a
|
|
54
|
+
* multiplier on the base rate). Same units as `baseRate` — token base units
|
|
55
|
+
* per `rateInterval` for token-reward pools, or points per `rateInterval`
|
|
56
|
+
* for points-reward pools. Fits in `u64`.
|
|
57
|
+
*/
|
|
58
|
+
rewardRate: number | bigint;
|
|
24
59
|
/** When true, rewards can only be claimed at unstake. */
|
|
25
60
|
claimOnlyAtEnd: boolean;
|
|
26
61
|
/** BPS forfeited when unstaking before lock expires. 0..=10000. */
|
|
@@ -35,7 +70,7 @@ export interface BuilderIssue {
|
|
|
35
70
|
}
|
|
36
71
|
export interface BuiltLockTier {
|
|
37
72
|
lockDuration: bigint;
|
|
38
|
-
|
|
73
|
+
rewardRate: bigint;
|
|
39
74
|
claimOnlyAtEnd: boolean;
|
|
40
75
|
earlyUnstakePenaltyBps: number;
|
|
41
76
|
}
|
package/dist/helpers.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAEpD,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,OAAO,CAAA;IACjB,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAA;IACjB,+EAA+E;IAC/E,gBAAgB,EAAE,MAAM,CAAA;CACzB;AAED,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,kBAAkB,CAAC,EAC/C,UAAU,CAAC,EAAE,MAAM,GAClB,eAAe,CAWjB;AAGD,mFAAmF;AACnF,eAAO,MAAM,YAAY,MAAO,CAAA;AAEhC,MAAM,WAAW,aAAa;IAC5B
|
|
1
|
+
{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAEpD,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,OAAO,CAAA;IACjB,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAA;IACjB,+EAA+E;IAC/E,gBAAgB,EAAE,MAAM,CAAA;CACzB;AAED,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,kBAAkB,CAAC,EAC/C,UAAU,CAAC,EAAE,MAAM,GAClB,eAAe,CAWjB;AAGD,mFAAmF;AACnF,eAAO,MAAM,YAAY,MAAO,CAAA;AAEhC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,uBAAuB,KAAK,CAAA;AAEzC,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,YAAY,EAAE,MAAM,GAAG,MAAM,CAAA;IAC7B;;;;;;OAMG;IACH,UAAU,EAAE,MAAM,GAAG,MAAM,CAAA;IAC3B,yDAAyD;IACzD,cAAc,EAAE,OAAO,CAAA;IACvB,mEAAmE;IACnE,sBAAsB,EAAE,MAAM,CAAA;IAC9B,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,OAAO,GAAG,SAAS,CAAA;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,MAAM,CAAA;IAClB,cAAc,EAAE,OAAO,CAAA;IACvB,sBAAsB,EAAE,MAAM,CAAA;CAC/B;AAED,qBAAa,qBAAqB;IAChC,OAAO,CAAC,KAAK,CAAsB;IAEnC,GAAG,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI;IAK9B,oDAAoD;IACpD,QAAQ,IAAI,YAAY,EAAE;IA0D1B,2EAA2E;IAC3E,KAAK,IAAI,aAAa,EAAE;CAczB"}
|
package/dist/helpers.js
CHANGED
|
@@ -12,6 +12,29 @@ export function getClaimLockStatus(staker, nowSeconds) {
|
|
|
12
12
|
}
|
|
13
13
|
/** Sentinel index meaning "no lock tier". Mirrors `shared_types::NO_LOCK_TIER`. */
|
|
14
14
|
export const NO_LOCK_TIER = 0xff;
|
|
15
|
+
/**
|
|
16
|
+
* Sentinel value for a permanent (irreversible) lock tier.
|
|
17
|
+
*
|
|
18
|
+
* Mirrors `shared_types::PERMANENT_LOCK_DURATION = -1`. Set
|
|
19
|
+
* `LockTierInput.lockDuration` to this value to mark a tier as permanent:
|
|
20
|
+
* staking under it sets `lock_expires_at = i64::MAX`, the asset can never be
|
|
21
|
+
* unstaked, and (if `allowBurn = true` on the pool) the staker may instead
|
|
22
|
+
* choose to burn it via `burnStakedNft` / `burnStakedCoreNft`.
|
|
23
|
+
*
|
|
24
|
+
* @example
|
|
25
|
+
* ```ts
|
|
26
|
+
* import { PERMANENT_LOCK_DURATION } from "@soltracer/nft-staking"
|
|
27
|
+
*
|
|
28
|
+
* await client.updateStakePool(poolId, {
|
|
29
|
+
* lockTiers: [
|
|
30
|
+
* { lockDuration: 0, rewardRate: 100, claimOnlyAtEnd: false, earlyUnstakePenaltyBps: 0 },
|
|
31
|
+
* { lockDuration: 30 * 86400, rewardRate: 150, claimOnlyAtEnd: false, earlyUnstakePenaltyBps: 5000 },
|
|
32
|
+
* { lockDuration: PERMANENT_LOCK_DURATION, rewardRate: 500, claimOnlyAtEnd: false, earlyUnstakePenaltyBps: 0 },
|
|
33
|
+
* ],
|
|
34
|
+
* })
|
|
35
|
+
* ```
|
|
36
|
+
*/
|
|
37
|
+
export const PERMANENT_LOCK_DURATION = -1;
|
|
15
38
|
export class LockTierConfigBuilder {
|
|
16
39
|
tiers = [];
|
|
17
40
|
add(tier) {
|
|
@@ -38,11 +61,12 @@ export class LockTierConfigBuilder {
|
|
|
38
61
|
message: "claimOnlyAtEnd requires a positive lockDuration — otherwise rewards are never claimable.",
|
|
39
62
|
});
|
|
40
63
|
}
|
|
41
|
-
|
|
64
|
+
const rate = BigInt(t.rewardRate);
|
|
65
|
+
if (rate < 0n || rate > 0xffffffffffffffffn) {
|
|
42
66
|
issues.push({
|
|
43
67
|
level: "error",
|
|
44
|
-
field: f("
|
|
45
|
-
message: "
|
|
68
|
+
field: f("rewardRate"),
|
|
69
|
+
message: "rewardRate must fit in u64 (0..=2^64 - 1).",
|
|
46
70
|
});
|
|
47
71
|
}
|
|
48
72
|
if (t.earlyUnstakePenaltyBps < 0 || t.earlyUnstakePenaltyBps > 10_000) {
|
|
@@ -52,11 +76,11 @@ export class LockTierConfigBuilder {
|
|
|
52
76
|
message: "earlyUnstakePenaltyBps must be 0..=10000.",
|
|
53
77
|
});
|
|
54
78
|
}
|
|
55
|
-
if (dur < 0n) {
|
|
79
|
+
if (dur < 0n && dur !== BigInt(PERMANENT_LOCK_DURATION)) {
|
|
56
80
|
issues.push({
|
|
57
81
|
level: "error",
|
|
58
82
|
field: f("lockDuration"),
|
|
59
|
-
message: "lockDuration
|
|
83
|
+
message: "lockDuration must be >= 0, or exactly PERMANENT_LOCK_DURATION (-1) to mark the tier as permanent.",
|
|
60
84
|
});
|
|
61
85
|
}
|
|
62
86
|
if (t.claimOnlyAtEnd && t.earlyUnstakePenaltyBps === 0) {
|
|
@@ -79,7 +103,7 @@ export class LockTierConfigBuilder {
|
|
|
79
103
|
}
|
|
80
104
|
return this.tiers.map((t) => ({
|
|
81
105
|
lockDuration: BigInt(t.lockDuration),
|
|
82
|
-
|
|
106
|
+
rewardRate: BigInt(t.rewardRate),
|
|
83
107
|
claimOnlyAtEnd: t.claimOnlyAtEnd,
|
|
84
108
|
earlyUnstakePenaltyBps: t.earlyUnstakePenaltyBps,
|
|
85
109
|
}));
|
package/dist/helpers.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAiBA,MAAM,UAAU,kBAAkB,CAChC,MAA+C,EAC/C,UAAmB;IAEnB,MAAM,GAAG,GAAG,UAAU,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAA;IACvD,MAAM,SAAS,GAAG,MAAM,CAAC,gBAAgB,IAAI,CAAC,CAAA;IAC9C,IAAI,SAAS,KAAK,CAAC,IAAI,GAAG,IAAI,SAAS,EAAE,CAAC;QACxC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,CAAC,EAAE,CAAA;IAC5D,CAAC;IACD,OAAO;QACL,QAAQ,EAAE,IAAI;QACd,SAAS;QACT,gBAAgB,EAAE,SAAS,GAAG,GAAG;KAClC,CAAA;AACH,CAAC;AAGD,mFAAmF;AACnF,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,CAAA;
|
|
1
|
+
{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"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"}
|