Skip to content

docs: Update README with comprehensive documentation #11

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lalalune merged 16 commits into from
Feb 8, 2026

docs: update README with comprehensive documentation

43423f1
Select commit
Loading
Failed to load commit list.
Merged

docs: Update README with comprehensive documentation #11

docs: update README with comprehensive documentation
43423f1
Select commit
Loading
Failed to load commit list.
Cursor / Cursor Bugbot completed Jul 23, 2025 in 2m 38s

Bugbot Review

BugBot Analysis Progress (2m 40s elapsed)

✅ Gathered PR context (1s)
✅ Analyzed code changes (1s)
✅ Completed bug detection — 3 potential bugs found (2m 36s)
✅ Validation and filtering completed (0s)
✅ Posted analysis results — 3 bugs reported (2s)
✅ Analysis completed successfully (0s)

Final Result: Bugbot completed review and found 3 potential issues

Request ID: serverGenReqId_d4b004d4-45d4-437d-b201-98abaf4f085d

Details

Bug: Plugin Initialization Prematurely Completes

The solanaPlugin.init function prematurely resolves its internal Promise before completing its asynchronous setup (waiting for the TRADER_CHAIN service and registering the chain). This causes the init function to complete prematurely, leading to potential race conditions or incomplete plugin initialization.

src/index.ts#L17-L39

plugin-solana/src/index.ts

Lines 17 to 39 in 43423f1

new Promise<void>(async (resolve) => {
resolve();
const asking = 'solana';
const serviceType = 'TRADER_CHAIN';
let traderChainService = runtime.getService(serviceType) as any;
while (!traderChainService) {
console.log(asking, 'waiting for', serviceType, 'service...');
traderChainService = runtime.getService(serviceType) as any;
if (!traderChainService) {
await new Promise((waitResolve) => setTimeout(waitResolve, 1000));
} else {
console.log(asking, 'Acquired', serviceType, 'service...');
}
}
const me = {
name: 'Solana services',
};
traderChainService.registerChain(me);
console.log('solana init done');
});

Fix in Cursor • Fix in Web

Bug: Async Initialization Causes Undefined PublicKey

A race condition exists in the SolanaService constructor where this.publicKey is initialized asynchronously. This allows methods like updateWalletData() to be called before this.publicKey is set. When this.publicKey is undefined, updateWalletData() returns an empty object {}, which violates its Promise<WalletPortfolio> return type. The WalletPortfolio interface requires totalUsd: string and items: Array<Item>, leading to runtime errors when consumers attempt to access these missing properties.

src/service.ts#L181-L188

plugin-solana/src/service.ts

Lines 181 to 188 in 43423f1

if (!this.publicKey) {
// can't be warn if we fire every start up
// maybe we just get the pubkey here proper
// or fall back to SOLANA_PUBLIC_KEY
logger.log('solana::updateWalletData - no Public Key yet');
return {};
}

src/service.ts#L42-L62

plugin-solana/src/service.ts

Lines 42 to 62 in 43423f1

*/
constructor(protected runtime: IAgentRuntime) {
super();
this.exchangeRegistry = {};
const connection = new Connection(
runtime.getSetting('SOLANA_RPC_URL') || PROVIDER_CONFIG.DEFAULT_RPC
);
this.connection = connection;
// Initialize publicKey using getWalletKey
getWalletKey(runtime, false)
.then(({ publicKey }) => {
if (!publicKey) {
throw new Error('Failed to initialize public key');
}
this.publicKey = publicKey;
})
.catch((error) => {
logger.error('Error initializing public key:', error);
});
this.subscriptions = new Map();
}

Fix in Cursor • Fix in Web

Bug: Direct Environment Access Bypasses Configuration

The SOL_ADDRESS is directly accessed via process.env.SOL_ADDRESS in swapToken and executeSwap functions. This bypasses the runtime configuration system (runtime.getSetting) and could lead to failures if the environment variable is not set or differs from the intended runtime setting.

src/actions/swap.ts#L65-L66

plugin-solana/src/actions/swap.ts

Lines 65 to 66 in 43423f1

const decimals =
inputTokenCA === process.env.SOL_ADDRESS

src/actions/swap.ts#L283-L287

plugin-solana/src/actions/swap.ts

Lines 283 to 287 in 43423f1

if (response.inputTokenSymbol?.toUpperCase() === 'SOL') {
response.inputTokenCA = process.env.SOL_ADDRESS;
}
if (response.outputTokenSymbol?.toUpperCase() === 'SOL') {
response.outputTokenCA = process.env.SOL_ADDRESS;

Fix in Cursor • Fix in Web

Was this report helpful? Give feedback by reacting with 👍 or 👎

View more details on Cursor