@bsv/sdk
Version:
BSV Blockchain Software Development Kit
692 lines (481 loc) • 21.6 kB
Markdown
# API
Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
## Interfaces
| |
| --- |
| [AdmittanceInstructions](#interface-admittanceinstructions) |
| [LookupQuestion](#interface-lookupquestion) |
| [LookupResolverConfig](#interface-lookupresolverconfig) |
| [OverlayBroadcastFacilitator](#interface-overlaybroadcastfacilitator) |
| [OverlayLookupFacilitator](#interface-overlaylookupfacilitator) |
| [RankedHost](#interface-rankedhost) |
| [SHIPBroadcasterConfig](#interface-shipbroadcasterconfig) |
| [TaggedBEEF](#interface-taggedbeef) |
Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
### Interface: AdmittanceInstructions
Instructs the Overlay Services Engine about which outputs to admit and which previous outputs to retain. Returned by a Topic Manager.
```ts
export interface AdmittanceInstructions {
outputsToAdmit: number[];
coinsToRetain: number[];
coinsRemoved?: number[];
}
```
#### Property coinsRemoved
The indices of all inputs from the provided transaction which reference previously-admitted outputs,
which are now considered spent and have been removed from the managed topic.
```ts
coinsRemoved?: number[]
```
#### Property coinsToRetain
The indices of all inputs from the provided transaction which spend previously-admitted outputs that should be retained for historical record-keeping.
```ts
coinsToRetain: number[]
```
#### Property outputsToAdmit
The indices of all admissible outputs into the managed topic from the provided transaction.
```ts
outputsToAdmit: number[]
```
Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
### Interface: LookupQuestion
The question asked to the Overlay Services Engine when a consumer of state wishes to look up information.
```ts
export interface LookupQuestion {
service: string;
query: unknown;
}
```
#### Property query
The query which will be forwarded to the Lookup Service.
Its type depends on that prescribed by the Lookup Service employed.
```ts
query: unknown
```
#### Property service
The identifier for a Lookup Service which the person asking the question wishes to use.
```ts
service: string
```
Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
### Interface: LookupResolverConfig
Configuration options for the Lookup resolver.
```ts
export interface LookupResolverConfig {
networkPreset?: "mainnet" | "testnet" | "local";
facilitator?: OverlayLookupFacilitator;
slapTrackers?: string[];
hostOverrides?: Record<string, string[]>;
additionalHosts?: Record<string, string[]>;
cache?: CacheOptions;
reputationStorage?: "localStorage" | {
get: (key: string) => string | null | undefined;
set: (key: string, value: string) => void;
};
}
```
See also: [OverlayLookupFacilitator](./overlay-tools.md#interface-overlaylookupfacilitator)
#### Property additionalHosts
Map of lookup service names to arrays of hosts to use in addition to resolving via SLAP.
```ts
additionalHosts?: Record<string, string[]>
```
#### Property cache
Optional cache tuning.
```ts
cache?: CacheOptions
```
#### Property facilitator
The facilitator used to make requests to Overlay Services hosts.
```ts
facilitator?: OverlayLookupFacilitator
```
See also: [OverlayLookupFacilitator](./overlay-tools.md#interface-overlaylookupfacilitator)
#### Property hostOverrides
Map of lookup service names to arrays of hosts to use in place of resolving via SLAP.
```ts
hostOverrides?: Record<string, string[]>
```
#### Property networkPreset
The network preset to use, unless other options override it.
- mainnet: use mainnet SLAP trackers and HTTPS facilitator
- testnet: use testnet SLAP trackers and HTTPS facilitator
- local: directly query from localhost:8080 and a facilitator that permits plain HTTP
```ts
networkPreset?: "mainnet" | "testnet" | "local"
```
#### Property reputationStorage
Optional storage for host reputation data.
```ts
reputationStorage?: "localStorage" | {
get: (key: string) => string | null | undefined;
set: (key: string, value: string) => void;
}
```
#### Property slapTrackers
The list of SLAP trackers queried to resolve Overlay Services hosts for a given lookup service.
```ts
slapTrackers?: string[]
```
Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
### Interface: OverlayBroadcastFacilitator
Facilitates transaction broadcasts that return STEAK.
```ts
export interface OverlayBroadcastFacilitator {
send: (url: string, taggedBEEF: TaggedBEEF) => Promise<STEAK>;
}
```
See also: [STEAK](./overlay-tools.md#type-steak), [TaggedBEEF](./overlay-tools.md#interface-taggedbeef)
Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
### Interface: OverlayLookupFacilitator
Facilitates lookups to URLs that return answers.
```ts
export interface OverlayLookupFacilitator {
lookup: (url: string, question: LookupQuestion, timeout?: number) => Promise<LookupAnswer>;
}
```
See also: [LookupAnswer](./overlay-tools.md#type-lookupanswer), [LookupQuestion](./overlay-tools.md#interface-lookupquestion)
#### Property lookup
Returns a lookup answer for a lookup question
```ts
lookup: (url: string, question: LookupQuestion, timeout?: number) => Promise<LookupAnswer>
```
See also: [LookupAnswer](./overlay-tools.md#type-lookupanswer), [LookupQuestion](./overlay-tools.md#interface-lookupquestion)
Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
### Interface: RankedHost
```ts
export interface RankedHost extends HostReputationEntry {
score: number;
}
```
Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
### Interface: SHIPBroadcasterConfig
Configuration options for the SHIP broadcaster.
```ts
export interface SHIPBroadcasterConfig {
networkPreset?: "mainnet" | "testnet" | "local";
facilitator?: OverlayBroadcastFacilitator;
resolver?: LookupResolver;
requireAcknowledgmentFromAllHostsForTopics?: "all" | "any" | string[];
requireAcknowledgmentFromAnyHostForTopics?: "all" | "any" | string[];
requireAcknowledgmentFromSpecificHostsForTopics?: Record<string, "all" | "any" | string[]>;
}
```
See also: [LookupResolver](./overlay-tools.md#class-lookupresolver), [OverlayBroadcastFacilitator](./overlay-tools.md#interface-overlaybroadcastfacilitator)
#### Property facilitator
The facilitator used to make requests to Overlay Services hosts.
```ts
facilitator?: OverlayBroadcastFacilitator
```
See also: [OverlayBroadcastFacilitator](./overlay-tools.md#interface-overlaybroadcastfacilitator)
#### Property networkPreset
The network preset to use, unless other options override it.
- mainnet: use mainnet resolver and HTTPS facilitator
- testnet: use testnet resolver and HTTPS facilitator
- local: directly send to localhost:8080 and a facilitator that permits plain HTTP
```ts
networkPreset?: "mainnet" | "testnet" | "local"
```
#### Property requireAcknowledgmentFromAllHostsForTopics
Determines which topics (all, any, or a specific list) must be present within all STEAKs received from every host for the broadcast to be considered a success. By default, all hosts must acknowledge all topics.
```ts
requireAcknowledgmentFromAllHostsForTopics?: "all" | "any" | string[]
```
#### Property requireAcknowledgmentFromAnyHostForTopics
Determines which topics (all, any, or a specific list) must be present within STEAK received from at least one host for the broadcast to be considered a success.
```ts
requireAcknowledgmentFromAnyHostForTopics?: "all" | "any" | string[]
```
#### Property requireAcknowledgmentFromSpecificHostsForTopics
Determines a mapping whose keys are specific hosts and whose values are the topics (all, any, or a specific list) that must be present within the STEAK received by the given hosts, in order for the broadcast to be considered a success.
```ts
requireAcknowledgmentFromSpecificHostsForTopics?: Record<string, "all" | "any" | string[]>
```
#### Property resolver
The resolver used to locate suitable hosts with SHIP
```ts
resolver?: LookupResolver
```
See also: [LookupResolver](./overlay-tools.md#class-lookupresolver)
Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
### Interface: TaggedBEEF
Tagged BEEF
```ts
export interface TaggedBEEF {
beef: number[];
topics: string[];
offChainValues?: number[];
}
```
Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
## Classes
| |
| --- |
| [HTTPSOverlayBroadcastFacilitator](#class-httpsoverlaybroadcastfacilitator) |
| [HTTPSOverlayLookupFacilitator](#class-httpsoverlaylookupfacilitator) |
| [HostReputationTracker](#class-hostreputationtracker) |
| [LookupResolver](#class-lookupresolver) |
| [OverlayAdminTokenTemplate](#class-overlayadmintokentemplate) |
| [TopicBroadcaster](#class-topicbroadcaster) |
Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
### Class: HTTPSOverlayBroadcastFacilitator
```ts
export class HTTPSOverlayBroadcastFacilitator implements OverlayBroadcastFacilitator {
httpClient: typeof fetch;
allowHTTP: boolean;
constructor(httpClient = fetch, allowHTTP: boolean = false)
async send(url: string, taggedBEEF: TaggedBEEF): Promise<STEAK>
}
```
See also: [OverlayBroadcastFacilitator](./overlay-tools.md#interface-overlaybroadcastfacilitator), [STEAK](./overlay-tools.md#type-steak), [TaggedBEEF](./overlay-tools.md#interface-taggedbeef)
Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
### Class: HTTPSOverlayLookupFacilitator
```ts
export class HTTPSOverlayLookupFacilitator implements OverlayLookupFacilitator {
fetchClient: typeof fetch;
allowHTTP: boolean;
constructor(httpClient = defaultFetch, allowHTTP: boolean = false)
async lookup(url: string, question: LookupQuestion, timeout: number = 5000): Promise<LookupAnswer>
}
```
See also: [LookupAnswer](./overlay-tools.md#type-lookupanswer), [LookupQuestion](./overlay-tools.md#interface-lookupquestion), [OverlayLookupFacilitator](./overlay-tools.md#interface-overlaylookupfacilitator)
Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
### Class: HostReputationTracker
```ts
export class HostReputationTracker {
constructor(store?: KeyValueStore)
reset(): void
recordSuccess(host: string, latencyMs: number): void
recordFailure(host: string, reason?: unknown): void
rankHosts(hosts: string[], now: number = Date.now()): RankedHost[]
snapshot(host: string): HostReputationEntry | undefined
}
```
See also: [RankedHost](./overlay-tools.md#interface-rankedhost)
Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
### Class: LookupResolver
Represents a Lookup Resolver.
```ts
export default class LookupResolver {
constructor(config: LookupResolverConfig = {})
async query(question: LookupQuestion, timeout?: number): Promise<LookupAnswer>
}
```
See also: [LookupAnswer](./overlay-tools.md#type-lookupanswer), [LookupQuestion](./overlay-tools.md#interface-lookupquestion), [LookupResolverConfig](./overlay-tools.md#interface-lookupresolverconfig)
#### Method query
Given a LookupQuestion, returns a LookupAnswer. Aggregates across multiple services and supports resiliency.
```ts
async query(question: LookupQuestion, timeout?: number): Promise<LookupAnswer>
```
See also: [LookupAnswer](./overlay-tools.md#type-lookupanswer), [LookupQuestion](./overlay-tools.md#interface-lookupquestion)
Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
### Class: OverlayAdminTokenTemplate
Script template enabling the creation, unlocking, and decoding of SHIP and SLAP advertisements.
```ts
export default class OverlayAdminTokenTemplate implements ScriptTemplate {
pushDrop: PushDrop;
static decode(script: LockingScript): {
protocol: "SHIP" | "SLAP";
identityKey: string;
domain: string;
topicOrService: string;
}
constructor(wallet: WalletInterface, originator?: OriginatorDomainNameStringUnder250Bytes)
async lock(protocol: "SHIP" | "SLAP", domain: string, topicOrService: string): Promise<LockingScript>
unlock(protocol: "SHIP" | "SLAP"): {
sign: (tx: Transaction, inputIndex: number) => Promise<UnlockingScript>;
estimateLength: (tx: Transaction, inputIndex: number) => Promise<number>;
}
}
```
See also: [LockingScript](./script.md#class-lockingscript), [OriginatorDomainNameStringUnder250Bytes](./wallet.md#type-originatordomainnamestringunder250bytes), [PushDrop](./script.md#class-pushdrop), [ScriptTemplate](./script.md#interface-scripttemplate), [Transaction](./transaction.md#class-transaction), [UnlockingScript](./script.md#class-unlockingscript), [WalletInterface](./wallet.md#interface-walletinterface), [sign](./compat.md#variable-sign)
#### Constructor
Constructs a new Overlay Admin template instance
```ts
constructor(wallet: WalletInterface, originator?: OriginatorDomainNameStringUnder250Bytes)
```
See also: [OriginatorDomainNameStringUnder250Bytes](./wallet.md#type-originatordomainnamestringunder250bytes), [WalletInterface](./wallet.md#interface-walletinterface)
Argument Details
+ **wallet**
+ Wallet to use for locking and unlocking
#### Method decode
Decodes a SHIP or SLAP advertisement from a given locking script.
```ts
static decode(script: LockingScript): {
protocol: "SHIP" | "SLAP";
identityKey: string;
domain: string;
topicOrService: string;
}
```
See also: [LockingScript](./script.md#class-lockingscript)
Returns
Decoded SHIP or SLAP advertisement
Argument Details
+ **script**
+ Locking script comprising a SHIP or SLAP token to decode
#### Method lock
Creates a new advertisement locking script
```ts
async lock(protocol: "SHIP" | "SLAP", domain: string, topicOrService: string): Promise<LockingScript>
```
See also: [LockingScript](./script.md#class-lockingscript)
Returns
Locking script comprising the advertisement token
Argument Details
+ **protocol**
+ SHIP or SLAP
+ **domain**
+ Domain where the topic or service is available
+ **topicOrService**
+ Topic or service to advertise
#### Method unlock
Unlocks an advertisement token as part of a transaction.
```ts
unlock(protocol: "SHIP" | "SLAP"): {
sign: (tx: Transaction, inputIndex: number) => Promise<UnlockingScript>;
estimateLength: (tx: Transaction, inputIndex: number) => Promise<number>;
}
```
See also: [Transaction](./transaction.md#class-transaction), [UnlockingScript](./script.md#class-unlockingscript), [sign](./compat.md#variable-sign)
Returns
Script unlocker capable of unlocking the advertisement token
Argument Details
+ **protocol**
+ SHIP or SLAP, depending on the token to unlock
Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
### Class: TopicBroadcaster
Broadcasts transactions to one or more overlay topics.
```ts
export default class TopicBroadcaster implements Broadcaster {
constructor(topics: string[], config: SHIPBroadcasterConfig = {})
async broadcast(tx: Transaction): Promise<BroadcastResponse | BroadcastFailure>
}
```
See also: [BroadcastFailure](./transaction.md#interface-broadcastfailure), [BroadcastResponse](./transaction.md#interface-broadcastresponse), [Broadcaster](./transaction.md#interface-broadcaster), [SHIPBroadcasterConfig](./overlay-tools.md#interface-shipbroadcasterconfig), [Transaction](./transaction.md#class-transaction)
#### Constructor
Constructs an instance of the SHIP broadcaster.
```ts
constructor(topics: string[], config: SHIPBroadcasterConfig = {})
```
See also: [SHIPBroadcasterConfig](./overlay-tools.md#interface-shipbroadcasterconfig)
Argument Details
+ **topics**
+ The list of SHIP topic names where transactions are to be sent.
+ **config**
+ Configuration options for the SHIP broadcaster.
#### Method broadcast
Broadcasts a transaction to Overlay Services via SHIP.
```ts
async broadcast(tx: Transaction): Promise<BroadcastResponse | BroadcastFailure>
```
See also: [BroadcastFailure](./transaction.md#interface-broadcastfailure), [BroadcastResponse](./transaction.md#interface-broadcastresponse), [Transaction](./transaction.md#class-transaction)
Returns
A promise that resolves to either a success or failure response.
Argument Details
+ **tx**
+ The transaction to be sent.
Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
## Functions
### Function: withDoubleSpendRetry
Executes an operation with automatic retry logic for double-spend errors.
When a double-spend is detected, broadcasts the competing transaction to
update the overlay with missing state, then retries the operation.
```ts
export async function withDoubleSpendRetry<T>(operation: () => Promise<T>, broadcaster: TopicBroadcaster, maxRetries: number = MAX_DOUBLE_SPEND_RETRIES): Promise<T>
```
See also: [TopicBroadcaster](./overlay-tools.md#class-topicbroadcaster)
Returns
The result of the successful operation
Argument Details
+ **operation**
+ The async operation to execute (e.g., createAction + signAction)
+ **broadcaster**
+ The TopicBroadcaster to use for syncing missing state
+ **maxRetries**
+ Maximum number of retry attempts (default: MAX_DOUBLE_SPEND_RETRIES)
Throws
If max retries exceeded or non-double-spend error occurs
Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
## Types
| |
| --- |
| [LookupAnswer](#type-lookupanswer) |
| [STEAK](#type-steak) |
Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
### Type: LookupAnswer
How the Overlay Services Engine responds to a Lookup Question.
It may comprise either an output list or a freeform response from the Lookup Service.
```ts
export type LookupAnswer = {
type: "output-list";
outputs: Array<{
beef: number[];
outputIndex: number;
context?: number[];
}>;
}
```
Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
### Type: STEAK
Submitted Transaction Execution AcKnowledgment
```ts
export type STEAK = Record<string, AdmittanceInstructions>
```
See also: [AdmittanceInstructions](./overlay-tools.md#interface-admittanceinstructions)
Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
## Enums
## Variables
| |
| --- |
| [DEFAULT_SLAP_TRACKERS](#variable-default_slap_trackers) |
| [DEFAULT_TESTNET_SLAP_TRACKERS](#variable-default_testnet_slap_trackers) |
| [getOverlayHostReputationTracker](#variable-getoverlayhostreputationtracker) |
Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
### Variable: DEFAULT_SLAP_TRACKERS
```ts
DEFAULT_SLAP_TRACKERS: string[] = [
"https://overlay-us-1.bsvb.tech",
"https://overlay-eu-1.bsvb.tech",
"https://overlay-ap-1.bsvb.tech",
"https://users.bapp.dev"
]
```
Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
### Variable: DEFAULT_TESTNET_SLAP_TRACKERS
```ts
DEFAULT_TESTNET_SLAP_TRACKERS: string[] = [
"https://testnet-users.bapp.dev"
]
```
Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
### Variable: getOverlayHostReputationTracker
```ts
getOverlayHostReputationTracker = (): HostReputationTracker => globalTracker
```
See also: [HostReputationTracker](./overlay-tools.md#class-hostreputationtracker)
Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)