@neuraiproject/neurai-rpc 0.4.7 → 0.5.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.
- package/CHANGELOG.md +80 -0
- package/DEPIN_EXAMPLES.md +148 -220
- package/DEPIN_IMPLEMENTATION_GUIDE_EN.md +239 -70
- package/README.md +98 -46
- package/depin.ts +465 -214
- package/dist/depin.cjs +305 -0
- package/dist/depin.d.cts +96 -0
- package/dist/depin.d.ts +96 -0
- package/dist/depin.mjs +280 -0
- package/dist/index.cjs +5251 -4941
- package/dist/{types.d.ts → index.d.cts} +10 -63
- package/dist/index.d.ts +200 -0
- package/dist/index.mjs +5224 -4933
- package/docs.json +140 -134
- package/docs.ts +512 -64
- package/index.ts +13 -9
- package/neurai_methods.md +482 -64
- package/package.json +39 -11
- package/createDocs.mjs +0 -61
- package/dist/index.cjs.map +0 -1
- package/dist/index.mjs.map +0 -1
- package/dist/types.d.ts.map +0 -1
- package/test-depin.ts +0 -187
- package/test.js +0 -56
- package/tsconfig.json +0 -26
package/dist/depin.mjs
ADDED
|
@@ -0,0 +1,280 @@
|
|
|
1
|
+
// depin.ts
|
|
2
|
+
import { createConnection } from "net";
|
|
3
|
+
var DEPIN_SOCKET_TIMEOUT_MS = 3e4;
|
|
4
|
+
var MAX_RESPONSE_BYTES = 10 * 1024 * 1024 + 1024;
|
|
5
|
+
var SIGN_PREFIX = {
|
|
6
|
+
SEND: "DEPIN-SEND",
|
|
7
|
+
RECEIVE: "DEPIN-GET",
|
|
8
|
+
ADMIN: "DEPIN-CLEAR"
|
|
9
|
+
};
|
|
10
|
+
var METHOD_AUTH = {
|
|
11
|
+
depinsendmsg: "SEND",
|
|
12
|
+
depinclearmsg: "ADMIN",
|
|
13
|
+
depingetmsg: "BLOCKED"
|
|
14
|
+
};
|
|
15
|
+
function validateTarget(target) {
|
|
16
|
+
if (typeof target === "string") {
|
|
17
|
+
throw new Error(
|
|
18
|
+
'getDePinRPC no longer accepts a URL string. The DePIN gateway speaks raw TCP, not HTTP: pass an object { host, port }, e.g. { host: "127.0.0.1", port: 19002 }'
|
|
19
|
+
);
|
|
20
|
+
}
|
|
21
|
+
if (!target || typeof target !== "object") {
|
|
22
|
+
throw new Error("A target object { host, port } is required for DePIN RPC");
|
|
23
|
+
}
|
|
24
|
+
if (!target.host || typeof target.host !== "string") {
|
|
25
|
+
throw new Error("target.host must be a non-empty string");
|
|
26
|
+
}
|
|
27
|
+
if (typeof target.port !== "number" || !Number.isInteger(target.port) || target.port < 1 || target.port > 65535) {
|
|
28
|
+
throw new Error("target.port must be an integer between 1 and 65535");
|
|
29
|
+
}
|
|
30
|
+
if (target.timeoutMs !== void 0 && (typeof target.timeoutMs !== "number" || target.timeoutMs <= 0)) {
|
|
31
|
+
throw new Error("target.timeoutMs must be a positive number");
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
function validateAuthOptions(authOptions) {
|
|
35
|
+
if (!authOptions.token) {
|
|
36
|
+
throw new Error("Token is required for DePIN authentication");
|
|
37
|
+
}
|
|
38
|
+
if (!authOptions.address) {
|
|
39
|
+
throw new Error("Address is required for DePIN authentication");
|
|
40
|
+
}
|
|
41
|
+
if (!authOptions.signMessage || typeof authOptions.signMessage !== "function") {
|
|
42
|
+
throw new Error("signMessage function is required for DePIN authentication");
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
function sendLine(target, line) {
|
|
46
|
+
const timeoutMs = target.timeoutMs ?? DEPIN_SOCKET_TIMEOUT_MS;
|
|
47
|
+
return new Promise((resolve, reject) => {
|
|
48
|
+
const socket = createConnection({ host: target.host, port: target.port });
|
|
49
|
+
const chunks = [];
|
|
50
|
+
let received = 0;
|
|
51
|
+
let settled = false;
|
|
52
|
+
const finish = (error, response) => {
|
|
53
|
+
if (settled) {
|
|
54
|
+
return;
|
|
55
|
+
}
|
|
56
|
+
settled = true;
|
|
57
|
+
socket.destroy();
|
|
58
|
+
if (error) {
|
|
59
|
+
reject(error);
|
|
60
|
+
} else {
|
|
61
|
+
resolve(response);
|
|
62
|
+
}
|
|
63
|
+
};
|
|
64
|
+
socket.setTimeout(timeoutMs, () => {
|
|
65
|
+
finish(
|
|
66
|
+
new Error(
|
|
67
|
+
`DePIN request timed out after ${timeoutMs} ms (${target.host}:${target.port})`
|
|
68
|
+
)
|
|
69
|
+
);
|
|
70
|
+
});
|
|
71
|
+
socket.on("error", (e) => {
|
|
72
|
+
finish(
|
|
73
|
+
new Error(
|
|
74
|
+
`Could not communicate with DePIN gateway at ${target.host}:${target.port}: ${e.message}`
|
|
75
|
+
)
|
|
76
|
+
);
|
|
77
|
+
});
|
|
78
|
+
socket.on("connect", () => {
|
|
79
|
+
socket.write(line.endsWith("\n") ? line : line + "\n");
|
|
80
|
+
});
|
|
81
|
+
socket.on("data", (chunk) => {
|
|
82
|
+
chunks.push(chunk);
|
|
83
|
+
received += chunk.length;
|
|
84
|
+
if (received > MAX_RESPONSE_BYTES) {
|
|
85
|
+
finish(new Error("DePIN response exceeded the 10 MB protocol limit"));
|
|
86
|
+
return;
|
|
87
|
+
}
|
|
88
|
+
if (chunk.includes(10)) {
|
|
89
|
+
const all = Buffer.concat(chunks);
|
|
90
|
+
const nl = all.indexOf(10);
|
|
91
|
+
finish(null, all.subarray(0, nl).toString("utf8"));
|
|
92
|
+
}
|
|
93
|
+
});
|
|
94
|
+
socket.on("close", () => {
|
|
95
|
+
finish(
|
|
96
|
+
new Error(
|
|
97
|
+
"DePIN gateway closed the connection before sending a complete response"
|
|
98
|
+
)
|
|
99
|
+
);
|
|
100
|
+
});
|
|
101
|
+
});
|
|
102
|
+
}
|
|
103
|
+
async function requestChallenge(target, token, address, mode) {
|
|
104
|
+
const responseText = await sendLine(
|
|
105
|
+
target,
|
|
106
|
+
`AUTH|${token}|${address}|${mode}`
|
|
107
|
+
);
|
|
108
|
+
if (!responseText.startsWith("CHALLENGE|")) {
|
|
109
|
+
throw new Error(`Invalid challenge response: ${responseText}`);
|
|
110
|
+
}
|
|
111
|
+
const parts = responseText.split("|");
|
|
112
|
+
if (parts.length < 3) {
|
|
113
|
+
throw new Error(`Malformed challenge response: ${responseText}`);
|
|
114
|
+
}
|
|
115
|
+
const challenge = parts[1];
|
|
116
|
+
const timeout = parseInt(parts[2], 10);
|
|
117
|
+
if (!challenge || isNaN(timeout)) {
|
|
118
|
+
throw new Error(`Invalid challenge data: ${responseText}`);
|
|
119
|
+
}
|
|
120
|
+
return {
|
|
121
|
+
challenge,
|
|
122
|
+
timeout,
|
|
123
|
+
messageToSign: `${SIGN_PREFIX[mode]}|${token}|${address}|${challenge}`
|
|
124
|
+
};
|
|
125
|
+
}
|
|
126
|
+
async function freshChallenge(context, mode, token) {
|
|
127
|
+
const auth = context.authOptions;
|
|
128
|
+
const challengeData = await requestChallenge(
|
|
129
|
+
context.target,
|
|
130
|
+
token,
|
|
131
|
+
auth.address,
|
|
132
|
+
mode
|
|
133
|
+
);
|
|
134
|
+
return challengeData.challenge;
|
|
135
|
+
}
|
|
136
|
+
async function signChallenge(auth, mode, token, challenge) {
|
|
137
|
+
const messageToSign = `${SIGN_PREFIX[mode]}|${token}|${auth.address}|${challenge}`;
|
|
138
|
+
const signature = await auth.signMessage(messageToSign);
|
|
139
|
+
if (!signature) {
|
|
140
|
+
throw new Error("Signature function returned empty result");
|
|
141
|
+
}
|
|
142
|
+
return signature;
|
|
143
|
+
}
|
|
144
|
+
async function buildAuthenticatedParams(context, method, params) {
|
|
145
|
+
const auth = context.authOptions;
|
|
146
|
+
if (method === "depinsendmsg") {
|
|
147
|
+
const sendParams = [...params];
|
|
148
|
+
if (sendParams.length === 3) {
|
|
149
|
+
sendParams.push(auth.address);
|
|
150
|
+
}
|
|
151
|
+
if (sendParams.length < 4 || typeof sendParams[3] !== "string") {
|
|
152
|
+
throw new Error(
|
|
153
|
+
"depinsendmsg over the gateway needs [token, ip, message, fromaddress]"
|
|
154
|
+
);
|
|
155
|
+
}
|
|
156
|
+
if (sendParams[3] !== auth.address) {
|
|
157
|
+
throw new Error(
|
|
158
|
+
`depinsendmsg fromaddress (${sendParams[3]}) must be the authenticated address (${auth.address})`
|
|
159
|
+
);
|
|
160
|
+
}
|
|
161
|
+
const token2 = String(sendParams[0]);
|
|
162
|
+
const challenge2 = await freshChallenge(context, "SEND", token2);
|
|
163
|
+
const signature2 = await signChallenge(auth, "SEND", token2, challenge2);
|
|
164
|
+
return {
|
|
165
|
+
params: [...sendParams, challenge2, signature2],
|
|
166
|
+
mode: "SEND",
|
|
167
|
+
token: token2
|
|
168
|
+
};
|
|
169
|
+
}
|
|
170
|
+
if (params.length > 2) {
|
|
171
|
+
throw new Error(
|
|
172
|
+
'depinclearmsg accepts at most [mode, scope], e.g. ["all", "&TOKEN/GENERAL"]'
|
|
173
|
+
);
|
|
174
|
+
}
|
|
175
|
+
const mode = params.length >= 1 ? params[0] : null;
|
|
176
|
+
const scope = params.length === 2 ? params[1] : void 0;
|
|
177
|
+
if (scope !== void 0 && typeof scope !== "string") {
|
|
178
|
+
throw new Error("depinclearmsg scope must be a string");
|
|
179
|
+
}
|
|
180
|
+
const token = scope || auth.token;
|
|
181
|
+
const challenge = await freshChallenge(context, "ADMIN", token);
|
|
182
|
+
const signature = await signChallenge(auth, "ADMIN", token, challenge);
|
|
183
|
+
return {
|
|
184
|
+
params: scope === void 0 ? [mode, auth.address, challenge, signature] : [mode, scope, auth.address, challenge, signature],
|
|
185
|
+
mode: "ADMIN",
|
|
186
|
+
token
|
|
187
|
+
};
|
|
188
|
+
}
|
|
189
|
+
function getDePinRPC(target, authOptions) {
|
|
190
|
+
validateTarget(target);
|
|
191
|
+
if (authOptions !== void 0) {
|
|
192
|
+
validateAuthOptions(authOptions);
|
|
193
|
+
}
|
|
194
|
+
const context = {
|
|
195
|
+
target,
|
|
196
|
+
authOptions
|
|
197
|
+
};
|
|
198
|
+
async function depinRpc(method, params, isRetry = false) {
|
|
199
|
+
try {
|
|
200
|
+
const authKind = METHOD_AUTH[method];
|
|
201
|
+
if (authKind === "BLOCKED") {
|
|
202
|
+
throw new Error(
|
|
203
|
+
"depingetmsg over the DePIN gateway is blocked by a node-side bug (the gateway reads fromaddress from params[3], but depingetmsg carries it at index 1 or 2 and accepts at most 3 arguments). Use depinreceivemsg over the gateway, or call depingetmsg through the node RPC port instead."
|
|
204
|
+
);
|
|
205
|
+
}
|
|
206
|
+
let mode;
|
|
207
|
+
let token;
|
|
208
|
+
let requestParams = params;
|
|
209
|
+
if (authKind !== void 0) {
|
|
210
|
+
if (!context.authOptions) {
|
|
211
|
+
throw new Error(
|
|
212
|
+
`${method} requires authentication: create the client with getDePinRPC(target, { token, address, signMessage })`
|
|
213
|
+
);
|
|
214
|
+
}
|
|
215
|
+
const derived = authKind === "SEND" ? "SEND" : "ADMIN";
|
|
216
|
+
if (context.authOptions.mode && context.authOptions.mode !== derived) {
|
|
217
|
+
throw new Error(
|
|
218
|
+
`${method} needs a ${derived} challenge, which conflicts with mode "${context.authOptions.mode}" in the auth options. The mode option is only honored by requestDePinChallenge(); omit it here \u2014 getDePinRPC derives it per method.`
|
|
219
|
+
);
|
|
220
|
+
}
|
|
221
|
+
const built = await buildAuthenticatedParams(context, method, params);
|
|
222
|
+
requestParams = built.params;
|
|
223
|
+
mode = built.mode;
|
|
224
|
+
token = built.token;
|
|
225
|
+
}
|
|
226
|
+
const requestData = {
|
|
227
|
+
jsonrpc: "2.0",
|
|
228
|
+
id: Math.random(),
|
|
229
|
+
method,
|
|
230
|
+
params: requestParams
|
|
231
|
+
};
|
|
232
|
+
const responseText = await sendLine(
|
|
233
|
+
context.target,
|
|
234
|
+
JSON.stringify(requestData)
|
|
235
|
+
);
|
|
236
|
+
if (responseText.startsWith("ERROR|")) {
|
|
237
|
+
throw new Error(responseText.slice("ERROR|".length));
|
|
238
|
+
}
|
|
239
|
+
let responseData;
|
|
240
|
+
try {
|
|
241
|
+
responseData = JSON.parse(responseText);
|
|
242
|
+
} catch (e) {
|
|
243
|
+
throw new Error(
|
|
244
|
+
`Invalid JSON-RPC response from DePIN gateway: ${responseText.slice(0, 200)}`
|
|
245
|
+
);
|
|
246
|
+
}
|
|
247
|
+
if (responseData.error) {
|
|
248
|
+
if (!isRetry && mode !== void 0 && token !== void 0 && responseData.error.message && responseData.error.message.includes("expired")) {
|
|
249
|
+
return depinRpc(method, params, true);
|
|
250
|
+
}
|
|
251
|
+
throw {
|
|
252
|
+
error: responseData.error,
|
|
253
|
+
description: responseData.error.message || "Unknown error"
|
|
254
|
+
};
|
|
255
|
+
}
|
|
256
|
+
return responseData.result;
|
|
257
|
+
} catch (error) {
|
|
258
|
+
if (error && (error.error || error.description)) {
|
|
259
|
+
throw error;
|
|
260
|
+
}
|
|
261
|
+
throw {
|
|
262
|
+
originalError: error,
|
|
263
|
+
type: "DePinRequestError",
|
|
264
|
+
error: error && error.message || "Failed to communicate with DePIN gateway",
|
|
265
|
+
description: "Check that the DePIN gateway host/port are correct and that the node is running with the gateway enabled"
|
|
266
|
+
};
|
|
267
|
+
}
|
|
268
|
+
}
|
|
269
|
+
return (method, params) => depinRpc(method, params);
|
|
270
|
+
}
|
|
271
|
+
async function requestDePinChallenge(target, authOptions) {
|
|
272
|
+
validateTarget(target);
|
|
273
|
+
validateAuthOptions(authOptions);
|
|
274
|
+
const mode = authOptions.mode || "RECEIVE";
|
|
275
|
+
return requestChallenge(target, authOptions.token, authOptions.address, mode);
|
|
276
|
+
}
|
|
277
|
+
export {
|
|
278
|
+
getDePinRPC,
|
|
279
|
+
requestDePinChallenge
|
|
280
|
+
};
|