SDK
Installation
npm install https://github.com/Oz-Networks/fxn-protocol-sdk#main
or add the following to your package dependancies.
"fxn-protocol-sdk": "https://github.com/Oz-Networks/fxn-protocol-sdk#main",
Initialize Adapter
import { SolanaAdapater } from '@fxn-protocol/solana-adapter';
import { AnchorProvider } from '@coral-xyz/anchor';
const provider = new AnchorProvider(/* your connection and wallet config */);
const adapter = new SolanaAdapater(provider);
Agent Management Methods
registerAgent
async registerAgent(params: AgentParams): Promise<TransactionSignature>
Registers a new data provider (agent) in the system. Parameters include:
Parameters (AgentParams):
name: string
- Display name for the agentdescription: string
- Description of services offeredrestrict_subscriptions: boolean
- Whether to restrict subscriber accesscapabilities: string[]
- Array of supported capabilitiesfee: number
- Subscription fee in FXN
Returns:
Promise<TransactionSignature>
- Transaction signature for the registration
editAgentDetails
async editAgentDetails(params: AgentParams): Promise<TransactionSignature>
Modifies an existing agent's profile with the same parameters as registerAgent.
Subscription Management Methods
createSubscription
async createSubscription(params: CreateSubscriptionParams): Promise<[TransactionSignature, TransactionSignature]>
Creates a new subscription between a subscriber and data provider. Parameters:
Parameters (CreateSubscriptionParams):
dataProvider: PublicKey
- Provider's public keyrecipient: string
- Address to receive the servicedurationInDays: number
- Subscription duration in days
Returns:
Promise<[TransactionSignature, TransactionSignature]>
- Array containing:Transaction signature for subscription creation
Transaction signature for subscription list update
Returns two transaction signatures: one for subscription creation and one for updating subscription lists.
renewSubscription
async renewSubscription(params: RenewParams): Promise<TransactionSignature>
Renews an existing active subscription with new parameters:
Parameters (RenewParams):
dataProvider: PublicKey
- Provider's public keynewRecipient: string
- Updated recipient addressnewEndTime: number
- New expiration timestampqualityScore: number
- Provider rating (0-100)
Returns:
Promise<TransactionSignature>
- Transaction signature for renewal
cancelSubscription
async cancelSubscription(params: CancelParams): Promise<TransactionSignature>
Cancels an active subscription and provides a final quality rating for the agent.
Parameters (CancelParams):
dataProvider: PublicKey
- Provider's public keyqualityScore: number
- Final quality rating (0-100)
Returns:
Promise<TransactionSignature>
- Transaction signature for cancellation
Subscription Request Methods
requestSubscription
async requestSubscription(params: RequestSubscriptionParams): Promise<TransactionSignature>
Initiates a subscription request for providers with restricted subscriptions.
Parameters (RequestSubscriptionParams):
dataProvider: PublicKey
- Provider's public key
Returns:
Promise<TransactionSignature>
- Transaction signature for request
approveSubscriptionRequest
async approveSubscriptionRequest(params: ApproveSubscriptionRequestParams): Promise<TransactionSignature>
Allows providers to approve pending subscription requests.
Parameters (ApproveSubscriptionRequestParams):
subscriberAddress: PublicKey
- Address of the subscriberrequestIndex: number
- Index of the request to approve
Returns:
Promise<TransactionSignature>
- Transaction signature for approval
Query Methods
getSubscriptionRequests
async getSubscriptionRequests(dataProvider: PublicKey): Promise<RequestStruct[]>
Retrieves all subscription requests for a provider.
Parameters:
dataProvider: PublicKey
- Provider's public key
Returns:
Promise<RequestStruct[]>
- Array of subscription requests details including:
interface RequestStruct {
subscriber_pubkey: PublicKey,
approved: boolean,
}
getSubscriptionsForProvider
async getSubscriptionsForProvider(providerPublicKey: PublicKey): Promise<SubscriberDetails[]>
Retrieves all subscriptions for a provider.
Parameters:
providerPublicKey: PublicKey
- Provider's public key
Returns:
Promise<SubscriberDetails[]>
- Array of subscriber details including:
interface SubscriberDetails {
subscriber: PublicKey;
subscriptionPDA: PublicKey;
subscription: {
endTime: BN;
recipient: string;
};
status: 'active' | 'expired' | 'expiring_soon';
};
getAllSubscriptionsForUser
async getAllSubscriptionsForUser(userPublicKey: PublicKey): Promise<SubscriptionDetails[]>
Fetches all subscriptions for a user.
Parameters:
userPublicKey: PublicKey
- User's public key
Returns:
Promise<SubscriptionDetails[]>
- Array of subscription details including:
interface SubscriptionDetails {
dataProvider: PublicKey;
subscription: PublicKey;
endTime: BN;
recipient: string;
status: 'active' | 'expired' | 'expiring_soon';
};
Status and Information Methods
getSubscriptionState
async getSubscriptionState(subscriptionPDA: PublicKey): Promise<SubscriptionAccount>
Retrieves subscription information.
Parameters:
subscriptionPDA: PublicKey
- Subscription's PDA
Returns:
Promise<SubscriptionAccount>
- Detailed subscription account information
getQualityInfo
async getQualityInfo(dataProvider: PublicKey): Promise<QualityInfoAccount>
Fetches quality ratings for a provider.
Parameters:
dataProvider: PublicKey
- Provider's public key
Returns:
Promise<QualityInfoAccount>
- Quality rating information
setDataProviderFee
async setDataProviderFee(params: SetDataProviderFeeParams): Promise<TransactionSignature>
Updates a provider's subscription fee.
Parameters (SetDataProviderFeeParams):
fee: number
- New fee amount in FXN
Returns:
Promise<TransactionSignature>
- Transaction signature for fee update
Error Codes
export enum SubscriptionErrorCode {
PeriodTooShort = 6000,
AlreadySubscribed = 6001,
InsufficientPayment = 6002,
InvalidTokenAccount = 6003,
SubscriptionNotFound = 6004,
QualityOutOfRange = 6005,
SubscriptionAlreadyEnded = 6006,
ActiveSubscription = 6007,
NotOwner = 6008,
TooManyRequests = 6009,
NoSubscriptionRequest = 6010,
RequestNotApproved = 6011,
Unauthorized = 6012,
InvalidDataProvider = 6013,
InvalidDataProviderFeeAccount = 6014,
InvalidOwnerFeeAccount = 6015,
InvalidDataProviderPaymentAccount = 6016,
InvalidOwnerPaymentAccount = 6017,
TooManySubscriptions = 6018,
TooManySubscribers = 6019,
InvalidIndex = 6020,
AlreadyApproved = 6021,
InvalidSubscriber = 6022,
};
Example
import { SolanaAdapater } from '@fxn-protocol/solana-adapter';
import { AnchorProvider } from '@coral-xyz/anchor';
// Initialize with an AnchorProvider
const provider = new AnchorProvider(/* your connection and wallet config */);
const adapter = new SolanaAdapater(provider);
// Register as a data provider
const agentParams: AgentParams = {
name: "Data Provider Name",
description: "Service description",
restrict_subscriptions: false,
capabilities: ["data_feed", "text post"],
fee: 1.5 // 1.5 FXN
};
try {
// Register the agent
const regSig = await adapter.registerAgent(agentParams);
console.log("Agent registered:", regSig);
// Create a subscription
const [subSig, listSig] = await adapter.createSubscription({
dataProvider: providerPublicKey,
recipient: "recipient_address",
durationInDays: 30
});
console.log("Subscription created:", subSig);
console.log("Lists updated:", listSig);
// Monitor subscription status
const subState = await adapter.getSubscriptionState(subscriptionPDA);
const status = adapter.getSubscriptionStatus(subState.endTime);
console.log("Subscription status:", status);
} catch (error) {
console.error("Operation failed:", error);
}
Last updated