@@ -384,7 +401,7 @@ instead, it's returned from `connection.getBlock()`
# class *Contract*
-Base class representing a particular instance of a smart contract.
+Represents a particular instance of a smart contract.
Subclass this to add custom query and transaction methods corresponding
to the contract's API.
diff --git a/packages/agent/chain.ts b/packages/agent/chain.ts
index 7e4eb07199..75f3aa4924 100644
--- a/packages/agent/chain.ts
+++ b/packages/agent/chain.ts
@@ -40,10 +40,10 @@ export type Message = string|Record
/** A transaction hash, uniquely identifying an executed transaction on a chain. */
export type TxHash = string
-/** Base class representing a remote API endpoint.
+/** Represents a remote API endpoint.
*
* You shouldn't need to instantiate this class directly.
- * Instead, see `Connection` and its subclasses. */
+ * Instead, see [`Connection`](#abstract-class-connection) and its subclasses. */
export abstract class Endpoint extends Logged {
/** Chain ID. This is a string that uniquely identifies a chain.
* A project's mainnet and testnet have different chain IDs. */
@@ -86,9 +86,8 @@ export abstract class Endpoint extends Logged {
}
}
-/** Base class representing any connection backend, such as:
+/** Provides control over the service backing an [`Endpoint`](#abstract-class-endpoint), such as:
*
- * * Remote RPC endpoint.
* * Local devnet RPC endpoint.
* * Stub/mock implementation of chain.
*
@@ -111,10 +110,10 @@ export abstract class Backend extends Logged {
abstract getIdentity (name: string): Promise<{ address?: Address, mnemonic?: string }>
}
-/** Base class representing a connection to a blockchain via a given endpoint.
- *
- * Use one of its subclasses in `@fadroma/scrt`, `@fadroma/cw`, `@fadroma/namada`
- * to connect to the corresponding chain. Or, extend this class to implement
+/** Represents a connection to a blockchain via a given endpoint.
+ * * Use one of its subclasses in `@fadroma/scrt`, `@fadroma/cw`, `@fadroma/namada`
+ * to connect to the corresponding chain.
+ * * Or, extend this class to implement
* support for new kinds of blockchains. */
export abstract class Connection extends Endpoint {
/** Native token of chain. */
@@ -212,11 +211,29 @@ export abstract class Connection extends Endpoint {
/** Get info about a specific block.
* If no height is passed, gets info about the latest block. */
- fetchBlock (height?: number): Promise {
- this.log.debug(height ? `Querying block ${height}` : `Querying latest block`)
- return this.fetchBlockInfoImpl(height) as Promise
+ fetchBlock (): Promise
+ fetchBlock ({ height }: { height: number }): Promise
+ fetchBlock ({ hash }: { hash: string }): Promise
+ fetchBlock (...args: unknown[]): Promise {
+ if (args[0]) {
+ if (typeof args[0] === 'object') {
+ if ('height' in args[0]) {
+ this.log.debug(`Querying block by height ${args[0].height}`)
+ return this.fetchBlockImpl({ height: args[0].height as number })
+ } else if ('hash' in args[0]) {
+ this.log.debug(`Querying block by hash ${args[0].hash}`)
+ return this.fetchBlockImpl({ hash: args[0].hash as string })
+ }
+ } else {
+ throw new Error('Invalid arguments, pass {height:number} or {hash:string}')
+ }
+ } else {
+ this.log.debug(`Querying latest block`)
+ return this.fetchBlockImpl()
+ }
}
- protected abstract fetchBlockInfoImpl (height?: number): Promise
+ protected abstract fetchBlockImpl (options?: { height: number }|{ hash: string }):
+ Promise
/////////////////////////////////////////////////////////////////////////////////////////////////
@@ -665,8 +682,17 @@ export abstract class Agent extends Logged {
* Each block contains collection of transactions that are
* appended to the blockchain at a given point in time.
*
- * You shouldn't have to instantiate this directly;
- * instead, it's returned from `connection.getBlock()` */
+ * ```
+ * // Fetching the latest block:
+ * const block = await connection.fetchBlock()
+ *
+ * // Fetching a specific block by height:
+ * const block = await connection.fetchBlock({ height: 1234 })
+ *
+ * // Fetching a specific block by hash:
+ * const block = await connection.fetchBlock({ hash: "..." })
+ * ```
+ * */
export abstract class Block {
/** Connection to the chain to which this block belongs. */
chain?: Connection
@@ -689,7 +715,7 @@ export abstract class Block {
}
}
-/** Base class representing a particular instance of a smart contract.
+/** Represents a particular instance of a smart contract.
*
* Subclass this to add custom query and transaction methods corresponding
* to the contract's API. */
diff --git a/packages/agent/stub.md b/packages/agent/stub.md
index 58766a55c1..e1e7147a6a 100644
--- a/packages/agent/stub.md
+++ b/packages/agent/stub.md
@@ -6,8 +6,16 @@ The building block of a blockchain.
Each block contains collection of transactions that are
appended to the blockchain at a given point in time.
-You shouldn't have to instantiate this directly;
-instead, it's returned from `connection.getBlock()`
+```
+// Fetching the latest block:
+const block = await connection.fetchBlock()
+
+// Fetching a specific block by height:
+const block = await connection.fetchBlock({ height: 1234 })
+
+// Fetching a specific block by hash:
+const block = await connection.fetchBlock({ hash: "..." })
+```
const stubBlock = new StubBlock(properties: Partial<Block>)
@@ -45,10 +53,10 @@ instead, it's returned from `connection.getBlock()`
# class *StubConnection*
-Base class representing a connection to a blockchain via a given endpoint.
-
-Use one of its subclasses in `@fadroma/scrt`, `@fadroma/cw`, `@fadroma/namada`
-to connect to the corresponding chain. Or, extend this class to implement
+Represents a connection to a blockchain via a given endpoint.
+* Use one of its subclasses in `@fadroma/scrt`, `@fadroma/cw`, `@fadroma/namada`
+to connect to the corresponding chain.
+* Or, extend this class to implement
support for new kinds of blockchains.
@@ -157,7 +165,17 @@ Fetch balance of 1 or many addresses in 1 or many native tokens.
Get info about a specific block.
If no height is passed, gets info about the latest block.
-const result: Block = await stubConnection.fetchBlock(height: number)
+const result: Block = await stubConnection.fetchBlock()
+
+
+const result: Block = await stubConnection.fetchBlock({
+ height,
+})
+
+
+const result: Block = await stubConnection.fetchBlock({
+ hash,
+})
## method [*stubConnection.fetchCodeInfo*](https://github.com/hackbg/fadroma/tree/v2/packages/agent/chain.ts)
@@ -343,9 +361,8 @@ stubAgent.upload(
# class *StubBackend*
-Base class representing any connection backend, such as:
+Provides control over the service backing an [`Endpoint`](#abstract-class-endpoint), such as:
- * Remote RPC endpoint.
* Local devnet RPC endpoint.
* Stub/mock implementation of chain.
diff --git a/packages/agent/stub.ts b/packages/agent/stub.ts
index bbbf6ff61c..d025108db9 100644
--- a/packages/agent/stub.ts
+++ b/packages/agent/stub.ts
@@ -37,9 +37,9 @@ export class StubConnection extends Connection {
return new StubBatch({ connection: this }) as unknown as Batch
}
protected fetchHeightImpl () {
- return this.fetchBlockInfoImpl().then(({height})=>height)
+ return this.fetchBlockImpl().then(({height})=>height)
}
- protected fetchBlockInfoImpl () {
+ protected fetchBlockImpl () {
return Promise.resolve(new StubBlock({ height: + new Date() }))
}
protected fetchCodesImpl () {
|