-
Via NPM:
npm i @debridge-finance/solana-transaction-parser
-
Via github:
npm i git+https://github.com/debridge-finance/solana-tx-parser-public
. -
Manual package.json edit: dependencies/devDependencies section ->
"@debridge-finance/solana-transaction-parser": "github:debridge-finance/solana-tx-parser-public"
Then runnpm i
- Parse solana instructions using anchor IDL/custom parsers.
- Parse
SystemProgram
,TokenProgram
,AssociatedTokenProgram
instructions out of the box. - Parse transaction logs.
- Convert ParsedTransaction/CompiledTransaction/base64-encoded transaction into a list of TransactionInstructions and parse it.
- Unfold transaction with CPI into artificial transaction with CPI calls included as usual TransactionInstruction.
First step: init parser
import { Idl } from "@project-serum/anchor";
import { PublicKey, Connection } from "@solana/web3.js";
import { SolanaParser } from "@debridge-finance/solana-transaction-parser";
import { IDL as JupiterIdl, Jupiter } from "./idl/jupiter"; // idl and types file generated by Anchor
const rpcConnection = new Connection("https://jupiter.genesysgo.net");
const txParser = new SolanaParser([{ idl: JupiterIdl as unknown as Idl, programId: "JUP2jxvXaqu7NQY1GmNF4m1vodw12LVXYxbFL2uJvfo" }]);
Second step: parse transaction by tx hash:
const parsed = await txParser.parseTransaction(
rpcConnection,
"5zgvxQjV6BisU8SfahqasBZGfXy5HJ3YxYseMBG7VbR4iypDdtdymvE1jmEMG7G39bdVBaHhLYUHUejSTtuZEpEj",
false,
);
Voila! We have a list of TransactionInstruction with instruction names, args and accounts.
// we can find instruction by name
const tokenSwapIx = parsed?.find((pix) => pix.name === "tokenSwap");
// or just use index
const setTokenLedgerIx = parsed[0] as ParsedIdlInstruction<Jupiter, "setTokenLedger">;
What if the instructions we want to parse do not belong to Anchor program?
We could provide custom instruction parser to SolanaParser!
Custom parser need to have following interface: (instruction: TransactionInstruction): ParsedCustomInstruction
.
We've implemented a small program for testing purposes which can perform two actions: sum up two numbers (passed as u64 numbers) OR
print provided data to log (passed as ASCII codes and as a second account in accounts list).
First byte | Action |
---|---|
0 | Print remaining data as text + string "From: " + second account pubkey as base58 |
1 | Sum up two numbers and print the result to log |
Parser will be really simple in such case:
function customParser(instruction: TransactionInstruction): ParsedCustomInstruction {
let args: unknown;
let keys: ParsedAccount[];
let name: string;
switch (instruction.data[0]) {
case 0:
args = { message: instruction.data.slice(1).toString("utf8") };
keys = [instruction.keys[0], { name: "messageFrom", ...instruction.keys[1] }];
name = "echo";
break;
case 1:
args = { a: instruction.data.readBigInt64LE(1), b: instruction.data.readBigInt64LE(9) };
keys = instruction.keys;
name = "sum";
break;
default:
throw new Error("unknown instruction!");
}
return {
programId: instruction.programId,
accounts: keys,
args,
name,
};
}
Now we need to init SolanaParser object (which contains different parsers that can parse instructions from specified programs)
const parser = new SolanaParser([]);
parser.addParser(new PublicKey("5wZA8owNKtmfWGBc7rocEXBvTBxMtbpVpkivXNKXNuCV"), customParser);
UPD: Since solana devnet transactions become unavailable after some time, here's code that can be used to emit test transactions
import { Connection, Keypair, PublicKey, Transaction, TransactionInstruction, LAMPORTS_PER_SOL } from "@solana/web3.js";
import { Wallet } from "@project-serum/anchor";
function echoIx(msg: string, from: PublicKey) {
return new TransactionInstruction({
programId: new PublicKey("5wZA8owNKtmfWGBc7rocEXBvTBxMtbpVpkivXNKXNuCV"),
data: Buffer.concat([Buffer.from([0]), Buffer.from(msg)]),
keys: [
{ isSigner: true, isWritable: false, pubkey: from },
{ isSigner: false, isWritable: false, pubkey: new Keypair().publicKey },
],
});
}
function addIx(a: bigint, b: bigint, signer: PublicKey) {
const data: Buffer = Buffer.alloc(2 * 8 + 1);
data[0] = 1;
data.writeBigInt64LE(a, 1);
data.writeBigInt64LE(b, 9);
return new TransactionInstruction({
programId: new PublicKey("5wZA8owNKtmfWGBc7rocEXBvTBxMtbpVpkivXNKXNuCV"),
data,
keys: [
{ isSigner: true, isWritable: false, pubkey: signer },
{ isSigner: false, isWritable: false, pubkey: new Keypair().publicKey },
],
});
}
const tx = new Transaction().add(echoIx("some test msg", kp.publicKey), addIx(555n, 1234n, kp.publicKey));
// send tx using devnet connection and your wallet
To parse transaction which contains this instructions we only need to call parseTransaction
method on parser object
const connection = new Connection(clusterApiUrl("devnet"));
const parsed = await parser.parseTransaction(connection, "5xEeZMdrWVG7i8Fbcbu718FtbgSbXsK9c4GPBv21W2e35vP4DdkVghqH4p8dPKdmroUzNe2mBkctm4RAxaVbo78G");
// check if no errors was produced during parsing
if (!parsed) throw new Error("failed to get tx/parse!");
console.log(parsed[0].name); // will print "echo"
Main functions of this project are:
- instruction deserialization
- flattening transactions with CPI calls
- parsing transaction logs
This part is pretty simple: we have some const mapping = Map<string, Parser>
where keys are program ids and values are parsers for corresponding programId - function that takes TransactionInstruction as input and returns ParsedInstruction (deserialized data, instruction name and accounts meta [with names]).
We can deserialize TransactionInstruction using Anchor's IDL or custom parser, hence we can deserialize everything which consists of (or can be converted into) TransactionInstructions: Transaction, ParsedTransaction, TransactionResponse, ParsedConfirmedTransaction, Message, CompiledMessage, CompiledInstruction or wire transaction, etc.
Steps of parsing are following:
- Convert input into TransactionInstruction, lets name it ix (different functions need to be called for different input formats)
- Find
ix.programId
in the mapping. If parser exists pass ix to it - Check parsed instruction name, set correct data types using generics
Function: flattenTransactionResponse
Can be only done with TransactionResponse/ParsedTransactionWithMeta objects because we need transaction.meta.innerInstructions
field.
transaction.meta.innerInstructions
is a list of objects of following structure:
export type CompiledInnerInstruction = {
index: number, // index of instruction in Transaction object which produced CPI,
instructions: CompiledInstruction[] // ordered list of instructions which were called after instruction with index *index*
}
We create artificial const result: Transaction = new Transaction();
object which contains all the instructions from TransactionResponse + CPI calls:
Add first TransactionInstruction to result, check if CPI calls with index = 0 exist, add them to result, move to the next instruction, repeat.
Finally, we check that result.instructions.length === input.instructions.length + total number of CPI instructions
.
We can call index of result.instructions callId - index of call in the whole transaction. Same callId will be used in the logs part
Function: parseLogs
Working with Solana's logs is not a trivial task - to determine which program emitted current log line we have to restore call stack, check call depth and set correct callId for each log line. parseLogs function implements all that stuff (with call depth and call id checks):
- Iterate over logs
- Check log type (invoke/return/error/program log/program data) using regex
- According to the log type perform action:
- Invoke: init and save new context object which contains program id, call depth of instruction, callId, index of instruction in Transaction which produced log (depth == 0) or current CPI call (depth != 0), save call stack (push current callId into stack)
- Return success/fail: pop caller id from call stack, current callId = popped callId
- program log/program data/program consumed: save log into context object with callId == current callId
- Return list of context objects
import { ourIdl } from "programIdl";
const parser = new SolanaParser([{programId: "someBase58Address", idl: ourIdl}]);
const flattened = flattenTransactionResponse(response);
const logs = parseLogs(response.meta.logs || []);
const parsed = flattened.map((ix) => parser.parse(ix));
const callId = parsed.findIndex( (parsedIx) => parsedIx.name === "someInstruction" );
if (callId === -1) return Promise.reject("instruction not found");
const someInstruction = parsed[callId];
const someInstructionLogs = logs.find((context) => context.id === callId);
const onlyNeededProgramLogs = logs.filter((context) => context.programId === "someBase58Address");