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 agent
description: string - Description of services offered
restrict_subscriptions: boolean - Whether to restrict subscriber access
capabilities: string[] - Array of supported capabilities
fee: 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 key
recipient: string - Address to receive the service
durationInDays: 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 key
newRecipient: string - Updated recipient address
newEndTime: number - New expiration timestamp
qualityScore: 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 key
qualityScore: 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 subscriber
requestIndex: 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);
}

PreviousSwarm Authentication NextKnown Issues

Last updated 5 months ago