diff --git a/docs/quick-start/developers/vote-contract/index.md b/docs/quick-start/developers/vote-contract/index.md index f9201719..f4e9de5a 100644 --- a/docs/quick-start/developers/vote-contract/index.md +++ b/docs/quick-start/developers/vote-contract/index.md @@ -21,13 +21,13 @@ import TabItem from '@theme/TabItem'; -* Basic knowledge of terminal commands -* **IDE** - Install [VS Code](https://code.visualstudio.com/) +- Basic knowledge of terminal commands +- **IDE** - Install [VS Code](https://code.visualstudio.com/) **Install Required Packages** -* [Install dotnet 6.0 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/6.0) -* Install aelf contract templates +- [Install dotnet 6.0 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/6.0) +- Install aelf contract templates ```bash title="Terminal" dotnet new --install AElf.ContractTemplates @@ -35,7 +35,7 @@ dotnet new --install AElf.ContractTemplates AELF.ContractTemplates contains various predefined templates for the ease of developing smart contracts on the aelf blockchain. -* Install aelf deploy tool +- Install aelf deploy tool ```bash title="Terminal" dotnet tool install --global aelf.deploy @@ -70,7 +70,7 @@ Provide required permissions while installing aelf-command globally. **Install Git** -* [Install Git](https://git-scm.com/downloads) +- [Install Git](https://git-scm.com/downloads) As we will be using a ready made project, we will require git to clone from the project. @@ -94,15 +94,15 @@ As we will be using a ready made project, we will require git to clone from the ### Project Setup -* Open your `Terminal`. -* Enter the following command to create a new project folder: +- Open your `Terminal`. +- Enter the following command to create a new project folder: ```bash title="Terminal" mkdir capstone_aelf cd capstone_aelf ``` -* Enter this command to create the capstone project. +- Enter this command to create the capstone project. ```bash title="Terminal" dotnet new aelf -n BuildersDAO @@ -110,21 +110,22 @@ dotnet new aelf -n BuildersDAO ### Adding Your Smart Contract Code -* Open your project in your favorite IDE (like VSCode). -* Rename the `src/Protobuf/contract/hello_world_contract.proto` file to `BuildersDAO.proto`. -* After renaming the file, your working directory should look like this. +- Open your project in your favorite IDE (like VSCode). +- Rename the `src/Protobuf/contract/hello_world_contract.proto` file to `BuildersDAO.proto`. +- After renaming the file, your working directory should look like this. ![img](/img/vote-be-project-dir.png) -* That's it! Your project is now set up and ready to go 🚀 + +- That's it! Your project is now set up and ready to go 🚀 ### Defining Methods and Messages Let's add the RPC methods and message definitions to our Voting dApp. -* Open `src/Protobuf/contract/BuildersDAO.proto` -* Replace its contents with this code snippet. +- Open `src/Protobuf/contract/BuildersDAO.proto` +- Replace its contents with this code snippet. -```csharp title="BuildersDAO.proto" +```csharp title="src/Protobuf/contract/BuildersDAO.proto" syntax = "proto3"; import "aelf/core.proto"; @@ -144,17 +145,17 @@ service BuildersDAO { // Actions -> Methods that change state of smart contract // This method sets up the initial state of our StackUpDAO smart contract rpc Initialize(google.protobuf.Empty) returns (google.protobuf.Empty); - + // This method allows a user to become a member of the DAO by taking in their // address as an input parameter rpc JoinDAO(aelf.Address) returns (google.protobuf.Empty); - + // This method allows a user to create a proposal for other users to vote on. // The method takes in a "CreateProposalInput" message which comprises of an // address, a title, description and a vote threshold (i.e how many votes // required for the proposal to pass) rpc CreateProposal(CreateProposalInput) returns (Proposal); - + // This method allows a user to vote on proposals towards a specific proposal. // This method takes in a "VoteInput" message which takes in the address of // the voter, specific proposal and a boolean which represents their vote @@ -166,8 +167,8 @@ service BuildersDAO { rpc GetAllProposals(google.protobuf.Empty) returns (ProposalList) { option (aelf.is_view) = true; } - - // aelf requires explicit getter methods to access the state value, + + // aelf requires explicit getter methods to access the state value, // so we provide these three getter methods for accessing the state // This method allows a user to fetch a proposal by proposalId rpc GetProposal (google.protobuf.StringValue) returns (Proposal) { @@ -226,38 +227,38 @@ message ProposalList { ##### 1. **Define Syntax & Imports** -* `proto3` version. -* Import necessary Protobuf definitions and libraries. +- `proto3` version. +- Import necessary Protobuf definitions and libraries. ##### 2. **RPC Methods** -* `Initialize` : Set up initial state -* `JoinDAO` : User joins DAO. User's `address` is the function parameter. -* `CreateProposal` : User creates a proposal. User's `address` , `title` , `description` , `vote threshold` are the function parameter. -* `VoteOnProposal` : User votes on a proposal. User's `address` , `proposal` `vote` is the function parameter. -* `GetAllProposals` : Fetch list of proposals +- `Initialize` : Set up initial state +- `JoinDAO` : User joins DAO. User's `address` is the function parameter. +- `CreateProposal` : User creates a proposal. User's `address` , `title` , `description` , `vote threshold` are the function parameter. +- `VoteOnProposal` : User votes on a proposal. User's `address` , `proposal` `vote` is the function parameter. +- `GetAllProposals` : Fetch list of proposals ##### 3. **Getter Methods** -* `GetProposal` : Fetch proposal by ID -* `GetMemberCount` : Fetch member count -* `GetMemberExist` : Check if a member exists by address +- `GetProposal` : Fetch proposal by ID +- `GetMemberCount` : Fetch member count +- `GetMemberExist` : Check if a member exists by address ##### 4. **Message Definitions** -* `Member` : DAO member (address) -* `Proposal` : Proposal (title, description, votes, status, vote threshold) -* `CreateProposalInput` : Fields for creating a proposal (title, description, vote threshold) -* `VoteInput` : Fields for voting on a proposal (proposal ID, vote) -* `MemberList` : List of DAO members -* `ProposalList` : List of proposals +- `Member` : DAO member (address) +- `Proposal` : Proposal (title, description, votes, status, vote threshold) +- `CreateProposalInput` : Fields for creating a proposal (title, description, vote threshold) +- `VoteInput` : Fields for voting on a proposal (proposal ID, vote) +- `MemberList` : List of DAO members +- `ProposalList` : List of proposals ### Defining Contract State -* Open the `src/BuildersDAOState.cs` file. -* Replace its contents with this code snippet. +- Open the `src/BuildersDAOState.cs` file. +- Replace its contents with this code snippet. -```csharp title="BuildersDAOState.proto" +```csharp title="src/BuildersDAOState.cs" using System.Collections.Generic; using System.Diagnostics.CodeAnalysis; using AElf.Sdk.CSharp.State; @@ -281,22 +282,22 @@ namespace AElf.Contracts.BuildersDAO ##### 3. **State Variables** -* `Members` : Mapping each member to a boolean indicates if they joined the DAO -* `Proposals` : Mapping each proposal to an ID for identification and retrieval -* `MemberCountId` and `NextProposalId` : Track total number of members and proposals +- `Members` : Mapping each member to a boolean indicates if they joined the DAO +- `Proposals` : Mapping each proposal to an ID for identification and retrieval +- `MemberCountId` and `NextProposalId` : Track total number of members and proposals #### Next Step -* Implement the logic of our voting smart contract. +- Implement the logic of our voting smart contract. ### Implement Voting Smart Contract Logic #### Checking Smart Contract Logics -* Open `src/BuildersDAO.cs` -* Replace the existing content with this code snippet. +- Open `src/BuildersDAO.cs` +- Replace the existing content with this code snippet. -```csharp title="BuildersDAO.proto" +```csharp title="src/BuildersDAO.cs" using System.Collections.Generic; using System.Security.Principal; using AElf.Sdk.CSharp; @@ -324,13 +325,13 @@ namespace AElf.Contracts.BuildersDAO // Implement Get All Proposals Logic public override ProposalList GetAllProposals(Empty input) { } - + // Implement Get Proposal Logic public override Proposal GetProposal(StringValue input) { } - + // Implement Get Member Count Logic public override Int32Value GetMemberCount(Empty input) { } - + // Implement Get Member Exist Logic public override BoolValue GetMemberExist(Address input) { } } @@ -343,12 +344,12 @@ Aelf sidechain does not allow duplicate identical smart contracts. Hence, we wil #### Implementing Initialize Function -* Go to the comment `Implement Vote on Proposal Logic`. -* Check if the smart contract is already initialized; return if true. -* Define a hardcoded proposal with necessary parameters. -* Update the Proposals state variable with the hardcoded proposal and increment the proposalId. +- Go to the comment `Implement Vote on Proposal Logic`. +- Check if the smart contract is already initialized; return if true. +- Define a hardcoded proposal with necessary parameters. +- Update the Proposals state variable with the hardcoded proposal and increment the proposalId. -```csharp title="BuildersDAO.proto" +```csharp title="src/BuildersDAO.cs" // Implement Initialize Smart Contract Logic public override Empty Initialize(Empty input) { @@ -364,23 +365,23 @@ public override Empty Initialize(Empty input) State.Proposals[initialProposal.Id] = initialProposal; State.NextProposalId.Value = 1; State.MemberCount.Value = 0; - + State.Initialized.Value = true; - + return new Empty(); } ``` #### Implementing Join DAO Function -* Go to the comment `Implement Join DAO Logic` -* Check if the member already exists in the DAO using the `Members` state variable. -* If not found, update `Members` to include the user's address. -* Increment `membersCount` to reflect the new member added. +- Go to the comment `Implement Join DAO Logic` +- Check if the member already exists in the DAO using the `Members` state variable. +- If not found, update `Members` to include the user's address. +- Increment `membersCount` to reflect the new member added. You'll implement this function. Once done, you can proceed to the next page to compare your code with the reference implementation. -```csharp title="BuildersDAO.proto" +```csharp title="src/BuildersDAO.cs" // Implement Join DAO Logic public override Empty JoinDAO(Address input) { @@ -394,14 +395,14 @@ public override Empty JoinDAO(Address input) #### Implementing Create Proposal Function -* Go to the comment `Implement Create Proposal Logic` -* Check if the user is a DAO member (required to create proposals). -* Create a new proposal object using fields from `CreateProposalInput`. -* `Update` Proposals with the new proposal, increment NextProposalId, and return the created proposal object. +- Go to the comment `Implement Create Proposal Logic` +- Check if the user is a DAO member (required to create proposals). +- Create a new proposal object using fields from `CreateProposalInput`. +- `Update` Proposals with the new proposal, increment NextProposalId, and return the created proposal object. Now, use the provided code snippet to fill in the `CreateProposal` function. -```csharp title="BuildersDAO.proto" +```csharp title="src/BuildersDAO.cs" // Implement Create Proposal Logic public override Proposal CreateProposal(CreateProposalInput input) { @@ -425,21 +426,22 @@ public override Proposal CreateProposal(CreateProposalInput input) #### Implementing Vote On Proposal Function -* Go to the comment `Implement Vote on Logic` -* Perform these checks: +- Go to the comment `Implement Vote on Logic` +- Perform these checks: - * Verify if the member is a DAO member (required to vote). - * Confirm if the proposal exists; otherwise, display an error message. - * Check if the member has already voted on the proposal; members can vote only once. -* If all checks pass, store the member’s vote and update the proposal state. -* Update the proposal status based on vote thresholds: + - Verify if the member is a DAO member (required to vote). + - Confirm if the proposal exists; otherwise, display an error message. + - Check if the member has already voted on the proposal; members can vote only once. - * If `yesVotes` reach the threshold, update status to "PASSED". - * If `noVotes` reach the threshold, update status to "DENIED". +- If all checks pass, store the member’s vote and update the proposal state. +- Update the proposal status based on vote thresholds: + + - If `yesVotes` reach the threshold, update status to "PASSED". + - If `noVotes` reach the threshold, update status to "DENIED". Now, use the provided code snippet to complete the `VoteOnProposal` function. -```csharp title="BuildersDAO.proto" +```csharp title="src/BuildersDAO.cs" // Implement Vote on Proposal Logic public override Proposal VoteOnProposal(VoteInput input) { @@ -480,17 +482,17 @@ public override Proposal VoteOnProposal(VoteInput input) #### Implementing Get All Proposals Function -* Go to the comment `Implement Get All Proposals Logic` -* Create a new `ProposalList` object from the message definition in `BuildersDAO.proto`. -* Fetch and iterate through `Proposals`. -* Update `ProposalList` with proposal objects and return the list of proposals. +- Go to the comment `Implement Get All Proposals Logic` +- Create a new `ProposalList` object from the message definition in `BuildersDAO.proto`. +- Fetch and iterate through `Proposals`. +- Update `ProposalList` with proposal objects and return the list of proposals. - * If `yesVotes` reach the threshold, update status to "PASSED". - * If `noVotes` reach the threshold, update status to "DENIED". + - If `yesVotes` reach the threshold, update status to "PASSED". + - If `noVotes` reach the threshold, update status to "DENIED". You'll implement this function. Once done, you can proceed to the next page to compare your code with the reference implementation. -```csharp title="BuildersDAO.proto" +```csharp title="src/BuildersDAO.cs" // Implement Get All Proposals Logic public override ProposalList GetAllProposals(Empty input) { @@ -505,27 +507,27 @@ public override ProposalList GetAllProposals(Empty input) ##### 1. Get Proposal -* Navigate to `Implement Get Proposal Logic`. -* Retrieve a proposal by `proposalId`. -* Use `proposalId` as the key to query `State.Proposals`. -* Return the corresponding proposal value. +- Navigate to `Implement Get Proposal Logic`. +- Retrieve a proposal by `proposalId`. +- Use `proposalId` as the key to query `State.Proposals`. +- Return the corresponding proposal value. ##### 2. Get Member Count -* Navigate to `Implement Get Member Count Logic`. -* Retrieve the total member count. -* Return the value of `MemberCount` from `State`. +- Navigate to `Implement Get Member Count Logic`. +- Retrieve the total member count. +- Return the value of `MemberCount` from `State`. ##### 3. Get Member Exist -* Navigate to `Implement Get Member Exist Logic`. -* Check if a member exists by `address`. -* Use `address` as the key to query `State.Members`. -* Return the corresponding existence value. +- Navigate to `Implement Get Member Exist Logic`. +- Check if a member exists by `address`. +- Use `address` as the key to query `State.Members`. +- Return the corresponding existence value. Implement these methods to access different states effectively in your smart contract. -```csharp title="BuildersDAO.proto" +```csharp title="src/BuildersDAO.cs" // Implement Get Proposal Logic public override Proposal GetProposal(StringValue input) { @@ -574,7 +576,7 @@ This process ensures thorough testing and readiness for deployment of our smart - \*\*Positive Cases:\*\* - - Call \`Initialize\` once and verify the proposal title using \`GetProposal\` with \`proposalId = "0"\`. + - Call \`Initialize\` once and verify the proposal title using \`GetProposal\` with \`proposalId = "0"\`. - Check if the title is "Proposal #1" using \`ShouldBe\` method. \`\`\`csharp @@ -606,11 +608,11 @@ public async Task InitializeTest_Duplicate() #### Implementing Join DAO Function -* **Check Membership** : See if the address has already joined the DAO by checking State.Members. Use the Assert method for this verification. -* **Add New Member** : If the address isn't a member yet, add it to State.Members and set its value to true. -* **Update Member Count** : Increase State.MemberCount by 1 and save the new value. +- **Check Membership** : See if the address has already joined the DAO by checking State.Members. Use the Assert method for this verification. +- **Add New Member** : If the address isn't a member yet, add it to State.Members and set its value to true. +- **Update Member Count** : Increase State.MemberCount by 1 and save the new value. -```csharp title="BuildersDAO.proto" +```csharp title="src/BuildersDAO.cs" public override Empty JoinDAO(Address input) { // Based on the address, determine whether the address has joined the DAO. If it has, throw an exception @@ -626,12 +628,12 @@ public override Empty JoinDAO(Address input) #### Implementing Get All Proposals Function -* Create a list object called `ProposalList`. -* Loop from 0 to the value of `State.NextProposalId`. -* In each loop iteration, get the values from `State.Proposals` and add them to `ProposalList`. -* Return `ProposalList`. +- Create a list object called `ProposalList`. +- Loop from 0 to the value of `State.NextProposalId`. +- In each loop iteration, get the values from `State.Proposals` and add them to `ProposalList`. +- Return `ProposalList`. -```csharp title="BuildersDAO.proto" +```csharp title="src/BuildersDAO.cs" public override ProposalList GetAllProposals(Empty input) { // Create a new list called ProposalList @@ -651,7 +653,7 @@ Once you've implemented these two methods and run the unit tests again, you shou ## Step 3 - Deploy Smart Contract -import Deploy from "../_deploy.md" +import Deploy from "../\_deploy.md" @@ -659,7 +661,7 @@ import Deploy from "../_deploy.md" ### Project Setup -Let's start by cloning the frontend project repository from GitHub. +Let's start by cloning the frontend project repository from GitHub. - Run the following command in the `capstone_aelf` directory: @@ -675,7 +677,7 @@ cd `vote-contract`-frontend - Once you're in the `vote-contract-frontend` directory, open the project with your preferred IDE (e.g., VSCode). You should see the project structure as shown below. - ![result](/img/vote-fe-directory.png) + ![result](/img/vote-fe-directory.png) #### Install necessary libraries @@ -687,7 +689,6 @@ npm install We are now ready to build the frontend components of our Voting dApp. - ### Configure Portkey Provider & Write Connect Wallet Function We'll set up our Portkey provider to let users connect their Portkey wallets to our app and interact with our voting smart contract. @@ -757,7 +758,6 @@ In this code, we fetch the Portkey wallet account using the provider and update With the Connect Wallet function defined, we're ready to write the remaining functions in the next steps. - ### Write Initialize Smart Contract & Join DAO Functions Let's write the Initialize and Join DAO functions. @@ -766,7 +766,6 @@ Let's write the Initialize and Join DAO functions. 2. Replace the existing `initializeAndJoinDAO` function with this code snippet: - ```javascript title="src/HomeDAO.ts" const initializeAndJoinDAO = async () => { //Step C - Write Initialize Smart Contract and Join DAO Logic @@ -804,11 +803,10 @@ const initializeAndJoinDAO = async () => { Now, wrap the `initializeAndJoinDAO` function in the "Join DAO" button to trigger both Initialize and JoinDAO when clicked. - ![jao-button](/img/fe-join-dao-button.png) +![jao-button](/img/fe-join-dao-button.png) Next, we'll write the **Create Proposal** function. - ### Write Create Proposal Function Let's write the Create Proposal function. @@ -821,15 +819,19 @@ Let's write the Create Proposal function. ```javascript title="src/CreateProposal.tsx" //Step D - Configure Proposal Form -const form = useForm>({ - resolver: zodResolver(formSchema), - defaultValues: { - address: currentWalletAddress, - title: "", - description: "", - voteThreshold: 0, - }, -}); +const form = + useForm < + z.infer < + typeof formSchema >> + { + resolver: zodResolver(formSchema), + defaultValues: { + address: currentWalletAddress, + title: "", + description: "", + voteThreshold: 0, + }, + }; ``` :::tip @@ -847,7 +849,6 @@ Default value: Now your form is ready for users to fill in the necessary details for their proposal. - Now, let's write the Create Proposal function for the form submission. 1. Scroll down to find the comment `Step E - Write Create Proposal Logic`. @@ -893,8 +894,6 @@ function onSubmit(values: z.infer) { Next, we'll write the **Vote** and **Fetch Proposal** functions to complete the frontend components of our Voting dApp. - - ### Write Vote & Fetch Proposals Function In this step, we'll write the Vote and Fetch Proposals functions to complete our Voting dApp's frontend components. @@ -950,7 +949,6 @@ const voteYes = async (index: number) => { The `voteNo` function works similarly but sets the vote to `false`. - - Scroll down to the `Step G - Use Effect to Fetch Proposals` comment and replace the `useEffect` hook with this code snippet: ```javascript title="src/HomeDAO.tsx" @@ -968,10 +966,10 @@ useEffect(() => { if (!account) throw new Error("No account"); - const proposalResponse = await DAOContract?.callViewMethod( - "GetAllProposals", - "" - ); + const proposalResponse = + (await DAOContract?.callViewMethod) < + IProposals > + ("GetAllProposals", ""); setProposals(proposalResponse?.data); alert("Fetched Proposals"); @@ -994,7 +992,6 @@ useEffect(() => { Now that we've written all the necessary frontend functions and components, we're ready to run the Voting dApp application in the next step. - ### Run Application In this step, we will run the Voting dApp application. @@ -1013,7 +1010,7 @@ npm run dev - You should observe the following as shown below. - ![run-app-success](/img/vote-npm-run-console.png) + ![run-app-success](/img/vote-npm-run-console.png) - Upon clicking on the **localhost URL**, you should be directed to the StackUpDAO landing page as shown below. @@ -1023,12 +1020,11 @@ If you are developing and testing this with GitHub codespace, you can use Port F - Usually codespace will automatically forward port, you should see a pop-up message at the bottom right of your codespace browser window as shown in the diagram below: - ![open-in-browser](/img/codespace-forwarded-port.png) + ![open-in-browser](/img/codespace-forwarded-port.png) - Click the link to open the Voting dApp in the browser. - ![vote-fe-ui](/img/vote-fe-ui-1.png) - + ![vote-fe-ui](/img/vote-fe-ui-1.png) #### Create Portkey Wallet @@ -1044,7 +1040,6 @@ With DID solution as its core, Portkey provides both Portkey Wallet and Portkey For more information, you may visit the official documentation for Portkey at https://doc.portkey.finance/. ::: - - Download the Chrome extension for Portkey from https://chromewebstore.google.com/detail/portkey-wallet/iglbgmakmggfkoidiagnhknlndljlolb. :::info @@ -1054,18 +1049,17 @@ You may download Chrome from https://www.google.com/intl/en_sg/chrome/. - Once you have downloaded the extension, you should see the following on your browser as shown below. - ![welcome-to-portkey](/img/welcome-to-portkey.png) + ![welcome-to-portkey](/img/welcome-to-portkey.png) - Click on `Get Start` and you should see the following interface as shown below. - ![portkey-login](/img/portkey-login.png) + ![portkey-login](/img/portkey-login.png) - -**Sign up** +**Sign up** - Switch to **aelf Testnet** network by selecting it: - ![portkey-switch-to-testnet](/img/portkey-switch-to-testnet.png) + ![portkey-switch-to-testnet](/img/portkey-switch-to-testnet.png) :::danger Please make sure you are using `aelf Testnet` in order to be able to receive your testnet tokens from the Faucet. @@ -1073,7 +1067,7 @@ Please make sure you are using `aelf Testnet` in order to be able to receive you - Proceed to sign up with a Google Account or your preferred login method and complete the necessary accounts creation prompts and you should observe the following interface once you have signed up. - ![success-login](/img/success-login.png) + ![success-login](/img/success-login.png) With that, you have successfully created your very first Portkey wallet within seconds. How easy was that? @@ -1083,8 +1077,7 @@ It is highly recommended to pin the Portkey wallet extension for easier access a - Next, click on ‘Open Portkey’ and you should now observe the following as shown below. - ![portkey-wallet-preview](/img/portkey-wallet-preview.png) - + ![portkey-wallet-preview](/img/portkey-wallet-preview.png) **Connect Portkey Wallet** @@ -1094,7 +1087,7 @@ It is highly recommended to pin the Portkey wallet extension for easier access a Once you have successfully joined the DAO, you should observe now that the landing page renders the proposal we have defined in our smart contract as shown below. - ![vote-fe-ui-joineddao](/img/vote-fe-ui-joineddao.png) +![vote-fe-ui-joineddao](/img/vote-fe-ui-joineddao.png) - Proposal #1 as defined in smart contract @@ -1106,45 +1099,43 @@ Once you have successfully joined the DAO, you should observe now that the landi - Proceed to click on **"Vote Yes"** and you should observe the following as shown below prompting you to sign the **"Vote Yes"** transaction. - ![fe-dapp-trans-sign](/img/fe-dapp-trans-sign.png) + ![fe-dapp-trans-sign](/img/fe-dapp-trans-sign.png) - Proceed to click on **"Sign"**. Upon a successful vote transaction, you should now observe that the proposal status has been updated to **"PASSED"** as shown below as the Yes vote count has reached the vote threshold. - ![vote-fe-ui-proposal-voted](/img/vote-fe-ui-proposal-voted.png) +![vote-fe-ui-proposal-voted](/img/vote-fe-ui-proposal-voted.png) - Proposal status updated to **"PASSED"** Lastly, we will be creating a proposal to wrap up our demonstration of our Voting dApp. - Click on **"Create Proposal"** for Proceed and you should be directed to the Create Proposal page as shown below. - ![fe-dapp-create-proposal](/img/fe-dapp-create-proposal.png) + ![fe-dapp-create-proposal](/img/fe-dapp-create-proposal.png) - Proceed to fill in the following fields under the Create Proposal form: - - - **Title** - Proposal #2 - - **Description** - Proposal to onboard Developer DAO + - **Title** - Proposal #2 - - **Vote Threshold** - 10 + - **Description** - Proposal to onboard Developer DAO + + - **Vote Threshold** - 10 - click on **"Submit"** and you should observe the following as shown below. - ![fe-submit-proposal-verify](/img/fe-submit-proposal-verify.png) + ![fe-submit-proposal-verify](/img/fe-submit-proposal-verify.png) - Click on **"Sign"** to Proceed. - Upon a successful proposal creation, you should be directed back to the landing page with the newly created proposal rendered on the landing page as shown below. - ![vote-fe-ui-new-proposal](/img/vote-fe-ui-new-proposal.png) + ![vote-fe-ui-new-proposal](/img/vote-fe-ui-new-proposal.png) :::success 🎉 Congratulations Learners! You have successfully built your Voting dApp and this is no mean feat! ::: - -## 🎯 Conclusion - +## 🎯 Conclusion 🎊 Congratulations on completing the Voting Contract tutorial! 🎊 You've reached an important milestone in your journey through aelf blockchain development. 🌟 @@ -1173,4 +1164,4 @@ Now that you've mastered the intricacies of voting contracts, it's time to explo Keep pushing the boundaries of blockchain technology with aelf. Your journey doesn't end here – it's just the beginning of even more exciting possibilities in decentralized applications and smart contracts. 🚀 -Happy coding and innovating with aelf! 😊 \ No newline at end of file +Happy coding and innovating with aelf! 😊 diff --git a/docs/resources/contribution/index.md b/docs/resources/contribution/index.md new file mode 100644 index 00000000..eac41673 --- /dev/null +++ b/docs/resources/contribution/index.md @@ -0,0 +1,37 @@ +--- +sidebar_position: 10 +title: Contribution Guide +description: contribution guide +--- + +aelf is an [open source](https://github.com/aelfproject) and community driven project. This guide is aims to help anyone wants to contribute to the project. + +### Code Contribution + +You can always send pull requests to the Github repository. + +- Clone the [aelf repository](https://github.com/aelfproject/aelf/) from Github. +- Make the required changes. +- Send a pull request. + +Before making any change, please discuss it on the [Github issues](https://github.com/aelfproject/aelf/issues). In this way, no other developer will work on the same issue and your PR will have a better chance to be accepted. + +#### Bug Fixes & Enhancements + +You may want to fix a known bug or work on a planned enhancement. See [the issue list](https://github.com/aelfproject/aelf/issues) on Github. + +#### Feature Requests + +If you have a feature idea for the framework or modules, [create an issue](https://github.com/aelfproject/aelf/issues/new) on Github or attend to an existing discussion. Then you can implement it if it's embraced by the community. + +### Blog Posts & Tutorials + +If you decide to create some tutorials or blog posts on aelf, please inform us (by creating a [Github issue](https://github.com/aelfproject/aelf/issues)), so we may add a link to your tutorial/post in the official documentation and we can announce it on our [Twitter account](https://twitter.com/aelfblockchain). + +### Bug Report + +If you find any bug, please [create an issue on the Github repository](https://github.com/aelfproject/aelf/issues/new). + +### Thanks + +Thanks to ABP, we follow their contribute guides diff --git a/docs/tools/chain-sdk/javascript-sdk/index.md b/docs/tools/chain-sdk/javascript-sdk/index.md index 15916244..f9a7e830 100644 --- a/docs/tools/chain-sdk/javascript-sdk/index.md +++ b/docs/tools/chain-sdk/javascript-sdk/index.md @@ -829,7 +829,7 @@ To use aelf SDK, you need: ## About contributing -Read out [contributing guide] +Read out [contributing guide](../../../resources/contribution/index.md) ## About Version diff --git a/docs/tools/chain-sdk/php-sdk/index.md b/docs/tools/chain-sdk/php-sdk/index.md index a9abe54c..8c396da8 100644 --- a/docs/tools/chain-sdk/php-sdk/index.md +++ b/docs/tools/chain-sdk/php-sdk/index.md @@ -8,11 +8,13 @@ image: /img/Logo.aelf.svg # aelf-sdk.php - aelf PHP API ## Introduction + aelf-sdk.php for aelf is similar to web.js for Ethereum. It consists of libraries that enable interaction with a local or remote aelf node via HTTP. This documentation will guide you through the installation and usage of aelf-sdk.php, with examples included. For more information, visit the [aelf-sdk.php repository](https://github.com/AElfProject/aelf-sdk.php). ## Adding aelf PHP SDK + To install the library via Composer, run the following commands in your console: ```sh @@ -33,6 +35,7 @@ If you cloned the SDK directly, you must install Composer and run it in the root ## Examples ### 1. Create an Instance + Create a new instance of AElf and connect to an AELF chain node. Using this instance, you can call the AElf APIs. ```php @@ -44,6 +47,7 @@ $aelf = new AElf($url); ``` ### 2. Get a System Contract Address + Get a system contract address. For example, to get the address of `AElf.ContractNames.Token`: ```php @@ -61,6 +65,7 @@ $contractAddress = $aelf->GetContractAddressByName($privateKey, $bytes); ``` ### 3. Send a Transaction + Get the contract address and then send a transaction. ```php @@ -113,7 +118,6 @@ $url = '127.0.0.1:8000'; $aelf = new AElf($url); ``` - ### 1. Get Chain Status - **API Path**: `/api/blockChain/chainStatus` @@ -122,19 +126,18 @@ $aelf = new AElf($url); - **Returns**: - - `Array` - - `ChainId` - String - - `Branches` - Array - - `NotLinkedBlocks` - Array - - `LongestChainHeight` - Integer - - `LongestChainHash` - String - - `GenesisBlockHash` - String - - `GenesisContractAddress` - String - - `LastIrreversibleBlockHash` - String - - `LastIrreversibleBlockHeight` - Integer - - `BestChainHash` - String - - `BestChainHeight` - Integer - + - `Array` + - `ChainId` - String + - `Branches` - Array + - `NotLinkedBlocks` - Array + - `LongestChainHeight` - Integer + - `LongestChainHash` - String + - `GenesisBlockHash` - String + - `GenesisContractAddress` - String + - `LastIrreversibleBlockHash` - String + - `LastIrreversibleBlockHeight` - Integer + - `BestChainHash` - String + - `BestChainHeight` - Integer - **Example** : @@ -146,8 +149,6 @@ $chainStatus = $aelf->getChainStatus(); print_r($chainStatus); ``` - - ### 2. Get Block Height - **API Path**: `/api/blockChain/blockHeight` @@ -165,34 +166,33 @@ $height = $aelf->getBlockHeight(); print($height); ``` - ### 3. getBlock - **API Path**: `/api/blockChain/block` -- **Parameters**: - - - `block_hash` (String) - - `include_transactions` (Boolean) - -- **Returns**: - - - `Array` - - `BlockHash` - String - - `Header` - Array - - `PreviousBlockHash` - String - - `MerkleTreeRootOfTransactions` - String - - `MerkleTreeRootOfWorldState` - String - - `Extra` - List - - `Height` - Integer - - `Time` - String - - `ChainId` - String - - `Bloom` - String - - `SignerPubkey` - String - - `Body` - Array - - `TransactionsCount` - Integer - - `Transactions` - Array - - `transactionId` - String +- **Parameters**: + + - `block_hash` (String) + - `include_transactions` (Boolean) + +- **Returns**: + + - `Array` + - `BlockHash` - String + - `Header` - Array + - `PreviousBlockHash` - String + - `MerkleTreeRootOfTransactions` - String + - `MerkleTreeRootOfWorldState` - String + - `Extra` - List + - `Height` - Integer + - `Time` - String + - `ChainId` - String + - `Bloom` - String + - `SignerPubkey` - String + - `Body` - Array + - `TransactionsCount` - Integer + - `Transactions` - Array + - `transactionId` - String - **Example** : @@ -204,35 +204,33 @@ $block2 = $aelf->getBlockByHash($block['BlockHash'], false); print_r($block2); ``` - ### 4. Get Block by Height - **API Path**: `/api/blockChain/blockByHeight` -- **Parameters**: - - - `block_height` (Number) - - `include_transactions` (Boolean) +- **Parameters**: -- **Returns**: + - `block_height` (Number) + - `include_transactions` (Boolean) - - `Array` - - `BlockHash` - String - - `Header` - Array - - `PreviousBlockHash` - String - - `MerkleTreeRootOfTransactions` - String - - `MerkleTreeRootOfWorldState` - String - - `Extra` - List - - `Height` - Integer - - `Time` - String - - `ChainId` - String - - `Bloom` - String - - `SignerPubkey` - String - - `Body` - Array - - `TransactionsCount` - Integer - - `Transactions` - Array - - `transactionId` - String +- **Returns**: + - `Array` + - `BlockHash` - String + - `Header` - Array + - `PreviousBlockHash` - String + - `MerkleTreeRootOfTransactions` - String + - `MerkleTreeRootOfWorldState` - String + - `Extra` - List + - `Height` - Integer + - `Time` - String + - `ChainId` - String + - `Bloom` - String + - `SignerPubkey` - String + - `Body` - Array + - `TransactionsCount` - Integer + - `Transactions` - Array + - `transactionId` - String - **Example** : @@ -243,38 +241,37 @@ $block = $aelf->getBlockByHeight(1, true); print_r($block); ``` - ### 5. Get Transaction Result - **API Path**: `/api/blockChain/transactionResult` -- **Parameters**: +- **Parameters**: - - `transactionId` (String) + - `transactionId` (String) - **Returns**: - - `Object` - - `TransactionId` - String - - `Status` - String - - `Logs` - Array - - `Address` - String - - `Name` - String - - `Indexed` - Array - - `NonIndexed` - String - - `Bloom` - String - - `BlockNumber` - Integer - - `Transaction` - Array - - `From` - String - - `To` - String - - `RefBlockNumber` - Integer - - `RefBlockPrefix` - String - - `MethodName` - String - - `Params` - json - - `Signature` - String - - `transactionId` - String - - `ReadableReturnValue` - String - - `Error` - String + - `Object` + - `TransactionId` - String + - `Status` - String + - `Logs` - Array + - `Address` - String + - `Name` - String + - `Indexed` - Array + - `NonIndexed` - String + - `Bloom` - String + - `BlockNumber` - Integer + - `Transaction` - Array + - `From` - String + - `To` - String + - `RefBlockNumber` - Integer + - `RefBlockPrefix` - String + - `MethodName` - String + - `Params` - json + - `Signature` - String + - `transactionId` - String + - `ReadableReturnValue` - String + - `Error` - String - **Example** : @@ -286,21 +283,20 @@ $transactionResult = $aelf->getTransactionResult($block['Body']['Transactions'][ print_r($transactionResult); ``` - ### 6. Get Multiple Transaction Results - **API Path**: `/api/blockChain/transactionResults` -- **Parameters**: +- **Parameters**: - - `blockHash` (String) - - `offset` (Number) - - `limit` (Number) + - `blockHash` (String) + - `offset` (Number) + - `limit` (Number) -- **Returns**: +- **Returns**: - - `List` - The array of method descriptions: - - the transaction result object + - `List` - The array of method descriptions: + - the transaction result object - **Example** : @@ -312,7 +308,6 @@ $transactionResults = $aelf->getTransactionResults($block['Body']); print_r($transactionResults); ``` - ### 7. Get Transaction Pool Status - **API Path**: `/api/blockChain/transactionPoolStatus` @@ -326,16 +321,15 @@ $status = $aelf->getTransactionPoolStatus(); print_r($status); ``` - ### 8. Send Transaction - **API Path**: `/api/blockChain/sendTransaction` - **Method**: POST -- **Parameters**: +- **Parameters**: - - `transaction` (String) + - `transaction` (String) - **Example** : @@ -348,16 +342,15 @@ $result = $aelf->sendTransaction($executeTransactionDtoObj); print_r($result); ``` - ### 9. Send Multiple Transactions - **API Path**: `/api/blockChain/sendTransactions` - **Method**:POST -- **Parameters**: +- **Parameters**: - - `transactions` (String) + - `transactions` (String) - **Example** : @@ -376,7 +369,6 @@ $listString = $aelf->sendTransactions($sendTransactionsInputs); print_r($listString); ``` - ### 10. Get Peers - **API Path**: `/api/net/peers` @@ -387,7 +379,6 @@ print_r($listString); print_r($aelf->getPeers(true)); ``` - ### 11. Add Peer - **API Path**: `/api/net/peer` @@ -396,7 +387,7 @@ print_r($aelf->getPeers(true)); - **Parameters**: - - `peer_address` (String) + - `peer_address` (String) - **Example** : @@ -404,14 +395,13 @@ print_r($aelf->getPeers(true)); $aelf->addPeer($url); ``` - ### 12. Remove Peer - **API Path**: `/api/net/peer` - **Parameters**: - - `peer_address` (String) + - `peer_address` (String) - **Example** : @@ -419,21 +409,20 @@ $aelf->addPeer($url); $aelf->removePeer($url); ``` - ### 13. Create Raw Transaction - **API Path**: `/api/blockchain/rawTransaction` - **Method**: POST -- **Parameters**: +- **Parameters**: - - `transaction` (Array) + - `transaction` (Array) -- **Returns**: +- **Returns**: - - `Array` - - `RawTransaction` - hex string bytes generated by transaction information + - `Array` + - `RawTransaction` - hex string bytes generated by transaction information - **Example** : @@ -455,16 +444,15 @@ $rawTransaction = $aelf->createRawTransaction($transaction); print_r($rawTransaction); ``` - ### 14. Send Raw Transaction - **API Path**: `/api/blockchain/sendRawTransaction` -- **Parameters**: +- **Parameters**: - - `Transaction` (raw transaction) - - `Signature` (signature) - - `ReturnTransaction` (indicates whether to return transaction) + - `Transaction` (raw transaction) + - `Signature` (signature) + - `ReturnTransaction` (indicates whether to return transaction) - **Example** : @@ -479,19 +467,16 @@ $execute = $aelf->sendRawTransaction($transaction); print_r($execute); ``` - - ### 15. Execute Raw Transaction - **API Path**: `/api/blockchain/executeRawTransaction` - **Method**: POST -- **Parameters**: - - - `RawTransaction` (raw transaction) - - `Signature` (signature) +- **Parameters**: + - `RawTransaction` (raw transaction) + - `Signature` (signature) - **Example** : @@ -506,14 +491,13 @@ $execute = $aelf->executeRawTransaction($transaction); print_r($execute); ``` - ### 16. Get Merkle Path by Transaction ID - **API Path**: `/api/blockchain/merklePathByTransactionId` -- **Parameters**: +- **Parameters**: - - `transactionId` (String) + - `transactionId` (String) - **Example** : @@ -525,24 +509,23 @@ $merklePath = $aelf->getMerklePathByTransactionId($block['Body']['Transactions'] print_r($merklePath); ``` - ### 17. Calculate Transaction Fee - **API Path**: `/api/blockChain/calculateTransactionFee` - **Method**: POST -- **Parameters**: +- **Parameters**: - - `CalculateTransactionFeeInput` (Object) + - `CalculateTransactionFeeInput` (Object) -- **Returns**: +- **Returns**: - - `CalculateTransactionFeeOutput (Object)` + - `CalculateTransactionFeeOutput (Object)` - - `Success` - bool - - `TransactionFee` - Array - - `ResourceFee` - Array + - `Success` - bool + - `TransactionFee` - Array + - `ResourceFee` - Array - **Example** : @@ -556,7 +539,6 @@ $result = $aelf->calculateTransactionFee($calculateTransactionFeeInputParam); print_r($result); ``` - ### 18. Get Network Info - **API Path**: `/api/net/networkInfo` @@ -569,7 +551,6 @@ $aelf = new AElf($url); print_r($aelf->getNetworkInfo()); ``` - ### 19. Get Contract File Descriptor Set - **API Path**: `/api/blockchain/contractFileDescriptorSet` @@ -587,7 +568,6 @@ foreach ($transactionResultDtoList as $v) { } ``` - ### 20. Get Task Queue Status - **API Path**: `/api/blockchain/taskQueueStatus` @@ -601,7 +581,6 @@ $taskQueueStatus = $aelf->getTaskQueueStatus(); print_r($taskQueueStatus); ``` - ### 21. Execute Transaction - **API Path**: `/api/blockchain/executeTransaction` @@ -626,8 +605,6 @@ $tokenInfo = new TokenInfo(); $tokenInfo->mergeFromString(hex2bin($response)); ``` - - ## Other Tool Kit aelf supplies some APIs to simplify development. @@ -641,8 +618,7 @@ $chainId = $aelf->getChainId(); print_r($chainId); ``` - -### 2. Generate Transaction +### 2. Generate Transaction ```php $aelf = new AElf($url); @@ -652,8 +628,7 @@ $param->setValue(''); $transaction = $aelf->generateTransaction($fromAddress, $toAddress, $methodName, $param); ``` - -### 3. Sign Transaction +### 3. Sign Transaction ```php $aelf = new AElf($url); @@ -662,7 +637,6 @@ $transaction = $aelf->generateTransaction($fromAddress, $toAddress, $methodName, $signature = $aelf->signTransaction($privateKey, $transaction); ``` - ### 4. Get Genesis Contract Address ```php @@ -672,8 +646,8 @@ $genesisContractAddress = $aelf->getGenesisContractAddress(); print_r($genesisContractAddress); ``` - ### 5. Get Address From PubKey + Calculate the account address according to the public key. ```php @@ -683,8 +657,8 @@ $pubKeyAddress = $aelf->getAddressFromPubKey('04166cf4be901dee1c21f3d97b9e4818f2 print_r($pubKeyAddress); ``` - ### 6. Get Formatted Address + Convert the address to the displayed string: symbol_base58-string_base58-string_chain_id. ```php @@ -694,8 +668,8 @@ $addressVal = $aelf->getFormattedAddress($privateKey, $base58Address); print_r($addressVal); ``` - ### 7. Generate Key Pair Info + Generate a new key pair using ECDSA. ```php @@ -705,8 +679,7 @@ $pairInfo = $aelf->generateKeyPairInfo(); print_r($pairInfo); ``` - -### 8. Get Contract Address By Name +### 8. Get Contract Address By Name ```php $aelf = new AElf($url); @@ -717,7 +690,6 @@ $contractAddress = $aelf->GetContractAddressByName($privateKey, $bytes); print_r($contractAddress); ``` - ### 9. Get Address From Private Key ```php @@ -727,7 +699,6 @@ $address = $aelf->getAddressFromPrivateKey($privateKey); print_r($address); ``` - ### 10. Get Signature With Private Key ```php @@ -737,7 +708,6 @@ $sign = $aelf->getSignatureWithPrivateKey($privateKey, $transactionId); print_r($sign); ``` - ### 11. Is Connected ```php @@ -747,11 +717,11 @@ $isConnected = $this->aelf->isConnected(); print_r($isConnected); ``` - ### 12. Get Transaction Fees + Get the transaction fee from the transaction result. -```php +```php $aelf = new AElf($url); $block = $aelf->getBlockByHeight(1, true); @@ -769,18 +739,14 @@ $aelf = new AElf($url); $version = $aelf->version; ``` - ## Requirements - [**php**](https://php.net) - - ## About contributing -Read out [contributing guide] + +Read out [contributing guide](../../../resources/contribution/index.md) ## About Version [https://semver.org/](https://semver.org/) - - diff --git a/docs/tools/chain-sdk/python-sdk/index.md b/docs/tools/chain-sdk/python-sdk/index.md index 6a3b6611..f2ce79c4 100644 --- a/docs/tools/chain-sdk/python-sdk/index.md +++ b/docs/tools/chain-sdk/python-sdk/index.md @@ -29,7 +29,6 @@ from aelf import AElf chain = AElf('http://127.0.0.1:8000') ``` - ## Examples You can find more examples in the `./test` directory of the repository. @@ -45,7 +44,6 @@ from aelf import AElf aelf = AElf('http://127.0.0.1:8000') ``` - ### 2. Get a System Contract Address To get a system contract address, for example, the `AElf.ContractNames.Token`, use the following code: @@ -63,7 +61,6 @@ genesis_contract_address = aelf.get_genesis_contract_address_string() multi_token_contract_address = aelf.get_system_contract_address('AElf.ContractNames.Token') ``` - ### 3. Send a Transaction To send a transaction, first get the contract address and then use the following steps: @@ -93,9 +90,7 @@ aelf.sign_transaction(private_key, transaction) aelf.execute_transaction(transaction) ``` -By following these instructions, you can effectively interact with the aelf blockchain using the `aelf-sdk.py` library. For more detailed examples and information, please refer to the [aelf-sdk.py repository](https://github.com/AElfProject/aelf-sdk.py). - - +By following these instructions, you can effectively interact with the aelf blockchain using the `aelf-sdk.py` library. For more detailed examples and information, please refer to the [aelf-sdk.py repository](https://github.com/AElfProject/aelf-sdk.py). ## Web API @@ -105,7 +100,6 @@ For example, if your local address is `http://127.0.0.1:1235`, you can access it Before using these methods, make sure you have an `AElf` instance. If not, create one as shown below: - ```python from aelf import AElf @@ -113,28 +107,27 @@ from aelf import AElf aelf = AElf('http://127.0.0.1:8000') ``` - ### 1. Get Chain Status **Web API Path**: `/api/blockChain/chainStatus` **Parameters**: None -**Returns**: +**Returns**: - - `JSON` +- `JSON` - - `ChainId` - String - - `Branches` - JSON - - `NotLinkedBlocks` - JSON - - `LongestChainHeight` - Number - - `LongestChainHash` - String - - `GenesisBlockHash` - String - - `GenesisContractAddress` - String - - `LastIrreversibleBlockHash` - String - - `LastIrreversibleBlockHeight` - Number - - `BestChainHash` - String - - `BestChainHeight` - Number + - `ChainId` - String + - `Branches` - JSON + - `NotLinkedBlocks` - JSON + - `LongestChainHeight` - Number + - `LongestChainHash` - String + - `GenesisBlockHash` - String + - `GenesisContractAddress` - String + - `LastIrreversibleBlockHash` - String + - `LastIrreversibleBlockHeight` - Number + - `BestChainHash` - String + - `BestChainHeight` - Number **Example**: @@ -144,7 +137,6 @@ chain_status = aelf.get_chain_status() print('# get_chain_status', chain_status) ``` - ### 2. Get Block Height **Web API Path**: `/api/blockChain/blockHeight` @@ -161,35 +153,34 @@ block_height = aelf.get_block_height() print('# get_block_height', block_height) ``` - ### 3. Get Block **Web API Path**: /api/blockChain/block **Parameters**: None - - `block_hash` - String - - `include_transactions` - Boolean (true to include transaction IDs list, false otherwise) - -**Returns**: - - - `JSON` - - - `BlockHash` - String - - `Header` - JSON - - `PreviousBlockHash` - String - - `MerkleTreeRootOfTransactions` - String - - `MerkleTreeRootOfWorldState` - String - - `Extra` - List - - `Height` - Number - - `Time` - JSON - - `ChainId` - String - - `Bloom` - String - - `SignerPubkey` - String - - `Body` - JSON - - `TransactionsCount` - Number - - `Transactions` - List - - `transactionId` - String +- `block_hash` - String +- `include_transactions` - Boolean (true to include transaction IDs list, false otherwise) + +**Returns**: + +- `JSON` + +- `BlockHash` - String +- `Header` - JSON + - `PreviousBlockHash` - String + - `MerkleTreeRootOfTransactions` - String + - `MerkleTreeRootOfWorldState` - String + - `Extra` - List + - `Height` - Number + - `Time` - JSON + - `ChainId` - String + - `Bloom` - String + - `SignerPubkey` - String +- `Body` - JSON + - `TransactionsCount` - Number + - `Transactions` - List + - `transactionId` - String **Example**: @@ -199,35 +190,34 @@ block = aelf.get_block(blockHash) print('# get_block', block) ``` - ### 4. Get Block by Height **Web API Path**: /api/blockChain/blockByHeight -**Parameters**: - - - `block_height` - Number - - `include_transactions` - Boolean (true to include transaction IDs list, false otherwise) - -**Returns**: - - - `JSON` +**Parameters**: - - `BlockHash` - String - - `Header` - JSON - - `PreviousBlockHash` - String - - `MerkleTreeRootOfTransactions` - String - - `MerkleTreeRootOfWorldState` - String - - `Extra` - List - - `Height` - Number - - `Time` - JSON - - `ChainId` - String - - `Bloom` - String - - `SignerPubkey` - String - - `Body` - JSON - - `TransactionsCount` - Number - - `Transactions` - List - - `transactionId` - String +- `block_height` - Number +- `include_transactions` - Boolean (true to include transaction IDs list, false otherwise) + +**Returns**: + +- `JSON` + +- `BlockHash` - String +- `Header` - JSON + - `PreviousBlockHash` - String + - `MerkleTreeRootOfTransactions` - String + - `MerkleTreeRootOfWorldState` - String + - `Extra` - List + - `Height` - Number + - `Time` - JSON + - `ChainId` - String + - `Bloom` - String + - `SignerPubkey` - String +- `Body` - JSON + - `TransactionsCount` - Number + - `Transactions` - List + - `transactionId` - String **Example**: @@ -237,38 +227,37 @@ block_by_height = aelf.get_block_by_height(12, False) print('# get_block_by_height', block_by_height) ``` - ### 5. Get Transaction Result **Web API Path**: /api/blockChain/transactionResult **Parameters**: - - `transactionId` - String - -**Returns**: - - - `JSON` - - - `TransactionId` - String - - `Status` - String - - `Logs` - List - - `Address` - String - - `Name` - String - - `Indexed` - List - - `NonIndexed` - String - - `Bloom` - String - - `BlockNumber` - Number - - `Transaction` - List - - `From` - Number - - `To` - Number - - `RefBlockNumber` - Number - - `RefBlockPrefix` - String - - `MethodName` - String - - `Params` - JSON - - `Signature` - String - - `ReadableReturnValue` - JSON - - `Error` - String +- `transactionId` - String + +**Returns**: + +- `JSON` + + - `TransactionId` - String + - `Status` - String + - `Logs` - List + - `Address` - String + - `Name` - String + - `Indexed` - List + - `NonIndexed` - String + - `Bloom` - String + - `BlockNumber` - Number + - `Transaction` - List + - `From` - Number + - `To` - Number + - `RefBlockNumber` - Number + - `RefBlockPrefix` - String + - `MethodName` - String + - `Params` - JSON + - `Signature` - String + - `ReadableReturnValue` - JSON + - `Error` - String **Example**: @@ -278,17 +267,15 @@ transaction_result = aelf.get_transaction_result(transactionId) print('# get_transaction_result', transaction_result) ``` - ### 6. Get Transaction Results **Web API Path**: /api/blockChain/transactionResults **Parameters**: - - `blockHash` - String - - `offset` - Number - - `limit` - Number - +- `blockHash` - String +- `offset` - Number +- `limit` - Number **Returns**: `List` of transaction result objects @@ -300,8 +287,6 @@ transaction_results = aelf.get_transaction_results(blockHash, 0, 2) print('# get_transaction_results', transaction_results) ``` - - ### 7. Get Transaction Pool Status **Web API Path**: /api/blockChain/transactionPoolStatus @@ -314,7 +299,6 @@ tx_pool_status = aelf.get_transaction_pool_status() print('# get_transaction_pool_status', tx_pool_status) ``` - ### 8. Send Transaction **Web API Path**: `/api/blockChain/sendTransaction` @@ -323,7 +307,7 @@ print('# get_transaction_pool_status', tx_pool_status) **Parameters**: - - `transaction` - String (serialized data) +- `transaction` - String (serialized data) **Example**: @@ -341,8 +325,6 @@ result = aelf.send_transaction(transaction.SerializePartialToString().hex()) print('# send_transaction', result) ``` - - ### 9. Send Transactions **Web API Path**: `/api/blockChain/sendTransaction` @@ -351,7 +333,7 @@ print('# send_transaction', result) **Parameters**: - - `transactions` - String (serialized data) +- `transactions` - String (serialized data) **Example**: @@ -365,7 +347,6 @@ result = aelf.send_transaction(transaction1 + ',' + transaction2) print('# send_transactions', result) ``` - ### 10. Get Peers **Web API Path**: `/api/net/peers` @@ -378,7 +359,6 @@ peers = aelf.get_peers() print('# get_peers', peers) ``` - ### 11. Add Peer **Web API Path**: `/api/net/peers` @@ -387,7 +367,7 @@ print('# get_peers', peers) **Parameters**: - - `peer_address` - String (peer’s endpoint) +- `peer_address` - String (peer’s endpoint) **Example**: @@ -397,8 +377,6 @@ add_peer = aelf.add_peer(endpoint) print('# add_peer', add_peer) ``` - - ### 12. Remove Peer **Web API Path**: `/api/net/peer?address=` @@ -407,7 +385,7 @@ print('# add_peer', add_peer) **Parameters**: - - `peer_address` - String (peer’s endpoint) +- `peer_address` - String (peer’s endpoint) **Example**: @@ -425,12 +403,12 @@ print('# remove_peer', remove_peer) **Parameters**: - - `transaction` - JSON format transaction +- `transaction` - JSON format transaction -**Returns**: +**Returns**: - - `JSON` - - `RawTransaction` - hex string bytes generated by transaction information +- `JSON` + - `RawTransaction` - hex string bytes generated by transaction information **Example**: @@ -448,7 +426,6 @@ raw_transaction = aelf.create_raw_transaction(transaction) print('# create_raw_transaction', raw_transaction) ``` - ### 14. Send Raw Transaction **Web API Path**: `/api/blockchain/sendRawTransaction` @@ -457,9 +434,9 @@ print('# create_raw_transaction', raw_transaction) **Parameters**: - - `Transaction` - raw transaction - - `Signature` - signature - - `ReturnTransaction` - indicates whether to return the transaction +- `Transaction` - raw transaction +- `Signature` - signature +- `ReturnTransaction` - indicates whether to return the transaction **Example**: @@ -499,8 +476,8 @@ print('# send_raw_transaction', result) **Parameters**: - - `RawTransaction` - raw transaction - - `Signature` - signature +- `RawTransaction` - raw transaction +- `Signature` - signature **Example**: @@ -531,7 +508,6 @@ result = aelf.execute_raw_transaction(transaction_1) print('# execute_raw_transaction', result) ``` - ### 16. Get Merkle Path **Web API Path**: `/api/blockchain/merklePathByTransactionId?transactionId=` @@ -540,7 +516,7 @@ print('# execute_raw_transaction', result) **Parameters**: - - `transactionId` - String +- `transactionId` - String **Example**: @@ -552,7 +528,6 @@ merkle_path = aelf.get_merkle_path(transaction_id) print('# get_merkle_path', merkle_path) ``` - ### 17. Calculate Transaction Fee **Web API Path**: `/api/blockchain/calculateTransactionFee` @@ -561,15 +536,15 @@ print('# get_merkle_path', merkle_path) **Parameters**: - - `CalculateTransactionFeeInput` - JSON with the following structure: - - `RawTransaction` - String +- `CalculateTransactionFeeInput` - JSON with the following structure: + - `RawTransaction` - String -**Returns**: +**Returns**: - - `CalculateTransactionFeeOutput` - `json` - The json with the following structure : - - `Success` - Boolean - - `TransactionFee` - Array - - `ResourceFee` - Array +- `CalculateTransactionFeeOutput` - `json` - The json with the following structure : + - `Success` - Boolean + - `TransactionFee` - Array + - `ResourceFee` - Array **Example**: @@ -584,8 +559,6 @@ calculate_transaction_fee_output = aelf.calculate_transaction_fee(calculate_tran print('# calculate_transaction_fee', calculate_transaction_fee_output) ``` - - ### 18. Get Network Info **Web API Path**: `/api/net/networkInfo` @@ -601,8 +574,6 @@ network_info = aelf.get_network_info() print('# get_network_info', network_info) ``` - - ## AElf.client Use the API to see detailed results. @@ -619,16 +590,15 @@ aelf = AElf(url) genesis_contract_address = aelf.get_genesis_contract_address_string() ``` - ### 2. get_system_contract_address **Parameters:** - - `contract_name` - String: system contract’s name +- `contract_name` - String: system contract’s name **Returns:** - - `Address`: system contract’s address +- `Address`: system contract’s address **Example:** @@ -638,16 +608,15 @@ aelf = AElf(url) multi_token_contract_address = aelf.get_system_contract_address('AElf.ContractNames.Token') ``` - ### 3. get_system_contract_address_string **Parameters:** - - `contract_name` - String: system contract’s name +- `contract_name` - String: system contract’s name **Returns:** - - `String`: system contract’s address +- `String`: system contract’s address **Example:** @@ -657,14 +626,13 @@ aelf = AElf(url) multi_token_contract_address_string = aelf.get_system_contract_address_string('AElf.ContractNames.Token') ``` - ### 4. create_transaction **Parameters:** - - `to_address` - Address or String: target contract’s address - - `method_name` - String: method name - - `params` - String: serialize parameters into String +- `to_address` - Address or String: target contract’s address +- `method_name` - String: method name +- `params` - String: serialize parameters into String **Example:** @@ -676,15 +644,14 @@ params.value = hashlib.sha256(contract_name.encode('utf8')).digest() transaction = aelf.create_transaction(genesisContractAddress, 'GetContractAddressByName', params.SerializeToString()) ``` - ### 5. sign_transaction Sign a transaction with the user’s private key. **Parameters:** - - `private_key` - String: user’s private key - - `transaction` - Transaction: transaction +- `private_key` - String: user’s private key +- `transaction` - Transaction: transaction **Example:** @@ -698,18 +665,17 @@ transaction = aelf.create_transaction(to_address_string, 'GetContractAddressByNa transaction = aelf.sign_transaction(private_key, transaction) ``` - ### 6. get_address_from_public_key Generate an address from a public key. **Parameters:** - - `public_key` - bytes: user’s public key +- `public_key` - bytes: user’s public key **Returns:** - - `Address` +- `Address` **Example:** @@ -718,18 +684,17 @@ aelf = AElf(url) address = aelf.get_address_from_public_key(public_key) ``` - ### 7. get_address_string_from_public_key Generate an address string from a public key. **Parameters:** - - `public_key` - bytes: user’s public key +- `public_key` - bytes: user’s public key **Returns:** - - `String` +- `String` **Example:** @@ -738,14 +703,11 @@ aelf = AElf(url) address = aelf.get_address_string_from_public_key(public_key) ``` - - ### 8. get_chain_id - **Returns:** - - `Number` +- `Number` **Example:** @@ -756,18 +718,16 @@ chain_id = aelf.get_chain_id() print('# get_chain_id', chain_id) ``` - - ### 9. get_formatted_address **Parameters:** - - `address` - Address: address +- `address` - Address: address **Returns:** - - `String` - +- `String` + **Example:** ```python @@ -777,7 +737,6 @@ formatted_address = aelf.get_formatted_address(address) print('formatted address', formatted_address) ``` - ### 9. is_connected Check whether the node is connected. @@ -789,13 +748,10 @@ aelf = AElf(url) is_connected = aelf.is_connected() ``` - - ## Tookkits.py AElfToolkit Encapsulate AElf and user’s private key. It simplifies the procedures of sending some transactions. You can find it in src/aelf/toolkits.py. - ### Create a Toolkit Create a Toolkit with AElfToolkit. @@ -811,7 +767,6 @@ private_key = PrivateKey(bytes(bytearray.fromhex(private_key_string))) toolkit = AElfToolkit('http://127.0.0.1:8000', private_key) ``` - ### Send a Transaction Send a CrossChainTransfer transaction using AElfToolkit. @@ -832,22 +787,19 @@ toolkit = AElfToolkit('http://127.0.0.1:8000', private_key) toolkit.cross_chain_transfer(to_address_string, symbol, amount, memo, to_chain_id) ``` - - ## Requirements - [Python](https://www.python.org/) - [Docker](https://www.docker.com/) - ## Support - [Node](https://hub.docker.com/r/aelf/node) ## About Contributing -Read out [contributing guide]. +Read out [contributing guide](../../../resources/contribution/index.md). ## About Version -[https://semver.org/](https://semver.org/) \ No newline at end of file +[https://semver.org/](https://semver.org/) diff --git a/docs/tutorials/developers/javascript-sdk/index.md b/docs/tutorials/developers/javascript-sdk/index.md index 15916244..f9a7e830 100644 --- a/docs/tutorials/developers/javascript-sdk/index.md +++ b/docs/tutorials/developers/javascript-sdk/index.md @@ -829,7 +829,7 @@ To use aelf SDK, you need: ## About contributing -Read out [contributing guide] +Read out [contributing guide](../../../resources/contribution/index.md) ## About Version diff --git a/docs/tutorials/developers/php-sdk/index.md b/docs/tutorials/developers/php-sdk/index.md index 27ecce18..faac9aba 100644 --- a/docs/tutorials/developers/php-sdk/index.md +++ b/docs/tutorials/developers/php-sdk/index.md @@ -8,11 +8,13 @@ image: /img/Logo.aelf.svg # aelf-sdk.php - aelf PHP API ## Introduction + aelf-sdk.php for aelf is similar to web.js for Ethereum. It consists of libraries that enable interaction with a local or remote aelf node via HTTP. This documentation will guide you through the installation and usage of aelf-sdk.php, with examples included. For more information, visit the [aelf-sdk.php repository](https://github.com/AElfProject/aelf-sdk.php). ## Adding aelf PHP SDK + To install the library via Composer, run the following commands in your console: ```sh @@ -33,6 +35,7 @@ If you cloned the SDK directly, you must install Composer and run it in the root ## Examples ### 1. Create an Instance + Create a new instance of AElf and connect to an AELF chain node. Using this instance, you can call the AElf APIs. ```php @@ -44,6 +47,7 @@ $aelf = new AElf($url); ``` ### 2. Get a System Contract Address + Get a system contract address. For example, to get the address of `AElf.ContractNames.Token`: ```php @@ -61,6 +65,7 @@ $contractAddress = $aelf->GetContractAddressByName($privateKey, $bytes); ``` ### 3. Send a Transaction + Get the contract address and then send a transaction. ```php @@ -113,7 +118,6 @@ $url = '127.0.0.1:8000'; $aelf = new AElf($url); ``` - ### 1. Get Chain Status - **API Path**: `/api/blockChain/chainStatus` @@ -122,19 +126,18 @@ $aelf = new AElf($url); - **Returns**: - - `Array` - - `ChainId` - String - - `Branches` - Array - - `NotLinkedBlocks` - Array - - `LongestChainHeight` - Integer - - `LongestChainHash` - String - - `GenesisBlockHash` - String - - `GenesisContractAddress` - String - - `LastIrreversibleBlockHash` - String - - `LastIrreversibleBlockHeight` - Integer - - `BestChainHash` - String - - `BestChainHeight` - Integer - + - `Array` + - `ChainId` - String + - `Branches` - Array + - `NotLinkedBlocks` - Array + - `LongestChainHeight` - Integer + - `LongestChainHash` - String + - `GenesisBlockHash` - String + - `GenesisContractAddress` - String + - `LastIrreversibleBlockHash` - String + - `LastIrreversibleBlockHeight` - Integer + - `BestChainHash` - String + - `BestChainHeight` - Integer - **Example** : @@ -146,8 +149,6 @@ $chainStatus = $aelf->getChainStatus(); print_r($chainStatus); ``` - - ### 2. Get Block Height - **API Path**: `/api/blockChain/blockHeight` @@ -165,34 +166,33 @@ $height = $aelf->getBlockHeight(); print($height); ``` - ### 3. getBlock - **API Path**: `/api/blockChain/block` -- **Parameters**: - - - `block_hash` (String) - - `include_transactions` (Boolean) - -- **Returns**: - - - `Array` - - `BlockHash` - String - - `Header` - Array - - `PreviousBlockHash` - String - - `MerkleTreeRootOfTransactions` - String - - `MerkleTreeRootOfWorldState` - String - - `Extra` - List - - `Height` - Integer - - `Time` - String - - `ChainId` - String - - `Bloom` - String - - `SignerPubkey` - String - - `Body` - Array - - `TransactionsCount` - Integer - - `Transactions` - Array - - `transactionId` - String +- **Parameters**: + + - `block_hash` (String) + - `include_transactions` (Boolean) + +- **Returns**: + + - `Array` + - `BlockHash` - String + - `Header` - Array + - `PreviousBlockHash` - String + - `MerkleTreeRootOfTransactions` - String + - `MerkleTreeRootOfWorldState` - String + - `Extra` - List + - `Height` - Integer + - `Time` - String + - `ChainId` - String + - `Bloom` - String + - `SignerPubkey` - String + - `Body` - Array + - `TransactionsCount` - Integer + - `Transactions` - Array + - `transactionId` - String - **Example** : @@ -204,35 +204,33 @@ $block2 = $aelf->getBlockByHash($block['BlockHash'], false); print_r($block2); ``` - ### 4. Get Block by Height - **API Path**: `/api/blockChain/blockByHeight` -- **Parameters**: - - - `block_height` (Number) - - `include_transactions` (Boolean) +- **Parameters**: -- **Returns**: + - `block_height` (Number) + - `include_transactions` (Boolean) - - `Array` - - `BlockHash` - String - - `Header` - Array - - `PreviousBlockHash` - String - - `MerkleTreeRootOfTransactions` - String - - `MerkleTreeRootOfWorldState` - String - - `Extra` - List - - `Height` - Integer - - `Time` - String - - `ChainId` - String - - `Bloom` - String - - `SignerPubkey` - String - - `Body` - Array - - `TransactionsCount` - Integer - - `Transactions` - Array - - `transactionId` - String +- **Returns**: + - `Array` + - `BlockHash` - String + - `Header` - Array + - `PreviousBlockHash` - String + - `MerkleTreeRootOfTransactions` - String + - `MerkleTreeRootOfWorldState` - String + - `Extra` - List + - `Height` - Integer + - `Time` - String + - `ChainId` - String + - `Bloom` - String + - `SignerPubkey` - String + - `Body` - Array + - `TransactionsCount` - Integer + - `Transactions` - Array + - `transactionId` - String - **Example** : @@ -243,38 +241,37 @@ $block = $aelf->getBlockByHeight(1, true); print_r($block); ``` - ### 5. Get Transaction Result - **API Path**: `/api/blockChain/transactionResult` -- **Parameters**: +- **Parameters**: - - `transactionId` (String) + - `transactionId` (String) - **Returns**: - - `Object` - - `TransactionId` - String - - `Status` - String - - `Logs` - Array - - `Address` - String - - `Name` - String - - `Indexed` - Array - - `NonIndexed` - String - - `Bloom` - String - - `BlockNumber` - Integer - - `Transaction` - Array - - `From` - String - - `To` - String - - `RefBlockNumber` - Integer - - `RefBlockPrefix` - String - - `MethodName` - String - - `Params` - json - - `Signature` - String - - `transactionId` - String - - `ReadableReturnValue` - String - - `Error` - String + - `Object` + - `TransactionId` - String + - `Status` - String + - `Logs` - Array + - `Address` - String + - `Name` - String + - `Indexed` - Array + - `NonIndexed` - String + - `Bloom` - String + - `BlockNumber` - Integer + - `Transaction` - Array + - `From` - String + - `To` - String + - `RefBlockNumber` - Integer + - `RefBlockPrefix` - String + - `MethodName` - String + - `Params` - json + - `Signature` - String + - `transactionId` - String + - `ReadableReturnValue` - String + - `Error` - String - **Example** : @@ -286,21 +283,20 @@ $transactionResult = $aelf->getTransactionResult($block['Body']['Transactions'][ print_r($transactionResult); ``` - ### 6. Get Multiple Transaction Results - **API Path**: `/api/blockChain/transactionResults` -- **Parameters**: +- **Parameters**: - - `blockHash` (String) - - `offset` (Number) - - `limit` (Number) + - `blockHash` (String) + - `offset` (Number) + - `limit` (Number) -- **Returns**: +- **Returns**: - - `List` - The array of method descriptions: - - the transaction result object + - `List` - The array of method descriptions: + - the transaction result object - **Example** : @@ -312,7 +308,6 @@ $transactionResults = $aelf->getTransactionResults($block['Body']); print_r($transactionResults); ``` - ### 7. Get Transaction Pool Status - **API Path**: `/api/blockChain/transactionPoolStatus` @@ -326,16 +321,15 @@ $status = $aelf->getTransactionPoolStatus(); print_r($status); ``` - ### 8. Send Transaction - **API Path**: `/api/blockChain/sendTransaction` - **Method**: POST -- **Parameters**: +- **Parameters**: - - `transaction` (String) + - `transaction` (String) - **Example** : @@ -348,16 +342,15 @@ $result = $aelf->sendTransaction($executeTransactionDtoObj); print_r($result); ``` - ### 9. Send Multiple Transactions - **API Path**: `/api/blockChain/sendTransactions` - **Method**:POST -- **Parameters**: +- **Parameters**: - - `transactions` (String) + - `transactions` (String) - **Example** : @@ -376,7 +369,6 @@ $listString = $aelf->sendTransactions($sendTransactionsInputs); print_r($listString); ``` - ### 10. Get Peers - **API Path**: `/api/net/peers` @@ -387,7 +379,6 @@ print_r($listString); print_r($aelf->getPeers(true)); ``` - ### 11. Add Peer - **API Path**: `/api/net/peer` @@ -396,7 +387,7 @@ print_r($aelf->getPeers(true)); - **Parameters**: - - `peer_address` (String) + - `peer_address` (String) - **Example** : @@ -404,14 +395,13 @@ print_r($aelf->getPeers(true)); $aelf->addPeer($url); ``` - ### 12. Remove Peer - **API Path**: `/api/net/peer` - **Parameters**: - - `peer_address` (String) + - `peer_address` (String) - **Example** : @@ -419,21 +409,20 @@ $aelf->addPeer($url); $aelf->removePeer($url); ``` - ### 13. Create Raw Transaction - **API Path**: `/api/blockchain/rawTransaction` - **Method**: POST -- **Parameters**: +- **Parameters**: - - `transaction` (Array) + - `transaction` (Array) -- **Returns**: +- **Returns**: - - `Array` - - `RawTransaction` - hex string bytes generated by transaction information + - `Array` + - `RawTransaction` - hex string bytes generated by transaction information - **Example** : @@ -455,16 +444,15 @@ $rawTransaction = $aelf->createRawTransaction($transaction); print_r($rawTransaction); ``` - ### 14. Send Raw Transaction - **API Path**: `/api/blockchain/sendRawTransaction` -- **Parameters**: +- **Parameters**: - - `Transaction` (raw transaction) - - `Signature` (signature) - - `ReturnTransaction` (indicates whether to return transaction) + - `Transaction` (raw transaction) + - `Signature` (signature) + - `ReturnTransaction` (indicates whether to return transaction) - **Example** : @@ -479,19 +467,16 @@ $execute = $aelf->sendRawTransaction($transaction); print_r($execute); ``` - - ### 15. Execute Raw Transaction - **API Path**: `/api/blockchain/executeRawTransaction` - **Method**: POST -- **Parameters**: - - - `RawTransaction` (raw transaction) - - `Signature` (signature) +- **Parameters**: + - `RawTransaction` (raw transaction) + - `Signature` (signature) - **Example** : @@ -506,14 +491,13 @@ $execute = $aelf->executeRawTransaction($transaction); print_r($execute); ``` - ### 16. Get Merkle Path by Transaction ID - **API Path**: `/api/blockchain/merklePathByTransactionId` -- **Parameters**: +- **Parameters**: - - `transactionId` (String) + - `transactionId` (String) - **Example** : @@ -525,24 +509,23 @@ $merklePath = $aelf->getMerklePathByTransactionId($block['Body']['Transactions'] print_r($merklePath); ``` - ### 17. Calculate Transaction Fee - **API Path**: `/api/blockChain/calculateTransactionFee` - **Method**: POST -- **Parameters**: +- **Parameters**: - - `CalculateTransactionFeeInput` (Object) + - `CalculateTransactionFeeInput` (Object) -- **Returns**: +- **Returns**: - - `CalculateTransactionFeeOutput (Object)` + - `CalculateTransactionFeeOutput (Object)` - - `Success` - bool - - `TransactionFee` - Array - - `ResourceFee` - Array + - `Success` - bool + - `TransactionFee` - Array + - `ResourceFee` - Array - **Example** : @@ -556,7 +539,6 @@ $result = $aelf->calculateTransactionFee($calculateTransactionFeeInputParam); print_r($result); ``` - ### 18. Get Network Info - **API Path**: `/api/net/networkInfo` @@ -569,7 +551,6 @@ $aelf = new AElf($url); print_r($aelf->getNetworkInfo()); ``` - ### 19. Get Contract File Descriptor Set - **API Path**: `/api/blockchain/contractFileDescriptorSet` @@ -587,7 +568,6 @@ foreach ($transactionResultDtoList as $v) { } ``` - ### 20. Get Task Queue Status - **API Path**: `/api/blockchain/taskQueueStatus` @@ -601,7 +581,6 @@ $taskQueueStatus = $aelf->getTaskQueueStatus(); print_r($taskQueueStatus); ``` - ### 21. Execute Transaction - **API Path**: `/api/blockchain/executeTransaction` @@ -626,8 +605,6 @@ $tokenInfo = new TokenInfo(); $tokenInfo->mergeFromString(hex2bin($response)); ``` - - ## Other Tool Kit aelf supplies some APIs to simplify development. @@ -641,8 +618,7 @@ $chainId = $aelf->getChainId(); print_r($chainId); ``` - -### 2. Generate Transaction +### 2. Generate Transaction ```php $aelf = new AElf($url); @@ -652,8 +628,7 @@ $param->setValue(''); $transaction = $aelf->generateTransaction($fromAddress, $toAddress, $methodName, $param); ``` - -### 3. Sign Transaction +### 3. Sign Transaction ```php $aelf = new AElf($url); @@ -662,7 +637,6 @@ $transaction = $aelf->generateTransaction($fromAddress, $toAddress, $methodName, $signature = $aelf->signTransaction($privateKey, $transaction); ``` - ### 4. Get Genesis Contract Address ```php @@ -672,8 +646,8 @@ $genesisContractAddress = $aelf->getGenesisContractAddress(); print_r($genesisContractAddress); ``` - ### 5. Get Address From PubKey + Calculate the account address according to the public key. ```php @@ -683,8 +657,8 @@ $pubKeyAddress = $aelf->getAddressFromPubKey('04166cf4be901dee1c21f3d97b9e4818f2 print_r($pubKeyAddress); ``` - ### 6. Get Formatted Address + Convert the address to the displayed string: symbol_base58-string_base58-string_chain_id. ```php @@ -694,8 +668,8 @@ $addressVal = $aelf->getFormattedAddress($privateKey, $base58Address); print_r($addressVal); ``` - ### 7. Generate Key Pair Info + Generate a new key pair using ECDSA. ```php @@ -705,8 +679,7 @@ $pairInfo = $aelf->generateKeyPairInfo(); print_r($pairInfo); ``` - -### 8. Get Contract Address By Name +### 8. Get Contract Address By Name ```php $aelf = new AElf($url); @@ -717,7 +690,6 @@ $contractAddress = $aelf->GetContractAddressByName($privateKey, $bytes); print_r($contractAddress); ``` - ### 9. Get Address From Private Key ```php @@ -727,7 +699,6 @@ $address = $aelf->getAddressFromPrivateKey($privateKey); print_r($address); ``` - ### 10. Get Signature With Private Key ```php @@ -737,7 +708,6 @@ $sign = $aelf->getSignatureWithPrivateKey($privateKey, $transactionId); print_r($sign); ``` - ### 11. Is Connected ```php @@ -747,11 +717,11 @@ $isConnected = $this->aelf->isConnected(); print_r($isConnected); ``` - ### 12. Get Transaction Fees + Get the transaction fee from the transaction result. -```php +```php $aelf = new AElf($url); $block = $aelf->getBlockByHeight(1, true); @@ -769,18 +739,14 @@ $aelf = new AElf($url); $version = $aelf->version; ``` - ## Requirements - [**php**](https://php.orgwe67y8re8hufr54ff4ed3ed32ws2d3crf4cfsx2ws2e33333333333333333333333333333333dr34cf4c2q4cfuj7ji8o87hb6fv4d3ed3/) - - ## About contributing -Read out [contributing guide] + +Read out [contributing guide](../../../resources/contribution/index.md) ## About Version [https://semver.org/](https://semver.org/) - - diff --git a/docs/tutorials/developers/python-sdk/index.md b/docs/tutorials/developers/python-sdk/index.md index 6a3b6611..1d09eac0 100644 --- a/docs/tutorials/developers/python-sdk/index.md +++ b/docs/tutorials/developers/python-sdk/index.md @@ -29,7 +29,6 @@ from aelf import AElf chain = AElf('http://127.0.0.1:8000') ``` - ## Examples You can find more examples in the `./test` directory of the repository. @@ -45,7 +44,6 @@ from aelf import AElf aelf = AElf('http://127.0.0.1:8000') ``` - ### 2. Get a System Contract Address To get a system contract address, for example, the `AElf.ContractNames.Token`, use the following code: @@ -63,7 +61,6 @@ genesis_contract_address = aelf.get_genesis_contract_address_string() multi_token_contract_address = aelf.get_system_contract_address('AElf.ContractNames.Token') ``` - ### 3. Send a Transaction To send a transaction, first get the contract address and then use the following steps: @@ -93,9 +90,7 @@ aelf.sign_transaction(private_key, transaction) aelf.execute_transaction(transaction) ``` -By following these instructions, you can effectively interact with the aelf blockchain using the `aelf-sdk.py` library. For more detailed examples and information, please refer to the [aelf-sdk.py repository](https://github.com/AElfProject/aelf-sdk.py). - - +By following these instructions, you can effectively interact with the aelf blockchain using the `aelf-sdk.py` library. For more detailed examples and information, please refer to the [aelf-sdk.py repository](https://github.com/AElfProject/aelf-sdk.py). ## Web API @@ -105,7 +100,6 @@ For example, if your local address is `http://127.0.0.1:1235`, you can access it Before using these methods, make sure you have an `AElf` instance. If not, create one as shown below: - ```python from aelf import AElf @@ -113,28 +107,27 @@ from aelf import AElf aelf = AElf('http://127.0.0.1:8000') ``` - ### 1. Get Chain Status **Web API Path**: `/api/blockChain/chainStatus` **Parameters**: None -**Returns**: +**Returns**: - - `JSON` +- `JSON` - - `ChainId` - String - - `Branches` - JSON - - `NotLinkedBlocks` - JSON - - `LongestChainHeight` - Number - - `LongestChainHash` - String - - `GenesisBlockHash` - String - - `GenesisContractAddress` - String - - `LastIrreversibleBlockHash` - String - - `LastIrreversibleBlockHeight` - Number - - `BestChainHash` - String - - `BestChainHeight` - Number + - `ChainId` - String + - `Branches` - JSON + - `NotLinkedBlocks` - JSON + - `LongestChainHeight` - Number + - `LongestChainHash` - String + - `GenesisBlockHash` - String + - `GenesisContractAddress` - String + - `LastIrreversibleBlockHash` - String + - `LastIrreversibleBlockHeight` - Number + - `BestChainHash` - String + - `BestChainHeight` - Number **Example**: @@ -144,7 +137,6 @@ chain_status = aelf.get_chain_status() print('# get_chain_status', chain_status) ``` - ### 2. Get Block Height **Web API Path**: `/api/blockChain/blockHeight` @@ -161,35 +153,34 @@ block_height = aelf.get_block_height() print('# get_block_height', block_height) ``` - ### 3. Get Block **Web API Path**: /api/blockChain/block **Parameters**: None - - `block_hash` - String - - `include_transactions` - Boolean (true to include transaction IDs list, false otherwise) - -**Returns**: - - - `JSON` - - - `BlockHash` - String - - `Header` - JSON - - `PreviousBlockHash` - String - - `MerkleTreeRootOfTransactions` - String - - `MerkleTreeRootOfWorldState` - String - - `Extra` - List - - `Height` - Number - - `Time` - JSON - - `ChainId` - String - - `Bloom` - String - - `SignerPubkey` - String - - `Body` - JSON - - `TransactionsCount` - Number - - `Transactions` - List - - `transactionId` - String +- `block_hash` - String +- `include_transactions` - Boolean (true to include transaction IDs list, false otherwise) + +**Returns**: + +- `JSON` + +- `BlockHash` - String +- `Header` - JSON + - `PreviousBlockHash` - String + - `MerkleTreeRootOfTransactions` - String + - `MerkleTreeRootOfWorldState` - String + - `Extra` - List + - `Height` - Number + - `Time` - JSON + - `ChainId` - String + - `Bloom` - String + - `SignerPubkey` - String +- `Body` - JSON + - `TransactionsCount` - Number + - `Transactions` - List + - `transactionId` - String **Example**: @@ -199,35 +190,34 @@ block = aelf.get_block(blockHash) print('# get_block', block) ``` - ### 4. Get Block by Height **Web API Path**: /api/blockChain/blockByHeight -**Parameters**: - - - `block_height` - Number - - `include_transactions` - Boolean (true to include transaction IDs list, false otherwise) - -**Returns**: - - - `JSON` +**Parameters**: - - `BlockHash` - String - - `Header` - JSON - - `PreviousBlockHash` - String - - `MerkleTreeRootOfTransactions` - String - - `MerkleTreeRootOfWorldState` - String - - `Extra` - List - - `Height` - Number - - `Time` - JSON - - `ChainId` - String - - `Bloom` - String - - `SignerPubkey` - String - - `Body` - JSON - - `TransactionsCount` - Number - - `Transactions` - List - - `transactionId` - String +- `block_height` - Number +- `include_transactions` - Boolean (true to include transaction IDs list, false otherwise) + +**Returns**: + +- `JSON` + +- `BlockHash` - String +- `Header` - JSON + - `PreviousBlockHash` - String + - `MerkleTreeRootOfTransactions` - String + - `MerkleTreeRootOfWorldState` - String + - `Extra` - List + - `Height` - Number + - `Time` - JSON + - `ChainId` - String + - `Bloom` - String + - `SignerPubkey` - String +- `Body` - JSON + - `TransactionsCount` - Number + - `Transactions` - List + - `transactionId` - String **Example**: @@ -237,38 +227,37 @@ block_by_height = aelf.get_block_by_height(12, False) print('# get_block_by_height', block_by_height) ``` - ### 5. Get Transaction Result **Web API Path**: /api/blockChain/transactionResult **Parameters**: - - `transactionId` - String - -**Returns**: - - - `JSON` - - - `TransactionId` - String - - `Status` - String - - `Logs` - List - - `Address` - String - - `Name` - String - - `Indexed` - List - - `NonIndexed` - String - - `Bloom` - String - - `BlockNumber` - Number - - `Transaction` - List - - `From` - Number - - `To` - Number - - `RefBlockNumber` - Number - - `RefBlockPrefix` - String - - `MethodName` - String - - `Params` - JSON - - `Signature` - String - - `ReadableReturnValue` - JSON - - `Error` - String +- `transactionId` - String + +**Returns**: + +- `JSON` + + - `TransactionId` - String + - `Status` - String + - `Logs` - List + - `Address` - String + - `Name` - String + - `Indexed` - List + - `NonIndexed` - String + - `Bloom` - String + - `BlockNumber` - Number + - `Transaction` - List + - `From` - Number + - `To` - Number + - `RefBlockNumber` - Number + - `RefBlockPrefix` - String + - `MethodName` - String + - `Params` - JSON + - `Signature` - String + - `ReadableReturnValue` - JSON + - `Error` - String **Example**: @@ -278,17 +267,15 @@ transaction_result = aelf.get_transaction_result(transactionId) print('# get_transaction_result', transaction_result) ``` - ### 6. Get Transaction Results **Web API Path**: /api/blockChain/transactionResults **Parameters**: - - `blockHash` - String - - `offset` - Number - - `limit` - Number - +- `blockHash` - String +- `offset` - Number +- `limit` - Number **Returns**: `List` of transaction result objects @@ -300,8 +287,6 @@ transaction_results = aelf.get_transaction_results(blockHash, 0, 2) print('# get_transaction_results', transaction_results) ``` - - ### 7. Get Transaction Pool Status **Web API Path**: /api/blockChain/transactionPoolStatus @@ -314,7 +299,6 @@ tx_pool_status = aelf.get_transaction_pool_status() print('# get_transaction_pool_status', tx_pool_status) ``` - ### 8. Send Transaction **Web API Path**: `/api/blockChain/sendTransaction` @@ -323,7 +307,7 @@ print('# get_transaction_pool_status', tx_pool_status) **Parameters**: - - `transaction` - String (serialized data) +- `transaction` - String (serialized data) **Example**: @@ -341,8 +325,6 @@ result = aelf.send_transaction(transaction.SerializePartialToString().hex()) print('# send_transaction', result) ``` - - ### 9. Send Transactions **Web API Path**: `/api/blockChain/sendTransaction` @@ -351,7 +333,7 @@ print('# send_transaction', result) **Parameters**: - - `transactions` - String (serialized data) +- `transactions` - String (serialized data) **Example**: @@ -365,7 +347,6 @@ result = aelf.send_transaction(transaction1 + ',' + transaction2) print('# send_transactions', result) ``` - ### 10. Get Peers **Web API Path**: `/api/net/peers` @@ -378,7 +359,6 @@ peers = aelf.get_peers() print('# get_peers', peers) ``` - ### 11. Add Peer **Web API Path**: `/api/net/peers` @@ -387,7 +367,7 @@ print('# get_peers', peers) **Parameters**: - - `peer_address` - String (peer’s endpoint) +- `peer_address` - String (peer’s endpoint) **Example**: @@ -397,8 +377,6 @@ add_peer = aelf.add_peer(endpoint) print('# add_peer', add_peer) ``` - - ### 12. Remove Peer **Web API Path**: `/api/net/peer?address=` @@ -407,7 +385,7 @@ print('# add_peer', add_peer) **Parameters**: - - `peer_address` - String (peer’s endpoint) +- `peer_address` - String (peer’s endpoint) **Example**: @@ -425,12 +403,12 @@ print('# remove_peer', remove_peer) **Parameters**: - - `transaction` - JSON format transaction +- `transaction` - JSON format transaction -**Returns**: +**Returns**: - - `JSON` - - `RawTransaction` - hex string bytes generated by transaction information +- `JSON` + - `RawTransaction` - hex string bytes generated by transaction information **Example**: @@ -448,7 +426,6 @@ raw_transaction = aelf.create_raw_transaction(transaction) print('# create_raw_transaction', raw_transaction) ``` - ### 14. Send Raw Transaction **Web API Path**: `/api/blockchain/sendRawTransaction` @@ -457,9 +434,9 @@ print('# create_raw_transaction', raw_transaction) **Parameters**: - - `Transaction` - raw transaction - - `Signature` - signature - - `ReturnTransaction` - indicates whether to return the transaction +- `Transaction` - raw transaction +- `Signature` - signature +- `ReturnTransaction` - indicates whether to return the transaction **Example**: @@ -499,8 +476,8 @@ print('# send_raw_transaction', result) **Parameters**: - - `RawTransaction` - raw transaction - - `Signature` - signature +- `RawTransaction` - raw transaction +- `Signature` - signature **Example**: @@ -531,7 +508,6 @@ result = aelf.execute_raw_transaction(transaction_1) print('# execute_raw_transaction', result) ``` - ### 16. Get Merkle Path **Web API Path**: `/api/blockchain/merklePathByTransactionId?transactionId=` @@ -540,7 +516,7 @@ print('# execute_raw_transaction', result) **Parameters**: - - `transactionId` - String +- `transactionId` - String **Example**: @@ -552,7 +528,6 @@ merkle_path = aelf.get_merkle_path(transaction_id) print('# get_merkle_path', merkle_path) ``` - ### 17. Calculate Transaction Fee **Web API Path**: `/api/blockchain/calculateTransactionFee` @@ -561,15 +536,15 @@ print('# get_merkle_path', merkle_path) **Parameters**: - - `CalculateTransactionFeeInput` - JSON with the following structure: - - `RawTransaction` - String +- `CalculateTransactionFeeInput` - JSON with the following structure: + - `RawTransaction` - String -**Returns**: +**Returns**: - - `CalculateTransactionFeeOutput` - `json` - The json with the following structure : - - `Success` - Boolean - - `TransactionFee` - Array - - `ResourceFee` - Array +- `CalculateTransactionFeeOutput` - `json` - The json with the following structure : + - `Success` - Boolean + - `TransactionFee` - Array + - `ResourceFee` - Array **Example**: @@ -584,8 +559,6 @@ calculate_transaction_fee_output = aelf.calculate_transaction_fee(calculate_tran print('# calculate_transaction_fee', calculate_transaction_fee_output) ``` - - ### 18. Get Network Info **Web API Path**: `/api/net/networkInfo` @@ -601,8 +574,6 @@ network_info = aelf.get_network_info() print('# get_network_info', network_info) ``` - - ## AElf.client Use the API to see detailed results. @@ -619,16 +590,15 @@ aelf = AElf(url) genesis_contract_address = aelf.get_genesis_contract_address_string() ``` - ### 2. get_system_contract_address **Parameters:** - - `contract_name` - String: system contract’s name +- `contract_name` - String: system contract’s name **Returns:** - - `Address`: system contract’s address +- `Address`: system contract’s address **Example:** @@ -638,16 +608,15 @@ aelf = AElf(url) multi_token_contract_address = aelf.get_system_contract_address('AElf.ContractNames.Token') ``` - ### 3. get_system_contract_address_string **Parameters:** - - `contract_name` - String: system contract’s name +- `contract_name` - String: system contract’s name **Returns:** - - `String`: system contract’s address +- `String`: system contract’s address **Example:** @@ -657,14 +626,13 @@ aelf = AElf(url) multi_token_contract_address_string = aelf.get_system_contract_address_string('AElf.ContractNames.Token') ``` - ### 4. create_transaction **Parameters:** - - `to_address` - Address or String: target contract’s address - - `method_name` - String: method name - - `params` - String: serialize parameters into String +- `to_address` - Address or String: target contract’s address +- `method_name` - String: method name +- `params` - String: serialize parameters into String **Example:** @@ -676,15 +644,14 @@ params.value = hashlib.sha256(contract_name.encode('utf8')).digest() transaction = aelf.create_transaction(genesisContractAddress, 'GetContractAddressByName', params.SerializeToString()) ``` - ### 5. sign_transaction Sign a transaction with the user’s private key. **Parameters:** - - `private_key` - String: user’s private key - - `transaction` - Transaction: transaction +- `private_key` - String: user’s private key +- `transaction` - Transaction: transaction **Example:** @@ -698,18 +665,17 @@ transaction = aelf.create_transaction(to_address_string, 'GetContractAddressByNa transaction = aelf.sign_transaction(private_key, transaction) ``` - ### 6. get_address_from_public_key Generate an address from a public key. **Parameters:** - - `public_key` - bytes: user’s public key +- `public_key` - bytes: user’s public key **Returns:** - - `Address` +- `Address` **Example:** @@ -718,18 +684,17 @@ aelf = AElf(url) address = aelf.get_address_from_public_key(public_key) ``` - ### 7. get_address_string_from_public_key Generate an address string from a public key. **Parameters:** - - `public_key` - bytes: user’s public key +- `public_key` - bytes: user’s public key **Returns:** - - `String` +- `String` **Example:** @@ -738,14 +703,11 @@ aelf = AElf(url) address = aelf.get_address_string_from_public_key(public_key) ``` - - ### 8. get_chain_id - **Returns:** - - `Number` +- `Number` **Example:** @@ -756,18 +718,16 @@ chain_id = aelf.get_chain_id() print('# get_chain_id', chain_id) ``` - - ### 9. get_formatted_address **Parameters:** - - `address` - Address: address +- `address` - Address: address **Returns:** - - `String` - +- `String` + **Example:** ```python @@ -777,7 +737,6 @@ formatted_address = aelf.get_formatted_address(address) print('formatted address', formatted_address) ``` - ### 9. is_connected Check whether the node is connected. @@ -789,13 +748,10 @@ aelf = AElf(url) is_connected = aelf.is_connected() ``` - - ## Tookkits.py AElfToolkit Encapsulate AElf and user’s private key. It simplifies the procedures of sending some transactions. You can find it in src/aelf/toolkits.py. - ### Create a Toolkit Create a Toolkit with AElfToolkit. @@ -811,7 +767,6 @@ private_key = PrivateKey(bytes(bytearray.fromhex(private_key_string))) toolkit = AElfToolkit('http://127.0.0.1:8000', private_key) ``` - ### Send a Transaction Send a CrossChainTransfer transaction using AElfToolkit. @@ -832,22 +787,19 @@ toolkit = AElfToolkit('http://127.0.0.1:8000', private_key) toolkit.cross_chain_transfer(to_address_string, symbol, amount, memo, to_chain_id) ``` - - ## Requirements - [Python](https://www.python.org/) - [Docker](https://www.docker.com/) - ## Support - [Node](https://hub.docker.com/r/aelf/node) ## About Contributing -Read out [contributing guide]. +Read out [contributing guide](../../../resources/contribution/index.md) ## About Version -[https://semver.org/](https://semver.org/) \ No newline at end of file +[https://semver.org/](https://semver.org/)