@solana/offchain-messages 6.3.1 → 6.3.2-canary-20260313143218
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/package.json +11 -10
- package/src/application-domain.ts +135 -0
- package/src/codecs/application-domain.ts +80 -0
- package/src/codecs/content.ts +24 -0
- package/src/codecs/envelope.ts +165 -0
- package/src/codecs/message-v0.ts +138 -0
- package/src/codecs/message-v1.ts +74 -0
- package/src/codecs/message.ts +109 -0
- package/src/codecs/preamble-common.ts +113 -0
- package/src/codecs/preamble-v0.ts +63 -0
- package/src/codecs/preamble-v1.ts +87 -0
- package/src/codecs/signatures.ts +28 -0
- package/src/codecs/signing-domain.ts +25 -0
- package/src/codecs/version.ts +51 -0
- package/src/content.ts +378 -0
- package/src/envelope-common.ts +19 -0
- package/src/envelope-v0.ts +15 -0
- package/src/envelope-v1.ts +15 -0
- package/src/envelope.ts +46 -0
- package/src/index.ts +22 -0
- package/src/message-v0.ts +114 -0
- package/src/message-v1.ts +10 -0
- package/src/message.ts +8 -0
- package/src/preamble-v0.ts +10 -0
- package/src/preamble-v1.ts +5 -0
- package/src/signatures.ts +266 -0
- package/src/version.ts +1 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@solana/offchain-messages",
|
|
3
|
-
"version": "6.3.
|
|
3
|
+
"version": "6.3.2-canary-20260313143218",
|
|
4
4
|
"description": "Helpers for encoding and decoding messages according to the offchain message specification",
|
|
5
5
|
"homepage": "https://www.solanakit.com/api#solanaoffchain-messages",
|
|
6
6
|
"exports": {
|
|
@@ -33,7 +33,8 @@
|
|
|
33
33
|
"types": "./dist/types/index.d.ts",
|
|
34
34
|
"type": "commonjs",
|
|
35
35
|
"files": [
|
|
36
|
-
"./dist/"
|
|
36
|
+
"./dist/",
|
|
37
|
+
"./src/"
|
|
37
38
|
],
|
|
38
39
|
"sideEffects": false,
|
|
39
40
|
"keywords": [
|
|
@@ -55,14 +56,14 @@
|
|
|
55
56
|
"maintained node versions"
|
|
56
57
|
],
|
|
57
58
|
"dependencies": {
|
|
58
|
-
"@solana/
|
|
59
|
-
"@solana/codecs-
|
|
60
|
-
"@solana/
|
|
61
|
-
"@solana/codecs-numbers": "6.3.
|
|
62
|
-
"@solana/codecs-strings": "6.3.
|
|
63
|
-
"@solana/
|
|
64
|
-
"@solana/nominal-types": "6.3.
|
|
65
|
-
"@solana/
|
|
59
|
+
"@solana/codecs-core": "6.3.2-canary-20260313143218",
|
|
60
|
+
"@solana/codecs-data-structures": "6.3.2-canary-20260313143218",
|
|
61
|
+
"@solana/addresses": "6.3.2-canary-20260313143218",
|
|
62
|
+
"@solana/codecs-numbers": "6.3.2-canary-20260313143218",
|
|
63
|
+
"@solana/codecs-strings": "6.3.2-canary-20260313143218",
|
|
64
|
+
"@solana/errors": "6.3.2-canary-20260313143218",
|
|
65
|
+
"@solana/nominal-types": "6.3.2-canary-20260313143218",
|
|
66
|
+
"@solana/keys": "6.3.2-canary-20260313143218"
|
|
66
67
|
},
|
|
67
68
|
"peerDependencies": {
|
|
68
69
|
"typescript": "^5.0.0"
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
import { assertIsAddress, isAddress } from '@solana/addresses';
|
|
2
|
+
import {
|
|
3
|
+
isSolanaError,
|
|
4
|
+
SOLANA_ERROR__ADDRESSES__INVALID_BYTE_LENGTH,
|
|
5
|
+
SOLANA_ERROR__ADDRESSES__STRING_LENGTH_OUT_OF_RANGE,
|
|
6
|
+
SOLANA_ERROR__OFFCHAIN_MESSAGE__APPLICATION_DOMAIN_STRING_LENGTH_OUT_OF_RANGE,
|
|
7
|
+
SOLANA_ERROR__OFFCHAIN_MESSAGE__INVALID_APPLICATION_DOMAIN_BYTE_LENGTH,
|
|
8
|
+
SolanaError,
|
|
9
|
+
} from '@solana/errors';
|
|
10
|
+
import { Brand, EncodedString } from '@solana/nominal-types';
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* A 32-byte array identifying the application requesting off-chain message signing.
|
|
14
|
+
*
|
|
15
|
+
* This may be any arbitrary bytes. For instance the on-chain address of a program, DAO instance,
|
|
16
|
+
* Candy Machine, et cetera.
|
|
17
|
+
*
|
|
18
|
+
* This field SHOULD be displayed to users as a base58-encoded ASCII string rather than interpreted
|
|
19
|
+
* otherwise.
|
|
20
|
+
*/
|
|
21
|
+
export type OffchainMessageApplicationDomain = Brand<
|
|
22
|
+
EncodedString<string, 'base58'>,
|
|
23
|
+
'OffchainMessageApplicationDomain'
|
|
24
|
+
>;
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* A type guard that returns `true` if the input string conforms to the
|
|
28
|
+
* {@link OffchainMessageApplicationDomain} type, and refines its type for use in your program.
|
|
29
|
+
*
|
|
30
|
+
* @example
|
|
31
|
+
* ```ts
|
|
32
|
+
* import { isOffchainMessageApplicationDomain, OffchainMessageV0 } from '@solana/offchain-messages';
|
|
33
|
+
*
|
|
34
|
+
* if (isOffchainMessageApplicationDomain(applicationDomain)) {
|
|
35
|
+
* // At this point, `applicationDomain` has been refined to an
|
|
36
|
+
* // `OffchainMessageApplcationDomain` that can be used to craft a message.
|
|
37
|
+
* const offchainMessage: OffchainMessageV0 = {
|
|
38
|
+
* applicationDomain:
|
|
39
|
+
* offchainMessageApplicationDomain('HgHLLXT3BVA5m7x66tEp3YNatXLth1hJwVeCva2T9RNx'),
|
|
40
|
+
* // ...
|
|
41
|
+
* };
|
|
42
|
+
* } else {
|
|
43
|
+
* setError(`${applicationDomain} is not a valid application domain for an offchain message`);
|
|
44
|
+
* }
|
|
45
|
+
* ```
|
|
46
|
+
*/
|
|
47
|
+
export function isOffchainMessageApplicationDomain(
|
|
48
|
+
putativeApplicationDomain: string,
|
|
49
|
+
): putativeApplicationDomain is OffchainMessageApplicationDomain {
|
|
50
|
+
return isAddress(putativeApplicationDomain);
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/**
|
|
54
|
+
* From time to time you might acquire a string, that you expect to validate as an offchain message
|
|
55
|
+
* application domain, from an untrusted network API or user input. Use this function to assert that
|
|
56
|
+
* such an arbitrary string is a base58-encoded application domain.
|
|
57
|
+
*
|
|
58
|
+
* @example
|
|
59
|
+
* ```ts
|
|
60
|
+
* import { assertIsOffchainMessageApplicationDomain, OffchainMessageV0 } from '@solana/offchain-messages';
|
|
61
|
+
*
|
|
62
|
+
* // Imagine a function that determines whether an application domain is valid.
|
|
63
|
+
* function handleSubmit() {
|
|
64
|
+
* // We know only that what the user typed conforms to the `string` type.
|
|
65
|
+
* const applicationDomain: string = applicationDomainInput.value;
|
|
66
|
+
* try {
|
|
67
|
+
* // If this type assertion function doesn't throw, then
|
|
68
|
+
* // Typescript will upcast `applicationDomain` to `OffchainMessageApplicationDomain`.
|
|
69
|
+
* assertIsOffchainMessageApplicationDomain(applicationDomain);
|
|
70
|
+
* // At this point, `applicationDomain` is a `OffchainMessageApplicationDomain` that can be
|
|
71
|
+
* // used to craft an offchain message.
|
|
72
|
+
* const offchainMessage: OffchainMessageV0 = {
|
|
73
|
+
* applicationDomain:
|
|
74
|
+
* offchainMessageApplicationDomain('HgHLLXT3BVA5m7x66tEp3YNatXLth1hJwVeCva2T9RNx'),
|
|
75
|
+
* // ...
|
|
76
|
+
* };
|
|
77
|
+
* } catch (e) {
|
|
78
|
+
* // `applicationDomain` turned out not to be a base58-encoded application domain
|
|
79
|
+
* }
|
|
80
|
+
* }
|
|
81
|
+
* ```
|
|
82
|
+
*/
|
|
83
|
+
export function assertIsOffchainMessageApplicationDomain(
|
|
84
|
+
putativeApplicationDomain: string,
|
|
85
|
+
): asserts putativeApplicationDomain is OffchainMessageApplicationDomain {
|
|
86
|
+
try {
|
|
87
|
+
assertIsAddress(putativeApplicationDomain);
|
|
88
|
+
} catch (error) {
|
|
89
|
+
if (isSolanaError(error, SOLANA_ERROR__ADDRESSES__STRING_LENGTH_OUT_OF_RANGE)) {
|
|
90
|
+
throw new SolanaError(
|
|
91
|
+
SOLANA_ERROR__OFFCHAIN_MESSAGE__APPLICATION_DOMAIN_STRING_LENGTH_OUT_OF_RANGE,
|
|
92
|
+
error.context,
|
|
93
|
+
);
|
|
94
|
+
}
|
|
95
|
+
if (isSolanaError(error, SOLANA_ERROR__ADDRESSES__INVALID_BYTE_LENGTH)) {
|
|
96
|
+
throw new SolanaError(
|
|
97
|
+
SOLANA_ERROR__OFFCHAIN_MESSAGE__INVALID_APPLICATION_DOMAIN_BYTE_LENGTH,
|
|
98
|
+
error.context,
|
|
99
|
+
);
|
|
100
|
+
}
|
|
101
|
+
throw error;
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* Combines _asserting_ that a string is an offchain message application domain with _coercing_ it
|
|
107
|
+
* to the {@link OffchainMessageApplicationDomain} type. It's most useful with untrusted input.
|
|
108
|
+
*
|
|
109
|
+
* @example
|
|
110
|
+
* ```ts
|
|
111
|
+
* import { offchainMessageApplicationDomain, OffchainMessageV0 } from '@solana/offchain-messages';
|
|
112
|
+
*
|
|
113
|
+
* const offchainMessage: OffchainMessageV0 = {
|
|
114
|
+
* applicationDomain:
|
|
115
|
+
* offchainMessageApplicationDomain('HgHLLXT3BVA5m7x66tEp3YNatXLth1hJwVeCva2T9RNx'),
|
|
116
|
+
* // ...
|
|
117
|
+
* };
|
|
118
|
+
* ```
|
|
119
|
+
*
|
|
120
|
+
* > [!TIP]
|
|
121
|
+
* > When starting from a known-good application domain as a string, it's more efficient to typecast
|
|
122
|
+
* > it rather than to use the {@link offchainMessageApplicationDomain} helper, because the helper
|
|
123
|
+
* > unconditionally performs validation on its input.
|
|
124
|
+
* >
|
|
125
|
+
* > ```ts
|
|
126
|
+
* > import { OffchainMessageApplicationDomain } from '@solana/offchain-messages';
|
|
127
|
+
* >
|
|
128
|
+
* > const applicationDomain =
|
|
129
|
+
* > 'HgHLLXT3BVA5m7x66tEp3YNatXLth1hJwVeCva2T9RNx' as OffchainMessageApplicationDomain;
|
|
130
|
+
* > ```
|
|
131
|
+
*/
|
|
132
|
+
export function offchainMessageApplicationDomain(putativeApplicationDomain: string): OffchainMessageApplicationDomain {
|
|
133
|
+
assertIsOffchainMessageApplicationDomain(putativeApplicationDomain);
|
|
134
|
+
return putativeApplicationDomain;
|
|
135
|
+
}
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
import { Address, getAddressDecoder, getAddressEncoder } from '@solana/addresses';
|
|
2
|
+
import {
|
|
3
|
+
combineCodec,
|
|
4
|
+
FixedSizeCodec,
|
|
5
|
+
FixedSizeDecoder,
|
|
6
|
+
FixedSizeEncoder,
|
|
7
|
+
transformEncoder,
|
|
8
|
+
} from '@solana/codecs-core';
|
|
9
|
+
|
|
10
|
+
import { OffchainMessageApplicationDomain, offchainMessageApplicationDomain } from '../application-domain';
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* Returns an encoder that you can use to encode a base58-encoded offchain message application
|
|
14
|
+
* domain to a byte array.
|
|
15
|
+
*
|
|
16
|
+
* @example
|
|
17
|
+
* ```ts
|
|
18
|
+
* import { getOffchainMessageApplicationDomainEncoder } from '@solana/offchain-messages';
|
|
19
|
+
*
|
|
20
|
+
* const offchainMessageApplicationDomain =
|
|
21
|
+
* 'HgHLLXT3BVA5m7x66tEp3YNatXLth1hJwVeCva2T9RNx' as OffchainMessageApplicationDomain;
|
|
22
|
+
* const offchainMessageApplicationDomainEncoder = getOffchainMessageApplicationDomainEncoder();
|
|
23
|
+
* const offchainMessageApplicationDomainBytes =
|
|
24
|
+
* offchainMessageApplicationDomainEncoder.encode(offchainMessageApplicationDomain);
|
|
25
|
+
* // Uint8Array(32) [
|
|
26
|
+
* // 247, 203, 28, 80, 52, 240, 169, 19,
|
|
27
|
+
* // 21, 103, 107, 119, 91, 235, 13, 48,
|
|
28
|
+
* // 194, 169, 148, 160, 78, 105, 235, 37,
|
|
29
|
+
* // 232, 160, 49, 47, 64, 89, 18, 153,
|
|
30
|
+
* // ]
|
|
31
|
+
* ```
|
|
32
|
+
*/
|
|
33
|
+
export function getOffchainMessageApplicationDomainEncoder(): FixedSizeEncoder<OffchainMessageApplicationDomain, 32> {
|
|
34
|
+
return transformEncoder(
|
|
35
|
+
getAddressEncoder(),
|
|
36
|
+
putativeApplicationDomain => offchainMessageApplicationDomain(putativeApplicationDomain) as string as Address,
|
|
37
|
+
);
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* Returns a decoder that you can use to convert an array of 32 bytes representing an offchain
|
|
42
|
+
* message application domain to the base58-encoded representation of that application domain.
|
|
43
|
+
*
|
|
44
|
+
* @example
|
|
45
|
+
* ```ts
|
|
46
|
+
* import { getOffchainMessageApplicationDomainDecoder } from '@solana/offchain-messages';
|
|
47
|
+
*
|
|
48
|
+
* const offchainMessageApplicationDomainBytes = new Uint8Array([
|
|
49
|
+
* 247, 203, 28, 80, 52, 240, 169, 19,
|
|
50
|
+
* 21, 103, 107, 119, 91, 235, 13, 48,
|
|
51
|
+
* 194, 169, 148, 160, 78, 105, 235, 37,
|
|
52
|
+
* 232, 160, 49, 47, 64, 89, 18, 153,
|
|
53
|
+
* ]);
|
|
54
|
+
* const offchainMessageApplicationDomainDecoder = getOffchainMessageApplicationDomainDecoder();
|
|
55
|
+
* const offchainMessageApplicationDomain =
|
|
56
|
+
* offchainMessageApplicationDomainDecoder.decode(offchainMessageApplicationDomainBytes);
|
|
57
|
+
* // HgHLLXT3BVA5m7x66tEp3YNatXLth1hJwVeCva2T9RNx
|
|
58
|
+
* ```
|
|
59
|
+
*/
|
|
60
|
+
export function getOffchainMessageApplicationDomainDecoder(): FixedSizeDecoder<OffchainMessageApplicationDomain, 32> {
|
|
61
|
+
return getAddressDecoder() as FixedSizeDecoder<string, 32> as FixedSizeDecoder<
|
|
62
|
+
OffchainMessageApplicationDomain,
|
|
63
|
+
32
|
|
64
|
+
>;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* Returns a codec that you can use to encode from or decode to a base-58 encoded offchain message
|
|
69
|
+
* application domain.
|
|
70
|
+
*
|
|
71
|
+
* @see {@link getOffchainMessageApplicationDomainDecoder}
|
|
72
|
+
* @see {@link getOffchainMessageApplicationDomainEncoder}
|
|
73
|
+
*/
|
|
74
|
+
export function getOffchainMessageApplicationDomainCodec(): FixedSizeCodec<
|
|
75
|
+
OffchainMessageApplicationDomain,
|
|
76
|
+
OffchainMessageApplicationDomain,
|
|
77
|
+
32
|
|
78
|
+
> {
|
|
79
|
+
return combineCodec(getOffchainMessageApplicationDomainEncoder(), getOffchainMessageApplicationDomainDecoder());
|
|
80
|
+
}
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import { combineCodec, FixedSizeCodec, FixedSizeDecoder, FixedSizeEncoder } from '@solana/codecs-core';
|
|
2
|
+
import { getEnumDecoder, getEnumEncoder } from '@solana/codecs-data-structures';
|
|
3
|
+
|
|
4
|
+
import { OffchainMessageContentFormat } from '../content';
|
|
5
|
+
|
|
6
|
+
export function getOffchainMessageContentFormatDecoder(): FixedSizeDecoder<OffchainMessageContentFormat, 1> {
|
|
7
|
+
return getEnumDecoder(OffchainMessageContentFormat, {
|
|
8
|
+
useValuesAsDiscriminators: true,
|
|
9
|
+
});
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
export function getOffchainMessageContentFormatEncoder(): FixedSizeEncoder<OffchainMessageContentFormat, 1> {
|
|
13
|
+
return getEnumEncoder(OffchainMessageContentFormat, {
|
|
14
|
+
useValuesAsDiscriminators: true,
|
|
15
|
+
});
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
export function getOffchainMessageContentFormatCodec(): FixedSizeCodec<
|
|
19
|
+
OffchainMessageContentFormat,
|
|
20
|
+
OffchainMessageContentFormat,
|
|
21
|
+
1
|
|
22
|
+
> {
|
|
23
|
+
return combineCodec(getOffchainMessageContentFormatEncoder(), getOffchainMessageContentFormatDecoder());
|
|
24
|
+
}
|
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
import { Address, address } from '@solana/addresses';
|
|
2
|
+
import {
|
|
3
|
+
combineCodec,
|
|
4
|
+
fixDecoderSize,
|
|
5
|
+
ReadonlyUint8Array,
|
|
6
|
+
transformDecoder,
|
|
7
|
+
transformEncoder,
|
|
8
|
+
VariableSizeDecoder,
|
|
9
|
+
VariableSizeEncoder,
|
|
10
|
+
} from '@solana/codecs-core';
|
|
11
|
+
import {
|
|
12
|
+
getArrayDecoder,
|
|
13
|
+
getBytesDecoder,
|
|
14
|
+
getBytesEncoder,
|
|
15
|
+
getStructDecoder,
|
|
16
|
+
getStructEncoder,
|
|
17
|
+
} from '@solana/codecs-data-structures';
|
|
18
|
+
import { getU8Decoder } from '@solana/codecs-numbers';
|
|
19
|
+
import {
|
|
20
|
+
SOLANA_ERROR__OFFCHAIN_MESSAGE__ENVELOPE_SIGNERS_MISMATCH,
|
|
21
|
+
SOLANA_ERROR__OFFCHAIN_MESSAGE__NUM_ENVELOPE_SIGNATURES_CANNOT_BE_ZERO,
|
|
22
|
+
SOLANA_ERROR__OFFCHAIN_MESSAGE__NUM_REQUIRED_SIGNERS_CANNOT_BE_ZERO,
|
|
23
|
+
SOLANA_ERROR__OFFCHAIN_MESSAGE__NUM_SIGNATURES_MISMATCH,
|
|
24
|
+
SolanaError,
|
|
25
|
+
} from '@solana/errors';
|
|
26
|
+
import { SignatureBytes } from '@solana/keys';
|
|
27
|
+
|
|
28
|
+
import { OffchainMessageEnvelope } from '../envelope';
|
|
29
|
+
import { OffchainMessageBytes } from '../message';
|
|
30
|
+
import { decodeRequiredSignatoryAddresses } from './preamble-common';
|
|
31
|
+
import { getSignaturesEncoder } from './signatures';
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* Returns an encoder that you can use to encode an {@link OffchainMessageEnvelope} to a byte array
|
|
35
|
+
* appropriate for sharing with a third party for validation.
|
|
36
|
+
*/
|
|
37
|
+
export function getOffchainMessageEnvelopeEncoder(): VariableSizeEncoder<OffchainMessageEnvelope> {
|
|
38
|
+
return transformEncoder(
|
|
39
|
+
getStructEncoder([
|
|
40
|
+
['signatures', getSignaturesEncoder()],
|
|
41
|
+
['content', getBytesEncoder()],
|
|
42
|
+
]),
|
|
43
|
+
envelope => {
|
|
44
|
+
const signaturesMapAddresses = Object.keys(envelope.signatures).map(address);
|
|
45
|
+
if (signaturesMapAddresses.length === 0) {
|
|
46
|
+
throw new SolanaError(SOLANA_ERROR__OFFCHAIN_MESSAGE__NUM_ENVELOPE_SIGNATURES_CANNOT_BE_ZERO);
|
|
47
|
+
}
|
|
48
|
+
const signatoryAddresses = decodeAndValidateRequiredSignatoryAddresses(envelope.content);
|
|
49
|
+
const missingRequiredSigners = [];
|
|
50
|
+
const unexpectedSigners = [];
|
|
51
|
+
for (const address of signatoryAddresses) {
|
|
52
|
+
if (!signaturesMapAddresses.includes(address)) {
|
|
53
|
+
missingRequiredSigners.push(address);
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
for (const address of signaturesMapAddresses) {
|
|
57
|
+
if (!signatoryAddresses.includes(address)) {
|
|
58
|
+
unexpectedSigners.push(address);
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
if (missingRequiredSigners.length || unexpectedSigners.length) {
|
|
62
|
+
throw new SolanaError(SOLANA_ERROR__OFFCHAIN_MESSAGE__ENVELOPE_SIGNERS_MISMATCH, {
|
|
63
|
+
missingRequiredSigners,
|
|
64
|
+
unexpectedSigners,
|
|
65
|
+
});
|
|
66
|
+
}
|
|
67
|
+
const orderedSignatureMap: OffchainMessageEnvelope['signatures'] = {};
|
|
68
|
+
for (const address of signatoryAddresses) {
|
|
69
|
+
orderedSignatureMap[address] = envelope.signatures[address];
|
|
70
|
+
}
|
|
71
|
+
return {
|
|
72
|
+
...envelope,
|
|
73
|
+
signatures: orderedSignatureMap,
|
|
74
|
+
};
|
|
75
|
+
},
|
|
76
|
+
);
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
/**
|
|
80
|
+
* Returns a decoder that you can use to convert a byte array in the Solana offchain message format
|
|
81
|
+
* to a {@link OffchainMessageEnvelope} object.
|
|
82
|
+
*
|
|
83
|
+
* @example
|
|
84
|
+
* ```ts
|
|
85
|
+
* import { getOffchainMessageEnvelopeDecoder } from '@solana/offchain-messages';
|
|
86
|
+
*
|
|
87
|
+
* const offchainMessageEnvelopeDecoder = getOffchainMessageEnvelopeDecoder();
|
|
88
|
+
* const offchainMessageEnvelope = offchainMessageEnvelopeDecoder.decode(offchainMessageEnvelopeBytes);
|
|
89
|
+
* for (const [address, signature] in Object.entries(offchainMessageEnvelope.signatures)) {
|
|
90
|
+
* console.log(`Signature by ${address}`, signature);
|
|
91
|
+
* }
|
|
92
|
+
* ```
|
|
93
|
+
*/
|
|
94
|
+
export function getOffchainMessageEnvelopeDecoder(): VariableSizeDecoder<OffchainMessageEnvelope> {
|
|
95
|
+
return transformDecoder(
|
|
96
|
+
getStructDecoder([
|
|
97
|
+
['signatures', getArrayDecoder(fixDecoderSize(getBytesDecoder(), 64), { size: getU8Decoder() })],
|
|
98
|
+
['content', getBytesDecoder()],
|
|
99
|
+
]),
|
|
100
|
+
decodePartiallyDecodedOffchainMessageEnvelope,
|
|
101
|
+
);
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* Returns a codec that you can use to encode from or decode to an {@link OffchainMessageEnvelope}
|
|
106
|
+
*
|
|
107
|
+
* @see {@link getOffchainMessageEnvelopeDecoder}
|
|
108
|
+
* @see {@link getOffchainMessageEnvelopeEncoder}
|
|
109
|
+
*/
|
|
110
|
+
export function getOffchainMessageEnvelopeCodec() {
|
|
111
|
+
return combineCodec(getOffchainMessageEnvelopeEncoder(), getOffchainMessageEnvelopeDecoder());
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
type PartiallyDecodedOffchainMessageEnvelope = {
|
|
115
|
+
content: ReadonlyUint8Array;
|
|
116
|
+
signatures: ReadonlyUint8Array[];
|
|
117
|
+
};
|
|
118
|
+
|
|
119
|
+
function decodePartiallyDecodedOffchainMessageEnvelope(
|
|
120
|
+
offchainMessageEnvelope: PartiallyDecodedOffchainMessageEnvelope,
|
|
121
|
+
): OffchainMessageEnvelope {
|
|
122
|
+
const { content, signatures } = offchainMessageEnvelope;
|
|
123
|
+
|
|
124
|
+
if (signatures.length === 0) {
|
|
125
|
+
throw new SolanaError(SOLANA_ERROR__OFFCHAIN_MESSAGE__NUM_ENVELOPE_SIGNATURES_CANNOT_BE_ZERO);
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
const signatoryAddresses = decodeAndValidateRequiredSignatoryAddresses(content);
|
|
129
|
+
|
|
130
|
+
// Signer addresses and signatures must be the same length
|
|
131
|
+
// We encode an all-zero signature when the signature is missing
|
|
132
|
+
if (signatoryAddresses.length !== signatures.length) {
|
|
133
|
+
throw new SolanaError(SOLANA_ERROR__OFFCHAIN_MESSAGE__NUM_SIGNATURES_MISMATCH, {
|
|
134
|
+
numRequiredSignatures: signatoryAddresses.length,
|
|
135
|
+
signatoryAddresses,
|
|
136
|
+
signaturesLength: signatures.length,
|
|
137
|
+
});
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
// Combine the signer addresses + signatures into the signatures map
|
|
141
|
+
const signaturesMap: OffchainMessageEnvelope['signatures'] = {};
|
|
142
|
+
signatoryAddresses.forEach((address, index) => {
|
|
143
|
+
const signatureForAddress = signatures[index];
|
|
144
|
+
if (signatureForAddress.every(b => b === 0)) {
|
|
145
|
+
signaturesMap[address] = null;
|
|
146
|
+
} else {
|
|
147
|
+
signaturesMap[address] = signatureForAddress as SignatureBytes;
|
|
148
|
+
}
|
|
149
|
+
});
|
|
150
|
+
|
|
151
|
+
return Object.freeze({
|
|
152
|
+
content: content as OffchainMessageBytes,
|
|
153
|
+
signatures: Object.freeze(signaturesMap),
|
|
154
|
+
});
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
function decodeAndValidateRequiredSignatoryAddresses(bytes: ReadonlyUint8Array): readonly Address[] {
|
|
158
|
+
const signatoryAddresses = decodeRequiredSignatoryAddresses(bytes);
|
|
159
|
+
|
|
160
|
+
if (signatoryAddresses.length === 0) {
|
|
161
|
+
throw new SolanaError(SOLANA_ERROR__OFFCHAIN_MESSAGE__NUM_REQUIRED_SIGNERS_CANNOT_BE_ZERO);
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
return signatoryAddresses;
|
|
165
|
+
}
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
import {
|
|
2
|
+
combineCodec,
|
|
3
|
+
transformDecoder,
|
|
4
|
+
transformEncoder,
|
|
5
|
+
VariableSizeCodec,
|
|
6
|
+
VariableSizeDecoder,
|
|
7
|
+
VariableSizeEncoder,
|
|
8
|
+
} from '@solana/codecs-core';
|
|
9
|
+
import { getTupleDecoder, getTupleEncoder } from '@solana/codecs-data-structures';
|
|
10
|
+
import { getUtf8Decoder, getUtf8Encoder } from '@solana/codecs-strings';
|
|
11
|
+
import {
|
|
12
|
+
SOLANA_ERROR__INVARIANT_VIOLATION__SWITCH_MUST_BE_EXHAUSTIVE,
|
|
13
|
+
SOLANA_ERROR__OFFCHAIN_MESSAGE__MESSAGE_LENGTH_MISMATCH,
|
|
14
|
+
SolanaError,
|
|
15
|
+
} from '@solana/errors';
|
|
16
|
+
|
|
17
|
+
import { OffchainMessageContentFormat } from '../content';
|
|
18
|
+
import {
|
|
19
|
+
assertIsOffchainMessageRestrictedAsciiOf1232BytesMax,
|
|
20
|
+
assertIsOffchainMessageUtf8Of1232BytesMax,
|
|
21
|
+
assertIsOffchainMessageUtf8Of65535BytesMax,
|
|
22
|
+
OffchainMessageV0,
|
|
23
|
+
} from '../message-v0';
|
|
24
|
+
import { getOffchainMessageV0PreambleDecoder, getOffchainMessageV0PreambleEncoder } from './preamble-v0';
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* Returns a decoder that you can use to convert a byte array (eg. one that conforms to the
|
|
28
|
+
* {@link OffchainMessageBytes} type) to an {@link OffchainMessageV0} object.
|
|
29
|
+
*
|
|
30
|
+
* @example
|
|
31
|
+
* ```ts
|
|
32
|
+
* import { getOffchainMessageV0Decoder } from '@solana/offchain-messages';
|
|
33
|
+
*
|
|
34
|
+
* const offchainMessageDecoder = getOffchainMessageV0Decoder();
|
|
35
|
+
* const offchainMessage = offchainMessageDecoder.decode(
|
|
36
|
+
* offchainMessageEnvelope.content,
|
|
37
|
+
* );
|
|
38
|
+
* console.log(`Decoded a v0 offchain message`);
|
|
39
|
+
* ```
|
|
40
|
+
*
|
|
41
|
+
* Throws in the event that the message bytes represent a message of a version other than 0.
|
|
42
|
+
*/
|
|
43
|
+
export function getOffchainMessageV0Decoder(): VariableSizeDecoder<OffchainMessageV0> {
|
|
44
|
+
return transformDecoder(
|
|
45
|
+
getTupleDecoder([getOffchainMessageV0PreambleDecoder(), getUtf8Decoder()]),
|
|
46
|
+
([{ messageLength, messageFormat, requiredSignatories, ...preambleRest }, text]) => {
|
|
47
|
+
const actualLength = getUtf8Encoder().getSizeFromValue(text);
|
|
48
|
+
if (messageLength !== actualLength) {
|
|
49
|
+
throw new SolanaError(SOLANA_ERROR__OFFCHAIN_MESSAGE__MESSAGE_LENGTH_MISMATCH, {
|
|
50
|
+
actualLength: actualLength,
|
|
51
|
+
specifiedLength: messageLength,
|
|
52
|
+
});
|
|
53
|
+
}
|
|
54
|
+
const offchainMessage: Omit<OffchainMessageV0, 'content'> &
|
|
55
|
+
Readonly<{
|
|
56
|
+
content: {
|
|
57
|
+
format: OffchainMessageContentFormat;
|
|
58
|
+
text: string;
|
|
59
|
+
};
|
|
60
|
+
}> = Object.freeze({
|
|
61
|
+
...preambleRest,
|
|
62
|
+
content: Object.freeze({
|
|
63
|
+
format: messageFormat,
|
|
64
|
+
text,
|
|
65
|
+
}),
|
|
66
|
+
requiredSignatories: Object.freeze(requiredSignatories),
|
|
67
|
+
});
|
|
68
|
+
switch (messageFormat) {
|
|
69
|
+
case OffchainMessageContentFormat.RESTRICTED_ASCII_1232_BYTES_MAX: {
|
|
70
|
+
assertIsOffchainMessageRestrictedAsciiOf1232BytesMax(offchainMessage);
|
|
71
|
+
return offchainMessage;
|
|
72
|
+
}
|
|
73
|
+
case OffchainMessageContentFormat.UTF8_1232_BYTES_MAX: {
|
|
74
|
+
assertIsOffchainMessageUtf8Of1232BytesMax(offchainMessage);
|
|
75
|
+
return offchainMessage;
|
|
76
|
+
}
|
|
77
|
+
case OffchainMessageContentFormat.UTF8_65535_BYTES_MAX: {
|
|
78
|
+
assertIsOffchainMessageUtf8Of65535BytesMax(offchainMessage);
|
|
79
|
+
return offchainMessage;
|
|
80
|
+
}
|
|
81
|
+
default: {
|
|
82
|
+
throw new SolanaError(SOLANA_ERROR__INVARIANT_VIOLATION__SWITCH_MUST_BE_EXHAUSTIVE, {
|
|
83
|
+
unexpectedValue: messageFormat satisfies never,
|
|
84
|
+
});
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
},
|
|
88
|
+
);
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
/**
|
|
92
|
+
* Returns an encoder that you can use to encode an {@link OffchainMessageV0} to a byte array
|
|
93
|
+
* appropriate for inclusion in an {@link OffchainMessageEnvelope}.
|
|
94
|
+
*/
|
|
95
|
+
export function getOffchainMessageV0Encoder(): VariableSizeEncoder<OffchainMessageV0> {
|
|
96
|
+
return transformEncoder(
|
|
97
|
+
getTupleEncoder([getOffchainMessageV0PreambleEncoder(), getUtf8Encoder()]),
|
|
98
|
+
offchainMessage => {
|
|
99
|
+
const { content, ...preamble } = offchainMessage;
|
|
100
|
+
switch (offchainMessage.content.format) {
|
|
101
|
+
case OffchainMessageContentFormat.RESTRICTED_ASCII_1232_BYTES_MAX: {
|
|
102
|
+
assertIsOffchainMessageRestrictedAsciiOf1232BytesMax(offchainMessage);
|
|
103
|
+
break;
|
|
104
|
+
}
|
|
105
|
+
case OffchainMessageContentFormat.UTF8_1232_BYTES_MAX: {
|
|
106
|
+
assertIsOffchainMessageUtf8Of1232BytesMax(offchainMessage);
|
|
107
|
+
break;
|
|
108
|
+
}
|
|
109
|
+
case OffchainMessageContentFormat.UTF8_65535_BYTES_MAX: {
|
|
110
|
+
assertIsOffchainMessageUtf8Of65535BytesMax(offchainMessage);
|
|
111
|
+
break;
|
|
112
|
+
}
|
|
113
|
+
default: {
|
|
114
|
+
throw new SolanaError(SOLANA_ERROR__INVARIANT_VIOLATION__SWITCH_MUST_BE_EXHAUSTIVE, {
|
|
115
|
+
unexpectedValue: offchainMessage.content satisfies never,
|
|
116
|
+
});
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
const messageLength = getUtf8Encoder().getSizeFromValue(content.text);
|
|
120
|
+
const compiledPreamble = {
|
|
121
|
+
...preamble,
|
|
122
|
+
messageFormat: content.format,
|
|
123
|
+
messageLength,
|
|
124
|
+
};
|
|
125
|
+
return [compiledPreamble, content.text] as const;
|
|
126
|
+
},
|
|
127
|
+
);
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/**
|
|
131
|
+
* Returns a codec that you can use to encode from or decode to an {@link OffchainMessageV0}
|
|
132
|
+
*
|
|
133
|
+
* @see {@link getOffchainMessageV0Decoder}
|
|
134
|
+
* @see {@link getOffchainMessageV0Encoder}
|
|
135
|
+
*/
|
|
136
|
+
export function getOffchainMessageV0Codec(): VariableSizeCodec<OffchainMessageV0> {
|
|
137
|
+
return combineCodec(getOffchainMessageV0Encoder(), getOffchainMessageV0Decoder());
|
|
138
|
+
}
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
import {
|
|
2
|
+
combineCodec,
|
|
3
|
+
transformDecoder,
|
|
4
|
+
transformEncoder,
|
|
5
|
+
VariableSizeCodec,
|
|
6
|
+
VariableSizeDecoder,
|
|
7
|
+
VariableSizeEncoder,
|
|
8
|
+
} from '@solana/codecs-core';
|
|
9
|
+
import { getTupleDecoder, getTupleEncoder } from '@solana/codecs-data-structures';
|
|
10
|
+
import { getUtf8Decoder, getUtf8Encoder } from '@solana/codecs-strings';
|
|
11
|
+
import { SOLANA_ERROR__OFFCHAIN_MESSAGE__MESSAGE_MUST_BE_NON_EMPTY, SolanaError } from '@solana/errors';
|
|
12
|
+
|
|
13
|
+
import { OffchainMessageV1 } from '../message-v1';
|
|
14
|
+
import { getOffchainMessageV1PreambleDecoder, getOffchainMessageV1PreambleEncoder } from './preamble-v1';
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* Returns a decoder that you can use to convert a byte array (eg. one that conforms to the
|
|
18
|
+
* {@link OffchainMessageBytes} type) to an {@link OffchainMessageV1} object.
|
|
19
|
+
*
|
|
20
|
+
* @example
|
|
21
|
+
* ```ts
|
|
22
|
+
* import { getOffchainMessageV1Decoder } from '@solana/offchain-messages';
|
|
23
|
+
*
|
|
24
|
+
* const offchainMessageDecoder = getOffchainMessageV1Decoder();
|
|
25
|
+
* const offchainMessage = offchainMessageDecoder.decode(
|
|
26
|
+
* offchainMessageEnvelope.content,
|
|
27
|
+
* );
|
|
28
|
+
* console.log(`Decoded a v1 offchain message`);
|
|
29
|
+
* ```
|
|
30
|
+
*
|
|
31
|
+
* Throws in the event that the message bytes represent a message of a version other than 1.
|
|
32
|
+
*/
|
|
33
|
+
export function getOffchainMessageV1Decoder(): VariableSizeDecoder<OffchainMessageV1> {
|
|
34
|
+
return transformDecoder(
|
|
35
|
+
getTupleDecoder([getOffchainMessageV1PreambleDecoder(), getUtf8Decoder()]),
|
|
36
|
+
([{ requiredSignatories, ...preambleRest }, text]) => {
|
|
37
|
+
if (text.length === 0) {
|
|
38
|
+
throw new SolanaError(SOLANA_ERROR__OFFCHAIN_MESSAGE__MESSAGE_MUST_BE_NON_EMPTY);
|
|
39
|
+
}
|
|
40
|
+
return Object.freeze({
|
|
41
|
+
...preambleRest,
|
|
42
|
+
content: text,
|
|
43
|
+
requiredSignatories: Object.freeze(requiredSignatories),
|
|
44
|
+
});
|
|
45
|
+
},
|
|
46
|
+
);
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* Returns an encoder that you can use to encode an {@link OffchainMessageV1} to a byte array
|
|
51
|
+
* appropriate for inclusion in an {@link OffchainMessageEnvelope}.
|
|
52
|
+
*/
|
|
53
|
+
export function getOffchainMessageV1Encoder(): VariableSizeEncoder<OffchainMessageV1> {
|
|
54
|
+
return transformEncoder(
|
|
55
|
+
getTupleEncoder([getOffchainMessageV1PreambleEncoder(), getUtf8Encoder()]),
|
|
56
|
+
offchainMessage => {
|
|
57
|
+
const { content, ...compiledPreamble } = offchainMessage;
|
|
58
|
+
if (content.length === 0) {
|
|
59
|
+
throw new SolanaError(SOLANA_ERROR__OFFCHAIN_MESSAGE__MESSAGE_MUST_BE_NON_EMPTY);
|
|
60
|
+
}
|
|
61
|
+
return [compiledPreamble, content] as const;
|
|
62
|
+
},
|
|
63
|
+
);
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* Returns a codec that you can use to encode from or decode to an {@link OffchainMessageV1}
|
|
68
|
+
*
|
|
69
|
+
* @see {@link getOffchainMessageV1Decoder}
|
|
70
|
+
* @see {@link getOffchainMessageV1Encoder}
|
|
71
|
+
*/
|
|
72
|
+
export function getOffchainMessageV1Codec(): VariableSizeCodec<OffchainMessageV1> {
|
|
73
|
+
return combineCodec(getOffchainMessageV1Encoder(), getOffchainMessageV1Decoder());
|
|
74
|
+
}
|