@aboutcircles/sdk-utils 0.1.25 → 0.1.26

package/dist/abi.d.ts

@@ -52,4 +52,11 @@ export declare function decodeErrorResult(config: {
  * ```
  */
 export declare function encodeAbiParameters(types: string[], values: unknown[]): Hex;
+/**
+ * Decode ABI-encoded parameters given their type strings.
+ * @param types - Array of Solidity type strings (e.g. ['address', 'uint256'])
+ * @param data  - Hex-encoded data (with or without 0x prefix), without selector
+ * @returns Array of decoded values
+ */
+export declare function decodeAbiParameters(types: string[], data: string): unknown[];
 //# sourceMappingURL=abi.d.ts.map

package/dist/abi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"abi.d.ts","sourceRoot":"","sources":["../src/abi.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,GAAG,EAAe,MAAM,SAAS,CAAC;AAChD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,yBAAyB,CAAC;AAwCnD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CASvD;AAoXD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE;IACzC,GAAG,EAAE,GAAG,CAAC;IACT,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;CAC3B,GAAG,GAAG,CA+DN;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE;IAC3C,GAAG,EAAE,GAAG,CAAC;IACT,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CA0CV;AAmBD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,GAAG,EAAE,GAAG,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;CACd,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,GAAG,EAAE,CAAA;CAAE,GAAG,IAAI,CA+C7C;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,GAAG,CA+C3E"}
+{"version":3,"file":"abi.d.ts","sourceRoot":"","sources":["../src/abi.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,GAAG,EAAe,MAAM,SAAS,CAAC;AAChD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,yBAAyB,CAAC;AAwCnD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CASvD;AAoXD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE;IACzC,GAAG,EAAE,GAAG,CAAC;IACT,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;CAC3B,GAAG,GAAG,CA+DN;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE;IAC3C,GAAG,EAAE,GAAG,CAAC;IACT,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CA0CV;AAmBD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,GAAG,EAAE,GAAG,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;CACd,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,GAAG,EAAE,CAAA;CAAE,GAAG,IAAI,CA+C7C;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,GAAG,CA+C3E;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CAY5E"}

package/dist/abi.js

@@ -1,5 +1,5 @@
 import { keccak_256 } from '@noble/hashes/sha3.js';
-import { bytesToHex } from './bytes';
+import { bytesToHex } from './bytes.js';
 // ============================================================================
 // CONSTANTS & UTILITIES
 // ============================================================================
@@ -511,3 +511,20 @@ export function encodeAbiParameters(types, values) {
     }
     return ('0x' + result + dynamicData.join(''));
 }
+/**
+ * Decode ABI-encoded parameters given their type strings.
+ * @param types - Array of Solidity type strings (e.g. ['address', 'uint256'])
+ * @param data  - Hex-encoded data (with or without 0x prefix), without selector
+ * @returns Array of decoded values
+ */
+export function decodeAbiParameters(types, data) {
+    const cleanData = data.startsWith('0x') ? data.slice(2) : data;
+    const results = [];
+    let offset = 0;
+    for (const type of types) {
+        const result = decodeParam(type, cleanData, offset);
+        results.push(result.value);
+        offset += result.consumed;
+    }
+    return results;
+}

package/dist/contractErrors.d.ts

@@ -4,7 +4,7 @@
  */
 import type { Abi } from 'abitype';
 import type { DecodedContractError } from '@aboutcircles/sdk-types';
-import { CirclesError } from './errors';
+import { CirclesError } from './errors.js';
 /**
  * Parse contract error from a transaction error
  *

package/dist/contractErrors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contractErrors.d.ts","sourceRoot":"","sources":["../src/contractErrors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAEpE,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AA6HxC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,GAAG,EACV,GAAG,EAAE,GAAG,GACP,oBAAoB,GAAG,IAAI,CA4B7B;AAED;;;GAGG;AACH,qBAAa,aAAc,SAAQ,YAAY,CAAC,MAAM,CAAC;IACrD,SAAgB,YAAY,CAAC,EAAE,oBAAoB,CAAC;gBAGlD,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QACvB,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC9B,YAAY,CAAC,EAAE,oBAAoB,CAAC;KACrC;IAMH;;OAEG;IACH,MAAM,CAAC,oBAAoB,CACzB,KAAK,EAAE,GAAG,EACV,GAAG,EAAE,GAAG,EACR,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC5B,aAAa;IA8BhB;;OAEG;IACH,QAAQ,IAAI,MAAM;CAcnB"}
+{"version":3,"file":"contractErrors.d.ts","sourceRoot":"","sources":["../src/contractErrors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAEpE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA6H3C;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,GAAG,EACV,GAAG,EAAE,GAAG,GACP,oBAAoB,GAAG,IAAI,CA4B7B;AAED;;;GAGG;AACH,qBAAa,aAAc,SAAQ,YAAY,CAAC,MAAM,CAAC;IACrD,SAAgB,YAAY,CAAC,EAAE,oBAAoB,CAAC;gBAGlD,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QACvB,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC9B,YAAY,CAAC,EAAE,oBAAoB,CAAC;KACrC;IAMH;;OAEG;IACH,MAAM,CAAC,oBAAoB,CACzB,KAAK,EAAE,GAAG,EACV,GAAG,EAAE,GAAG,EACR,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC5B,aAAa;IA8BhB;;OAEG;IACH,QAAQ,IAAI,MAAM;CAcnB"}

package/dist/contractErrors.js

@@ -2,8 +2,8 @@
  * Contract Error Parsing
  * Utilities for parsing and decoding contract errors from transaction failures
  */
-import { decodeErrorResult } from './abi';
-import { CirclesError } from './errors';
+import { decodeErrorResult } from './abi.js';
+import { CirclesError } from './errors.js';
 /**
  * Contract error codes mapping
  * Maps error codes to human-readable messages

package/dist/crypto.js

@@ -1,6 +1,6 @@
 import { secp256k1 } from '@noble/curves/secp256k1';
 import { keccak_256 } from '@noble/hashes/sha3';
-import { checksumAddress } from './abi';
+import { checksumAddress } from './abi.js';
 /**
  * Generate a random private key (32 bytes / 64 hex chars)
  * @returns Private key as hex string with 0x prefix

package/dist/index.d.ts

@@ -1,12 +1,14 @@
-export { CirclesConverter } from './circlesConverter';
-export { bytesToHex, hexToBytes } from './bytes';
-export { encodeFunctionData, decodeFunctionResult, decodeErrorResult, checksumAddress, encodeAbiParameters } from './abi';
-export { cidV0ToHex, cidV0ToUint8Array } from './cid';
-export { uint256ToAddress } from './address';
-export { ZERO_ADDRESS, INVITATION_FEE, MAX_FLOW, SAFE_PROXY_FACTORY, ACCOUNT_INITIALIZER_HASH, ACCOUNT_CREATION_CODE_HASH, GNOSIS_GROUP_ADDRESS, FARM_DESTINATION } from './constants';
-export { circlesConfig } from './config';
-export { parseContractError, ContractError } from './contractErrors';
-export { generatePrivateKey, privateKeyToAddress, keccak256 } from './crypto';
-export { CirclesError, ValidationError, EncodingError, wrapError, isCirclesError, getErrorMessage, } from './errors';
-export type { BaseErrorSource, UtilsErrorSource } from './errors';
+export { CirclesConverter } from './circlesConverter.js';
+export { bytesToHex, hexToBytes } from './bytes.js';
+export { encodeFunctionData, decodeFunctionResult, decodeErrorResult, checksumAddress, encodeAbiParameters, decodeAbiParameters } from './abi.js';
+export { cidV0ToHex, cidV0ToUint8Array } from './cid.js';
+export { uint256ToAddress } from './address.js';
+export { ZERO_ADDRESS, INVITATION_FEE, MAX_FLOW, SAFE_PROXY_FACTORY, ACCOUNT_INITIALIZER_HASH, ACCOUNT_CREATION_CODE_HASH, GNOSIS_GROUP_ADDRESS, FARM_DESTINATION } from './constants.js';
+export { circlesConfig } from './config.js';
+export { parseContractError, ContractError } from './contractErrors.js';
+export { generatePrivateKey, privateKeyToAddress, keccak256 } from './crypto.js';
+export { encodeCrcV2TransferData, decodeCrcV2TransferData } from './transferData.js';
+export type { TransferDataType, DecodedTransferData, DecodedAbiPayload, DecodedMetadataPayload } from './transferData.js';
+export { CirclesError, ValidationError, EncodingError, wrapError, isCirclesError, getErrorMessage, } from './errors.js';
+export type { BaseErrorSource, UtilsErrorSource } from './errors.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,OAAO,CAAC;AAC1H,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,OAAO,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,QAAQ,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,0BAA0B,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACvL,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAG9E,OAAO,EACL,YAAY,EACZ,eAAe,EACf,aAAa,EACb,SAAS,EACT,cAAc,EACd,eAAe,GAChB,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,eAAe,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAClJ,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,QAAQ,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,0BAA0B,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAC1L,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACxE,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACjF,OAAO,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AACrF,YAAY,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAG1H,OAAO,EACL,YAAY,EACZ,eAAe,EACf,aAAa,EACb,SAAS,EACT,cAAc,EACd,eAAe,GAChB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,11 +1,12 @@
-export { CirclesConverter } from './circlesConverter';
-export { bytesToHex, hexToBytes } from './bytes';
-export { encodeFunctionData, decodeFunctionResult, decodeErrorResult, checksumAddress, encodeAbiParameters } from './abi';
-export { cidV0ToHex, cidV0ToUint8Array } from './cid';
-export { uint256ToAddress } from './address';
-export { ZERO_ADDRESS, INVITATION_FEE, MAX_FLOW, SAFE_PROXY_FACTORY, ACCOUNT_INITIALIZER_HASH, ACCOUNT_CREATION_CODE_HASH, GNOSIS_GROUP_ADDRESS, FARM_DESTINATION } from './constants';
-export { circlesConfig } from './config';
-export { parseContractError, ContractError } from './contractErrors';
-export { generatePrivateKey, privateKeyToAddress, keccak256 } from './crypto';
+export { CirclesConverter } from './circlesConverter.js';
+export { bytesToHex, hexToBytes } from './bytes.js';
+export { encodeFunctionData, decodeFunctionResult, decodeErrorResult, checksumAddress, encodeAbiParameters, decodeAbiParameters } from './abi.js';
+export { cidV0ToHex, cidV0ToUint8Array } from './cid.js';
+export { uint256ToAddress } from './address.js';
+export { ZERO_ADDRESS, INVITATION_FEE, MAX_FLOW, SAFE_PROXY_FACTORY, ACCOUNT_INITIALIZER_HASH, ACCOUNT_CREATION_CODE_HASH, GNOSIS_GROUP_ADDRESS, FARM_DESTINATION } from './constants.js';
+export { circlesConfig } from './config.js';
+export { parseContractError, ContractError } from './contractErrors.js';
+export { generatePrivateKey, privateKeyToAddress, keccak256 } from './crypto.js';
+export { encodeCrcV2TransferData, decodeCrcV2TransferData } from './transferData.js';
 // Error handling
-export { CirclesError, ValidationError, EncodingError, wrapError, isCirclesError, getErrorMessage, } from './errors';
+export { CirclesError, ValidationError, EncodingError, wrapError, isCirclesError, getErrorMessage, } from './errors.js';

package/dist/tests/abi.test.js

@@ -1,5 +1,5 @@
 import { describe, test, expect } from 'bun:test';
-import { encodeFunctionData, decodeFunctionResult } from '../abi';
+import { encodeFunctionData, decodeFunctionResult } from '../abi.js';
 import { encodeFunctionData as viemEncodeFunctionData, decodeFunctionResult as viemDecodeFunctionResult } from 'viem/utils';
 describe('encodeFunctionData', () => {
     test('encodes function with no inputs', () => {

package/dist/tests/checksumAddress.test.js

@@ -1,5 +1,5 @@
 import { describe, test, expect } from 'bun:test';
-import { checksumAddress } from '../abi';
+import { checksumAddress } from '../abi.js';
 describe('checksumAddress', () => {
     test('checksums lowercase address correctly', () => {
         const lowercase = '0x5aaeb6053f3e94c9b9a09f33669435e7ef1beaed';

package/dist/tests/transferData.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=transferData.test.d.ts.map

package/dist/tests/transferData.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transferData.test.d.ts","sourceRoot":"","sources":["../../src/tests/transferData.test.ts"],"names":[],"mappings":""}

package/dist/tests/transferData.test.js

@@ -0,0 +1,243 @@
+import { describe, test, expect } from 'bun:test';
+import { encodeCrcV2TransferData, decodeCrcV2TransferData } from '../transferData.js';
+// ============================================================================
+// Type 0x0001 — UTF-8 Text
+// ============================================================================
+describe('Type 0x0001 — UTF-8 text', () => {
+    test('encodes "Hi"', () => {
+        const result = encodeCrcV2TransferData(['Hi'], 0x0001);
+        expect(result).toBe('0x010001000248' + '69');
+    });
+    test('encodes "Happy Birthday 🎂"', () => {
+        const result = encodeCrcV2TransferData(['Happy Birthday 🎂'], 0x0001);
+        expect(result).toBe('0x0100010013486170707920426972746864617920F09F8E82'.toLowerCase());
+    });
+    test('round-trips simple text', () => {
+        const text = 'Thanks for the lunch! 🍣';
+        const encoded = encodeCrcV2TransferData([text], 0x0001);
+        const decoded = decodeCrcV2TransferData(encoded);
+        expect(decoded.type).toBe(0x0001);
+        expect(decoded.payload).toBe(text);
+        expect(decoded.length).toBe(new TextEncoder().encode(text).length);
+    });
+    test('round-trips empty string', () => {
+        const encoded = encodeCrcV2TransferData([''], 0x0001);
+        const decoded = decodeCrcV2TransferData(encoded);
+        expect(decoded.payload).toBe('');
+        expect(decoded.length).toBe(0);
+    });
+    test('round-trips multi-line text', () => {
+        const text = 'Line 1\nLine 2\nLine 3';
+        const encoded = encodeCrcV2TransferData([text], 0x0001);
+        const decoded = decodeCrcV2TransferData(encoded);
+        expect(decoded.payload).toBe(text);
+    });
+});
+// ============================================================================
+// Type 0x0002 — Raw 32-byte hex (XMTP message ID)
+// ============================================================================
+describe('Type 0x0002 — Raw 32-byte hex', () => {
+    const xmtpId = '0x69236a76eff7f05583e6fa5810cf6b24100f0e9132e0787594a790b2fea254ec';
+    test('encodes XMTP message ID', () => {
+        const result = encodeCrcV2TransferData([xmtpId], 0x0002);
+        expect(result).toBe('0x010002002069236a76eff7f05583e6fa5810cf6b24100f0e9132e0787594a790b2fea254ec');
+    });
+    test('round-trips XMTP message ID', () => {
+        const encoded = encodeCrcV2TransferData([xmtpId], 0x0002);
+        const decoded = decodeCrcV2TransferData(encoded);
+        expect(decoded.type).toBe(0x0002);
+        expect(decoded.length).toBe(32);
+        expect(decoded.payload.toLowerCase()).toBe(xmtpId.toLowerCase());
+    });
+    test('accepts hex without 0x prefix', () => {
+        const raw = '69236a76eff7f05583e6fa5810cf6b24100f0e9132e0787594a790b2fea254ec';
+        const encoded = encodeCrcV2TransferData([raw], 0x0002);
+        const decoded = decodeCrcV2TransferData(encoded);
+        expect(decoded.payload.slice(2)).toBe(raw);
+    });
+    test('throws for wrong byte length', () => {
+        expect(() => encodeCrcV2TransferData(['0xdeadbeef'], 0x0002)).toThrow();
+    });
+});
+// ============================================================================
+// Type 0x0003 — IPFS CID
+// ============================================================================
+describe('Type 0x0003 — IPFS CID', () => {
+    const cidV0 = 'QmZ4tDuvesekSs4qM5ZBKpXiZGun7S2CYtEZRB3DYXkjGx';
+    test('encodes CIDv0', () => {
+        const result = encodeCrcV2TransferData([cidV0], 0x0003);
+        expect(result).toMatch(/^0x01000300/);
+    });
+    test('round-trips CIDv0 back to CIDv0 string (dag-pb + sha256)', () => {
+        const encoded = encodeCrcV2TransferData([cidV0], 0x0003);
+        const decoded = decodeCrcV2TransferData(encoded);
+        expect(decoded.type).toBe(0x0003);
+        expect(decoded.payload).toBe(cidV0);
+    });
+    test('round-trips CIDv1 string', () => {
+        // CIDv1 base32 (dag-pb + sha256, same content as CIDv0 above)
+        const cidV1 = 'bafybeie7m2fsbt6sjtn7tymyb6sim7iiyz6szl4ethtn7anzx4frzfzipu';
+        const encoded = encodeCrcV2TransferData([cidV1], 0x0003);
+        const decoded = decodeCrcV2TransferData(encoded);
+        expect(decoded.type).toBe(0x0003);
+        // dag-pb + sha256 CIDv1 should decode back to CIDv0
+        expect(decoded.payload).toBe(cidV0);
+    });
+    test('encodes and decodes produce consistent length', () => {
+        const encoded = encodeCrcV2TransferData([cidV0], 0x0003);
+        const decoded = decodeCrcV2TransferData(encoded);
+        // CIDv1 hex for dag-pb sha256 = 36 bytes (1 version + 1 codec + 2 multihash header + 32 digest)
+        expect(decoded.length).toBe(36);
+    });
+});
+// ============================================================================
+// Type 0x1001 — UTF-8 text with metadata
+// ============================================================================
+describe('Type 0x1001 — UTF-8 text with metadata', () => {
+    test('encodes message + metadata', () => {
+        const encoded = encodeCrcV2TransferData(['Happy Birthday', 'https://app.gnosis.io'], 0x1001);
+        const hex = encoded.slice(2);
+        // Header starts with version=01, type=1001
+        expect(hex.slice(0, 2)).toBe('01');
+        expect(hex.slice(2, 6)).toBe('1001');
+        // Contains separator 480a868a
+        expect(hex).toContain('480a868a');
+    });
+    test('round-trips message + metadata', () => {
+        const message = 'Happy Birthday';
+        const metadata = 'https://app.gnosis.io';
+        const encoded = encodeCrcV2TransferData([message, metadata], 0x1001);
+        const decoded = decodeCrcV2TransferData(encoded);
+        expect(decoded.type).toBe(0x1001);
+        const p = decoded.payload;
+        expect(p.message).toBe(message);
+        expect(p.metadata).toBe(metadata);
+    });
+    test('length equals message + separator + metadata byte count', () => {
+        const message = 'Hello';
+        const metadata = 'order:123';
+        const encoded = encodeCrcV2TransferData([message, metadata], 0x1001);
+        const decoded = decodeCrcV2TransferData(encoded);
+        const messageBytes = new TextEncoder().encode(message).length;
+        const metadataBytes = new TextEncoder().encode(metadata).length;
+        // 4 bytes for the separator
+        expect(decoded.length).toBe(messageBytes + 4 + metadataBytes);
+    });
+    test('round-trips with emoji in message and metadata', () => {
+        const message = 'Thanks! 🎉';
+        const metadata = 'app:circles:tag=gift 🎁';
+        const encoded = encodeCrcV2TransferData([message, metadata], 0x1001);
+        const decoded = decodeCrcV2TransferData(encoded);
+        const p = decoded.payload;
+        expect(p.message).toBe(message);
+        expect(p.metadata).toBe(metadata);
+    });
+    test('throws on decode if separator is missing', () => {
+        // Manually craft a 0x1001 payload without the separator
+        const fakePayloadHex = '48656c6c6f'; // "Hello" without separator
+        const length = fakePayloadHex.length / 2;
+        const hex = '0x' + '01' + '1001' + length.toString(16).padStart(4, '0') + fakePayloadHex;
+        expect(() => decodeCrcV2TransferData(hex)).toThrow(/separator/i);
+    });
+});
+// ============================================================================
+// Type 0x0004 — ABI-encoded calldata
+// ============================================================================
+describe('Type 0x0004 — ABI-encoded calldata', () => {
+    const signature = 'transfer(address,uint256)';
+    const address = '0x742d35Cc6634C0532925a3b844Bc454e4438f44e';
+    const amount = 1000000000000000000n;
+    const expectedSelector = 'a9059cbb';
+    const expectedEncodedAddress = '000000000000000000000000742d35cc6634c0532925a3b844bc454e4438f44e';
+    const expectedEncodedAmount = '0000000000000000000000000000000000000000000000000de0b6b3a7640000';
+    test('encodes from function signature + params', () => {
+        const result = encodeCrcV2TransferData([signature, address, amount], 0x0004);
+        const hex = result.slice(2);
+        // Header: 01 0004 0044
+        expect(hex.slice(0, 10)).toBe('0100040044');
+        // Selector
+        expect(hex.slice(10, 18)).toBe(expectedSelector);
+        // Encoded address
+        expect(hex.slice(18, 18 + 64)).toBe(expectedEncodedAddress);
+        // Encoded amount
+        expect(hex.slice(18 + 64, 18 + 128)).toBe(expectedEncodedAmount);
+    });
+    test('encodes from pre-encoded calldata (single element)', () => {
+        const rawCalldata = `0x${expectedSelector}${expectedEncodedAddress}${expectedEncodedAmount}`;
+        const result = encodeCrcV2TransferData([rawCalldata], 0x0004);
+        const hex = result.slice(2);
+        expect(hex.slice(0, 10)).toBe('0100040044');
+        expect(hex.slice(10, 18)).toBe(expectedSelector);
+    });
+    test('decodes known selector with resolved signature and params', () => {
+        const encoded = encodeCrcV2TransferData([signature, address, amount], 0x0004);
+        const decoded = decodeCrcV2TransferData(encoded);
+        expect(decoded.type).toBe(0x0004);
+        expect(decoded.length).toBe(68); // 4 selector + 32 + 32
+        const p = decoded.payload;
+        expect(p.selector).toBe(`0x${expectedSelector}`);
+        expect(p.signature).toBe(signature);
+        expect(p.params.length).toBe(2);
+        // address param (lowercased with checksum)
+        expect(p.params[0].toLowerCase()).toBe(address.toLowerCase());
+        // uint256 param
+        expect(p.params[1]).toBe(amount);
+    });
+    test('decodes raw calldata with known selector', () => {
+        const rawCalldata = `0x${expectedSelector}${expectedEncodedAddress}${expectedEncodedAmount}`;
+        const encoded = encodeCrcV2TransferData([rawCalldata], 0x0004);
+        const decoded = decodeCrcV2TransferData(encoded);
+        const p = decoded.payload;
+        expect(p.selector).toBe(`0x${expectedSelector}`);
+        expect(p.signature).toBe(signature);
+        expect(p.params.length).toBe(2);
+    });
+    test('returns raw data for unknown selector', () => {
+        // Craft calldata with a selector not in the lookup table
+        // Use 8 zeros padded — extremely unlikely to be a real function
+        const unknownSelector = 'ffffffff';
+        const fakePayload = unknownSelector + expectedEncodedAddress;
+        const encoded = encodeCrcV2TransferData([`0x${fakePayload}`], 0x0004);
+        const decoded = decodeCrcV2TransferData(encoded);
+        // Unknown selector — payload is raw hex string
+        expect(typeof decoded.payload).toBe('string');
+        expect(decoded.payload).toBe(`0x${fakePayload}`);
+    });
+    test('throws for invalid signature', () => {
+        expect(() => encodeCrcV2TransferData(['notASignature', address], 0x0004)).toThrow();
+    });
+});
+// ============================================================================
+// Version handling
+// ============================================================================
+describe('Version handling', () => {
+    test('default version is 0x01', () => {
+        const encoded = encodeCrcV2TransferData(['test'], 0x0001);
+        expect(encoded.slice(2, 4)).toBe('01');
+    });
+    test('throws on version mismatch when decoding', () => {
+        const encoded = encodeCrcV2TransferData(['test'], 0x0001, 0x01);
+        expect(() => decodeCrcV2TransferData(encoded, 0x02)).toThrow(/version/i);
+    });
+});
+// ============================================================================
+// Error cases
+// ============================================================================
+describe('Error cases', () => {
+    test('throws for unsupported type in encode', () => {
+        expect(() => encodeCrcV2TransferData(['foo'], 0x9999)).toThrow();
+    });
+    test('throws for unsupported type in decode', () => {
+        // Manually craft an encoded payload with type 0x9999
+        const hex = '0x01999900020000';
+        expect(() => decodeCrcV2TransferData(hex)).toThrow();
+    });
+    test('throws for data too short to decode', () => {
+        expect(() => decodeCrcV2TransferData('0x0100')).toThrow(/too short/i);
+    });
+    test('throws for payload length mismatch', () => {
+        // Header says length=10 but no payload follows
+        const hex = '0x' + '01' + '0001' + '000a'; // 5 header bytes, claims 10 payload bytes
+        expect(() => decodeCrcV2TransferData(hex)).toThrow(/mismatch/i);
+    });
+});

package/dist/transferData.d.ts

@@ -0,0 +1,30 @@
+import type { Hex, DecodedTransferData, TransferDataType } from '@aboutcircles/sdk-types';
+export type { TransferDataType, DecodedTransferData, DecodedAbiPayload, DecodedMetadataPayload } from '@aboutcircles/sdk-types';
+/**
+ * Encodes payload data for Circles V2 transfer annotations.
+ *
+ * Format: [version: 1B][type: 2B][length: 2B][payload bytes]
+ *
+ * Types:
+ * - 0x0001: UTF-8 text string
+ * - 0x1001: UTF-8 text with metadata (payload[0] = message, payload[1] = metadata string)
+ * - 0x0002: Raw 32-byte hex (e.g. XMTP message ID)
+ * - 0x0003: IPFS CID string (CIDv0 or CIDv1, converted to hex)
+ * - 0x0004: ABI-encoded calldata
+ *   - payload[0] can be: a function signature string + params, or raw encoded hex calldata
+ *
+ * @param payload - Array of values; interpretation depends on type
+ * @param type    - Transfer data type (0x0001–0x0004)
+ * @param version - Protocol version (default 0x01)
+ * @returns 0x-prefixed hex string
+ */
+export declare function encodeCrcV2TransferData(payload: unknown[], type: TransferDataType, version?: number): Hex;
+/**
+ * Decodes Circles V2 transfer data annotation from hex.
+ *
+ * @param encoded - 0x-prefixed hex string (as returned from circles_getTransferData)
+ * @param version - Expected protocol version (default 0x01); throws if mismatch
+ * @returns Decoded struct with type, length, and payload
+ */
+export declare function decodeCrcV2TransferData(encoded: string, version?: number): DecodedTransferData;
+//# sourceMappingURL=transferData.d.ts.map

package/dist/transferData.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transferData.d.ts","sourceRoot":"","sources":["../src/transferData.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,GAAG,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAM1F,YAAY,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AA8HhI;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,OAAO,EAAE,EAClB,IAAI,EAAE,gBAAgB,EACtB,OAAO,GAAE,MAAa,GACrB,GAAG,CA4FL;AAMD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,MAAa,GACrB,mBAAmB,CA+FrB"}

package/dist/transferData.js

@@ -0,0 +1,314 @@
+import { CID } from 'multiformats/cid';
+import { base16 } from 'multiformats/bases/base16';
+import { base58btc } from 'multiformats/bases/base58';
+import { keccak_256 } from '@noble/hashes/sha3.js';
+import { encodeFunctionData } from './abi.js';
+import { decodeAbiParameters } from './abi.js';
+import { hexToBytes, bytesToHex } from './bytes.js';
+import { EncodingError } from './errors.js';
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+const VERSION_BYTES = 1;
+const TYPE_BYTES = 2;
+const LENGTH_BYTES = 2;
+const HEADER_BYTES = VERSION_BYTES + TYPE_BYTES + LENGTH_BYTES; // 5
+// ============================================================================
+// HELPERS
+// ============================================================================
+function numToHex(value, byteLength) {
+    return value.toString(16).padStart(byteLength * 2, '0');
+}
+function hexNum(hex, offset, length) {
+    return parseInt(hex.slice(offset, offset + length * 2), 16);
+}
+function cidToHex(cid) {
+    try {
+        const parsed = CID.parse(cid, base58btc);
+        const v1 = parsed.toV1();
+        // base16 (hex) encoding includes 'f' prefix - strip it
+        const encoded = v1.toString(base16);
+        return encoded.startsWith('f') ? encoded.slice(1) : encoded;
+    }
+    catch {
+        // Try as CIDv1 directly
+        const parsed = CID.parse(cid);
+        const v1 = parsed.toV1();
+        const encoded = v1.toString(base16);
+        return encoded.startsWith('f') ? encoded.slice(1) : encoded;
+    }
+}
+const METADATA_SEPARATOR = '480a868a'; // keccak256("metadataStart") first 4 bytes
+function hexToCid(hex) {
+    const bytes = hexToBytes(hex.startsWith('0x') ? hex : `0x${hex}`);
+    const cid = CID.decode(bytes);
+    // Return CIDv0 if compatible (dag-pb + sha2-256), otherwise CIDv1
+    const isDagPb = cid.code === 0x70;
+    const isSha256 = cid.multihash.code === 0x12;
+    if (isDagPb && isSha256) {
+        return cid.toV0().toString();
+    }
+    return cid.toString();
+}
+// @todo construct lookup table based on the contracts in the core pkg
+// ============================================================================
+// LOCAL SELECTOR LOOKUP TABLE
+// ============================================================================
+/** Known function signatures for local selector resolution. */
+const KNOWN_SIGNATURES = [
+    // ERC20
+    'transfer(address,uint256)',
+    'transferFrom(address,address,uint256)',
+    'approve(address,uint256)',
+    'increaseAllowance(address,uint256)',
+    'decreaseAllowance(address,uint256)',
+    'balanceOf(address)',
+    'allowance(address,address)',
+    'totalSupply()',
+    'decimals()',
+    'permit(address,address,uint256,uint256,uint8,bytes32,bytes32)',
+    // ERC1155
+    'safeTransferFrom(address,address,uint256,uint256,bytes)',
+    'safeBatchTransferFrom(address,address,uint256[],uint256[],bytes)',
+    'setApprovalForAll(address,bool)',
+    'isApprovedForAll(address,address)',
+    // Circles Hub V2
+    'trust(address,uint96)',
+    'isTrusted(address,address)',
+    'isHuman(address)',
+    'wrap(address,uint256,uint8)',
+    'toTokenId(address)',
+    'operateFlowMatrix(address[],tuple[],tuple[],bytes)',
+    // Wrapped Circles
+    'unwrap(uint256)',
+    'convertDemurrageToInflationaryValue(uint256,uint64)',
+    'convertInflationaryToDemurrageValue(uint256,uint64)',
+    // Safe
+    'enableModule(address)',
+    'isModuleEnabled(address)',
+    // Invitation
+    'trustInviter(address)',
+    'claimInvite()',
+    'claimInvites(uint256)',
+    'createAccount(address)',
+    'createAccounts(address[])',
+    // LiftERC20
+    'erc20Circles(uint8,address)',
+];
+/** Compute 4-byte selector from a function signature string. */
+function computeSelector(sig) {
+    const hash = keccak_256(new TextEncoder().encode(sig));
+    return bytesToHex(hash.slice(0, 4)).slice(2); // strip 0x, 8 hex chars
+}
+/** Map from 8-char hex selector → full signature string. Built once at module load. */
+const SELECTOR_TABLE = new Map(KNOWN_SIGNATURES.map(sig => [computeSelector(sig), sig]));
+/**
+ * Parse a function signature string into param type strings.
+ * e.g. "transfer(address,uint256)" → ["address", "uint256"]
+ */
+function parseSignatureTypes(signature) {
+    const parenIdx = signature.indexOf('(');
+    if (parenIdx === -1)
+        return [];
+    const inner = signature.slice(parenIdx + 1, -1);
+    if (!inner)
+        return [];
+    return inner.split(',').map(t => t.trim()).filter(Boolean);
+}
+// ============================================================================
+// ENCODE
+// ============================================================================
+/**
+ * Encodes payload data for Circles V2 transfer annotations.
+ *
+ * Format: [version: 1B][type: 2B][length: 2B][payload bytes]
+ *
+ * Types:
+ * - 0x0001: UTF-8 text string
+ * - 0x1001: UTF-8 text with metadata (payload[0] = message, payload[1] = metadata string)
+ * - 0x0002: Raw 32-byte hex (e.g. XMTP message ID)
+ * - 0x0003: IPFS CID string (CIDv0 or CIDv1, converted to hex)
+ * - 0x0004: ABI-encoded calldata
+ *   - payload[0] can be: a function signature string + params, or raw encoded hex calldata
+ *
+ * @param payload - Array of values; interpretation depends on type
+ * @param type    - Transfer data type (0x0001–0x0004)
+ * @param version - Protocol version (default 0x01)
+ * @returns 0x-prefixed hex string
+ */
+export function encodeCrcV2TransferData(payload, type, version = 0x01) {
+    let payloadHex;
+    switch (type) {
+        case 0x0001: {
+            // UTF-8 text
+            const text = payload[0];
+            const bytes = new TextEncoder().encode(text);
+            payloadHex = bytesToHex(bytes).slice(2);
+            break;
+        }
+        case 0x1001: {
+            // UTF-8 text with metadata
+            const message = payload[0];
+            const metadata = payload[1];
+            const messageHex = bytesToHex(new TextEncoder().encode(message)).slice(2);
+            const metadataHex = bytesToHex(new TextEncoder().encode(metadata)).slice(2);
+            payloadHex = messageHex + METADATA_SEPARATOR + metadataHex;
+            break;
+        }
+        case 0x0002: {
+            // Raw hex (XMTP message ID - 32 bytes)
+            const raw = payload[0];
+            const cleaned = raw.startsWith('0x') ? raw.slice(2) : raw;
+            if (cleaned.length !== 64) {
+                throw new EncodingError(`Type 0x0002 expects a 32-byte hex value (64 hex chars), got ${cleaned.length / 2} bytes`, {
+                    code: 'ENCODING_INVALID_LENGTH',
+                });
+            }
+            payloadHex = cleaned.toLowerCase();
+            break;
+        }
+        case 0x0003: {
+            // IPFS CID
+            const cidStr = payload[0];
+            payloadHex = cidToHex(cidStr);
+            break;
+        }
+        case 0x0004: {
+            // ABI-encoded calldata
+            const first = payload[0];
+            if (payload.length === 1 && first.startsWith('0x')) {
+                // Raw pre-encoded calldata
+                payloadHex = first.slice(2).toLowerCase();
+            }
+            else {
+                // Function signature + params
+                const signature = first; // e.g. "transfer(address,uint256)"
+                const parenIdx = signature.indexOf('(');
+                if (parenIdx === -1) {
+                    throw new EncodingError('Type 0x0004 payload[0] must be a function signature like "transfer(address,uint256)"', {
+                        code: 'ENCODING_INVALID_SIGNATURE',
+                    });
+                }
+                const fnName = signature.slice(0, parenIdx);
+                const paramTypes = signature
+                    .slice(parenIdx + 1, -1)
+                    .split(',')
+                    .map(t => t.trim())
+                    .filter(Boolean);
+                const abiInputs = paramTypes.map((t, i) => ({ type: t, name: `p${i}` }));
+                const args = payload.slice(1);
+                const encoded = encodeFunctionData({
+                    abi: [{ name: fnName, type: 'function', stateMutability: 'nonpayable', inputs: abiInputs, outputs: [] }],
+                    functionName: fnName,
+                    args,
+                });
+                payloadHex = encoded.slice(2).toLowerCase();
+            }
+            break;
+        }
+        default:
+            throw new EncodingError(`Unsupported transfer data type: ${type}`, {
+                code: 'ENCODING_UNSUPPORTED_TYPE',
+                context: { type },
+            });
+    }
+    const payloadBytes = payloadHex.length / 2;
+    const header = numToHex(version, VERSION_BYTES) +
+        numToHex(type, TYPE_BYTES) +
+        numToHex(payloadBytes, LENGTH_BYTES);
+    return `0x${header}${payloadHex}`;
+}
+// ============================================================================
+// DECODE
+// ============================================================================
+/**
+ * Decodes Circles V2 transfer data annotation from hex.
+ *
+ * @param encoded - 0x-prefixed hex string (as returned from circles_getTransferData)
+ * @param version - Expected protocol version (default 0x01); throws if mismatch
+ * @returns Decoded struct with type, length, and payload
+ */
+export function decodeCrcV2TransferData(encoded, version = 0x01) {
+    const hex = encoded.startsWith('0x') ? encoded.slice(2) : encoded;
+    if (hex.length < HEADER_BYTES * 2) {
+        throw new EncodingError('Encoded data too short to contain header', {
+            code: 'ENCODING_TOO_SHORT',
+            context: { encoded },
+        });
+    }
+    const encodedVersion = hexNum(hex, 0, VERSION_BYTES);
+    if (encodedVersion !== version) {
+        throw new EncodingError(`Version mismatch: expected ${version}, got ${encodedVersion}`, {
+            code: 'ENCODING_VERSION_MISMATCH',
+            context: { expected: version, got: encodedVersion },
+        });
+    }
+    const type = hexNum(hex, VERSION_BYTES * 2, TYPE_BYTES);
+    const length = hexNum(hex, (VERSION_BYTES + TYPE_BYTES) * 2, LENGTH_BYTES);
+    const payloadHex = hex.slice(HEADER_BYTES * 2, HEADER_BYTES * 2 + length * 2);
+    if (payloadHex.length !== length * 2) {
+        throw new EncodingError('Payload length mismatch', {
+            code: 'ENCODING_LENGTH_MISMATCH',
+            context: { expected: length, got: payloadHex.length / 2 },
+        });
+    }
+    let payload;
+    switch (type) {
+        case 0x0001: {
+            // UTF-8 text
+            const bytes = hexToBytes(`0x${payloadHex}`);
+            payload = new TextDecoder().decode(bytes);
+            break;
+        }
+        case 0x1001: {
+            // UTF-8 text with metadata
+            const separatorIdx = payloadHex.indexOf(METADATA_SEPARATOR);
+            if (separatorIdx === -1) {
+                throw new EncodingError('Type 0x1001: metadata separator not found in payload', {
+                    code: 'ENCODING_MISSING_SEPARATOR',
+                });
+            }
+            const messageHex = payloadHex.slice(0, separatorIdx);
+            const metadataHex = payloadHex.slice(separatorIdx + METADATA_SEPARATOR.length);
+            const message = new TextDecoder().decode(hexToBytes(`0x${messageHex}`));
+            const metadata = new TextDecoder().decode(hexToBytes(`0x${metadataHex}`));
+            payload = { message, metadata };
+            break;
+        }
+        case 0x0002: {
+            // Raw hex
+            payload = `0x${payloadHex}`;
+            break;
+        }
+        case 0x0003: {
+            // IPFS CID (hex → CID string)
+            payload = hexToCid(payloadHex);
+            break;
+        }
+        case 0x0004: {
+            // ABI-encoded calldata — try local selector lookup, fallback to raw data
+            const selectorHex = payloadHex.slice(0, 8);
+            const selector = `0x${selectorHex}`;
+            const signature = SELECTOR_TABLE.get(selectorHex);
+            if (signature) {
+                const paramTypes = parseSignatureTypes(signature);
+                const paramsHex = payloadHex.slice(8);
+                const params = paramTypes.length > 0
+                    ? decodeAbiParameters(paramTypes, paramsHex)
+                    : [];
+                payload = { selector, signature, params };
+            }
+            else {
+                // Unknown selector — return raw calldata hex
+                payload = `0x${payloadHex}`;
+            }
+            break;
+        }
+        default:
+            throw new EncodingError(`Unsupported transfer data type: ${type}`, {
+                code: 'ENCODING_UNSUPPORTED_TYPE',
+                context: { type },
+            });
+    }
+    return { type: type, length, payload };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aboutcircles/sdk-utils",
-  "version": "0.1.25",
+  "version": "0.1.26",
   "description": "Utility functions for Circles SDK including demurrage calculations and conversions",
   "type": "module",
   "main": "./dist/index.js",