candle-launch-bot 0.0.0-stage → 0.1.0

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.

Potentially problematic release.


This version of candle-launch-bot might be problematic. Click here for more details.

Files changed (66) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/LICENSE +21 -0
  3. package/README.md +400 -2
  4. package/bin/candle-launch-bot +7 -0
  5. package/dist/alerts.d.ts +28 -0
  6. package/dist/alerts.js +82 -0
  7. package/dist/cli.d.ts +3 -0
  8. package/dist/cli.js +321 -0
  9. package/dist/config.d.ts +88 -0
  10. package/dist/config.js +244 -0
  11. package/dist/detect/detector.d.ts +111 -0
  12. package/dist/detect/detector.js +348 -0
  13. package/dist/engine.d.ts +103 -0
  14. package/dist/engine.js +585 -0
  15. package/dist/exec/executor.d.ts +149 -0
  16. package/dist/exec/executor.js +859 -0
  17. package/dist/exec/fills.d.ts +25 -0
  18. package/dist/exec/fills.js +53 -0
  19. package/dist/exec/trader.d.ts +109 -0
  20. package/dist/exec/trader.js +310 -0
  21. package/dist/filters.d.ts +26 -0
  22. package/dist/filters.js +92 -0
  23. package/dist/index.d.ts +5 -0
  24. package/dist/index.js +2 -0
  25. package/dist/init.d.ts +23 -0
  26. package/dist/init.js +192 -0
  27. package/dist/ledger.d.ts +189 -0
  28. package/dist/ledger.js +243 -0
  29. package/dist/log.d.ts +22 -0
  30. package/dist/log.js +40 -0
  31. package/dist/market/curve.d.ts +80 -0
  32. package/dist/market/curve.js +168 -0
  33. package/dist/market/reader.d.ts +37 -0
  34. package/dist/market/reader.js +106 -0
  35. package/dist/redact.d.ts +20 -0
  36. package/dist/redact.js +111 -0
  37. package/dist/solana/base58.d.ts +4 -0
  38. package/dist/solana/base58.js +45 -0
  39. package/dist/solana/logs-ws.d.ts +25 -0
  40. package/dist/solana/logs-ws.js +116 -0
  41. package/dist/solana/pda.d.ts +12 -0
  42. package/dist/solana/pda.js +70 -0
  43. package/dist/solana/rpc.d.ts +29 -0
  44. package/dist/solana/rpc.js +96 -0
  45. package/dist/strategies/hold.d.ts +3 -0
  46. package/dist/strategies/hold.js +6 -0
  47. package/dist/strategies/ladder.d.ts +8 -0
  48. package/dist/strategies/ladder.js +51 -0
  49. package/dist/strategies/load.d.ts +5 -0
  50. package/dist/strategies/load.js +44 -0
  51. package/dist/strategies/preGrad.d.ts +10 -0
  52. package/dist/strategies/preGrad.js +32 -0
  53. package/dist/strategies/time.d.ts +6 -0
  54. package/dist/strategies/time.js +16 -0
  55. package/dist/strategies/tpsl.d.ts +8 -0
  56. package/dist/strategies/tpsl.js +30 -0
  57. package/dist/strategies/types.d.ts +55 -0
  58. package/dist/strategies/types.js +31 -0
  59. package/examples/dry.json +32 -0
  60. package/examples/live-embedded.json +14 -0
  61. package/examples/live-linked.json +15 -0
  62. package/examples/strategies/breakeven-stop.js +22 -0
  63. package/examples/strategies/stale-coin.js +18 -0
  64. package/examples/strategies/timeboxed-tp.js +18 -0
  65. package/package.json +60 -4
  66. package/skills/candle-launch-bot/SKILL.md +71 -0
@@ -0,0 +1,149 @@
1
+ /**
2
+ * The order executor. Every order is one row with its own attempt clock; each sweep claims due orders in one
3
+ * statement and runs at most one attempt each. Nothing in an attempt sleeps: a read that is not ready yet
4
+ * reschedules the order, so exits and STOP stay responsive.
5
+ *
6
+ * Rules (each one failed on a live wallet somewhere):
7
+ * - quantity and proceeds are booked from the transaction's balance deltas, never the quote
8
+ * - attempts are capped, backoff is jittered and scheduled per order (next_attempt_at), and a throw costs an
9
+ * attempt exactly like a failure
10
+ * - the terminal state is sticky one layer up: a position whose exit orders keep failing goes `exit_stuck`
11
+ * - errors branch on `.code` / `.status` / `.stage` / `.reason`, never on message text; logs are stored in full
12
+ * - a refusal is definite only when Candle says so for a step that broadcasts nothing (build/sign, 4xx, not
13
+ * retryable); transport failures (fetch failed, ECONNRESET, timeouts, 5xx) are always retried
14
+ * - the signature is persisted BEFORE submit; before any rebuild the persisted signature is checked on chain and
15
+ * its blockhash must be expired by block height (isBlockhashValid false), so no two transactions of one order
16
+ * can ever be live at once
17
+ */
18
+ import type { Config } from "../config.ts";
19
+ import type { Logger } from "../log.ts";
20
+ import type { Ledger } from "../ledger.ts";
21
+ import type { Alerter } from "../alerts.ts";
22
+ import { type Rpc } from "../solana/rpc.ts";
23
+ import { type TradeRail } from "./trader.ts";
24
+ /** Lease while an attempt runs: longer than every timeout inside one attempt put together. */
25
+ export declare const LEASE_MS = 180000;
26
+ /** Failed reads of a landed transaction before the bot books from Candle's numbers instead (and alerts). */
27
+ export declare const TX_READ_CAP = 6;
28
+ /** Never judge a signature dead sooner than this after signing, whatever the chain says (clock skew, RPC lag). */
29
+ export declare const SIGNATURE_MIN_AGE_MS = 20000;
30
+ /** Re-scans of the wallet for an ending buy's tokens that are there but not yet explained (RPC lag), on the backoff. */
31
+ export declare const ADOPT_SCAN_CAP = 10;
32
+ /** Pages of token-account history read per scan (100 signatures each), stopping at the order's creation. */
33
+ export declare const ADOPT_PAGES = 10;
34
+ /** An ending buy scans at least this long (the balance and history may lag a trade that just landed). */
35
+ export declare const ENDING_MIN_MS = 120000;
36
+ /** A transaction of an attempt can land up to this long after the attempt's call ended (its blockhash life, with margin). */
37
+ export declare const ATTEMPT_LAND_SEC = 150;
38
+ export interface DryPricer {
39
+ /** Tokens out (raw) for spending `lamports` on the coin now. */
40
+ buyOut(mint: string, lamports: bigint): Promise<bigint>;
41
+ /** Lamports out for selling `raw` tokens now. */
42
+ sellOut(mint: string, raw: bigint, decimals: number): Promise<bigint>;
43
+ }
44
+ export interface ExecutorDeps {
45
+ cfg: Config;
46
+ ledger: Ledger;
47
+ rail: TradeRail | null;
48
+ /** The TEE wallet's linked-wallet id (the build's payer). */
49
+ linkedWalletId?: string;
50
+ rpc: Rpc;
51
+ log: Logger;
52
+ alerter: Alerter;
53
+ dry?: DryPricer;
54
+ now?: () => number;
55
+ random?: () => number;
56
+ /** PAUSE_BUYS: a queued buy is not built while this says true. */
57
+ buysPaused?: () => boolean;
58
+ }
59
+ export interface ErrorInfo {
60
+ code: string;
61
+ /** True when the error is Candle's own structured refusal (CandleApiError: string code + HTTP status). */
62
+ candle: boolean;
63
+ status?: number;
64
+ retryable: boolean;
65
+ stage?: string;
66
+ reason?: string;
67
+ signature?: string;
68
+ recorded?: boolean;
69
+ retryAfter?: number;
70
+ logs?: string[];
71
+ }
72
+ /** Read an error's structure. Only a CandleApiError can be a definite refusal; everything else is retryable. */
73
+ export declare function errorInfo(e: unknown): ErrorInfo;
74
+ export declare class Executor {
75
+ private d;
76
+ private now;
77
+ private random;
78
+ constructor(d: ExecutorDeps);
79
+ backoffMs(attempts: number): number;
80
+ /**
81
+ * Run one attempt for each due order, sells first, claiming ONE order at a time (so no claimed order waits behind
82
+ * others while its lease runs), until `limit` orders, the time budget, or a stop request. Never throws.
83
+ */
84
+ sweep(limit?: number, opts?: {
85
+ onlyIds?: number[];
86
+ side?: "buy" | "sell";
87
+ reconcileOnly?: boolean;
88
+ budgetMs?: number;
89
+ shouldStop?: () => boolean;
90
+ }): Promise<void>;
91
+ private runOne;
92
+ private attempt;
93
+ /** Would this order still be placed now? Sells always; a buy only before its deadline, unpaused, impact passing. */
94
+ private buyStillGood;
95
+ /** End a buy that may have executed: book our tx or adopt its tokens if found, re-scan while unexplained, else end. */
96
+ private endBuy;
97
+ /** The one same-id probe of a long-built main job: only its answer is used (a signature to reconcile, or a wait). */
98
+ private probe;
99
+ /** Before rebuilding a buy, the market must still be the one the filter approved (no chasing a pump). */
100
+ private recheckBuy;
101
+ private classify;
102
+ private revertedOutcome;
103
+ /**
104
+ * A possibly executed buy about to end: find what it did to the wallet before ending it. In order:
105
+ * 1. our transaction(s) in the token account's history since the order was made (buys of about the ticket that no
106
+ * order has booked): booked from the transaction; two or more (a double execution) are all booked, alerted
107
+ * 2. tokens received since the order in unbooked transactions, up to a loose cap on the order's expected fill
108
+ * 3. tokens in the wallet that nothing explains yet: the history or a transaction may lag behind the balance, so
109
+ * the order stays pending and the scan repeats on the backoff (bounded by ADOPT_SCAN_CAP, alerted)
110
+ * Returns null when the order can end with nothing adopted. From the first call on the order is `ending`: later
111
+ * attempts only scan, never build.
112
+ */
113
+ private unexplainedTokens;
114
+ /**
115
+ * The token account history since the order was made: `found` are our buys of this order (about the ticket's SOL,
116
+ * landed inside one of the order's attempt windows, not booked by any order); `gained` is the net tokens received
117
+ * since the order in unbooked transactions that spent SOL (a transfer-in is not a fill). Paged back to the order's
118
+ * creation; `incomplete` when a transaction or its time could not be read. A read failure returns a wait outcome.
119
+ */
120
+ private scanSince;
121
+ /** The adoption cap: the order's expected fill plus slippage, x1.5 (a better fill than at decision time). */
122
+ private adoptCap;
123
+ /**
124
+ * For `sell` on a coin whose buy ended failed or rejected: how many wallet tokens that buy can claim. Our own
125
+ * transaction(s) found in its attempt windows (their tokens, their cost), else tokens received since the order for SOL,
126
+ * up to the adoption cap (cost the ticket). Never a bag that was already there or arrived by transfer.
127
+ */
128
+ reopenable(orderId: number): Promise<{
129
+ amount: bigint;
130
+ costLamports: bigint;
131
+ signatures: string[];
132
+ } | {
133
+ why: string;
134
+ }>;
135
+ /** A status or job read failed: no attempt is spent; reads are counted, alerted in buckets and backed off. */
136
+ private readFailed;
137
+ /** The signature landed: read its transaction once and book from it; if unreadable, come back later. */
138
+ private landed;
139
+ /** Settle a persisted signature. Returns an outcome when it is decided, or null to go on building. */
140
+ private reconcileSignature;
141
+ private apply;
142
+ private terminal;
143
+ private terminalTx;
144
+ private bookReverted;
145
+ private bookFill;
146
+ private bookFillTx;
147
+ private dryAttempt;
148
+ private alert;
149
+ }